Documentation: How do you actually use this thing?

[Jaegermeiste]

Given Nuget, a barebones program.cs, and a string with an address, how do you get this thing off the ground?

[Leftyx]

Once you have installed the package you should do something like this:

var libPostalDataFolder = "<folder libpostal>";

var config = new LibPostalConfiguration
{
    DataDirectory = libPostalDataFolder,
    ParserDataDirectory = libPostalDataFolder,
    LanguageClassifierDataDirectory = libPostalDataFolder,
    PaserOptions = new ParserOptions
    {
    	Country = "gb",
        Language = "en",
    }
};

var libPostalClient = new LibPostalClient(config);

List<KeyValuePair<string, string>> result = await libPostalClient.ParseAddressAsync(content);

The key should correspond to the labels you can find here

You could probably skip the configuration where you provide the folder to the LibPostal files.
I have included those cause I use an improved model I found here.

[chunty]

Here's a basic program.cs you can run.

WARNING: The first build will be slow because it downloads a zip file of the address data (I think)

using Humanizer;
using NEL.LibPostalClient.Clients;
using NEL.LibPostalClient.Models.Brokers.LibPostal;
using System.Text.Json;


var addresses = args.Length > 0
	? new[] { string.Join(' ', args) }
	: new[]
	{ 
		"12, High Street, Little Houghton, Northamptonshire, AB1 2CD",
		"The Cottage, Bogus Street, Not a place, Faketown, AB2 3FG" // Demo of what happens for a completely bogus address
	};
var dataDirectory = Path.Combine(AppContext.BaseDirectory, "Data");

var config = new LibPostalConfiguration
{
    DataDirectory = dataDirectory,
    ParserDataDirectory = dataDirectory,
    LanguageClassifierDataDirectory = dataDirectory,
    PaserOptions = new ParserOptions
    {
        Country = "gb",
        Language = "en"
    }
};

var client = new LibPostalClient(config);
foreach (var address in addresses)
{
    var parsedParts = await client.ParseAddressAsync(address);

    // Map all the different properties returned as listed in https://github.com/openvenues/libpostal to my address model
    var mapped = MapAddress(parsedParts);
    Console.WriteLine($"Input: {address}");
    Console.WriteLine();
    Console.WriteLine(JsonSerializer.Serialize(mapped, new JsonSerializerOptions { WriteIndented = true }));
	Console.WriteLine(new string('-', 50));
}

static AddressParseResult MapAddress(IEnumerable<KeyValuePair<string, string>> parts)
{
    var partList = parts.Select(part => new KeyValuePair<string, string>(part.Key, FormatPartValue(part.Key, part.Value))).ToList();
    var values = partList
        .GroupBy(part => part.Key, StringComparer.OrdinalIgnoreCase)
        .ToDictionary(group => group.Key, group => group.Select(part => part.Value).ToList(), StringComparer.OrdinalIgnoreCase);

    string? First(string key) => values.TryGetValue(key, out var items) ? items.FirstOrDefault() : null;

    var unitParts = new[]
    {
	    First("po_box"),
	    First("metro_station"),
	    First("unit"),
	    First("level"),
	    First("entrance"),
	    First("staircase")
    }.Where(value => !string.IsNullOrWhiteSpace(value));

    var houseParts = unitParts.ToList();
    var house = new[]
    {
	    First("building"),
	    First("house")
    }.FirstOrDefault(value => !string.IsNullOrWhiteSpace(value));

    if (!string.IsNullOrWhiteSpace(house))
    {
        houseParts.Add(house);
    }

    var mappedKeys = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
    {
        "unit",
        "level",
        "staircase",
        "entrance",
        "metro_station",
        "po_box",
        "house",
        "building",
        "house_number",
        "road",
        "suburb",
        "city_district",
        "city",
        "state_district",
        "state",
        "country_region",
        "island",
        "country",
        "world_region",
        "postcode",
        "postal_code"
    };

    var addressDto = new AddressDto
    {
        HouseName = string.Join(' ', houseParts.Select(value => FormatPartValue("house", value))),
        RoadNumber = FormatPartValue("house_number", First("house_number") ?? string.Empty),
        RoadName = FormatPartValue("road", First("road") ?? string.Empty),
        Area = FormatPartValue("suburb", First("suburb") ?? First("city_district") ?? string.Empty),
        Town = FormatPartValue("city", First("city") ?? string.Empty),
        County = string.Join(' ', new[]
        {
            First("state_district"),
            First("state"),
            First("country_region")
        }.Where(value => !string.IsNullOrWhiteSpace(value)).Select(value => FormatPartValue("state", value))),
        Country = string.Join(' ', new[]
        {
            First("island"),
            First("country"),
            First("world_region")
        }.Where(value => !string.IsNullOrWhiteSpace(value)).Select(value => FormatPartValue("country", value))),
        PostCode = FormatPartValue("postcode", First("postcode") ?? First("postal_code") ?? string.Empty)
    };

    var extras = partList
        .Where(part => !mappedKeys.Contains(part.Key))
        .GroupBy(part => part.Key, StringComparer.OrdinalIgnoreCase)
        .ToDictionary(
            group => group.Key,
            group => group.Select(part => part.Value).ToArray(),
            StringComparer.OrdinalIgnoreCase);

    return new AddressParseResult(addressDto, partList.ToArray(), extras);
}

// The library converts everything to lower case - I wanted Title Case except for post code
static string FormatPartValue(string key, string? value)
{
    var text = value ?? string.Empty;

    if (string.IsNullOrWhiteSpace(text))
    {
        return string.Empty;
    }

    if (key.Equals("postcode", StringComparison.OrdinalIgnoreCase) ||
        key.Equals("postal_code", StringComparison.OrdinalIgnoreCase))
    {
        return text.ToUpperInvariant();
    }

    if (key.Equals("website", StringComparison.OrdinalIgnoreCase) ||
        key.Equals("phone", StringComparison.OrdinalIgnoreCase))
    {
        return text;
    }

    return text.Titleize();
}

public sealed record AddressParseResult(
    AddressDto Address, // My dto
    KeyValuePair<string, string>[] RawParts, // What I was given
    IReadOnlyDictionary<string, string[]> ExtraParts); // Stuff I don't map


public class AddressDto
{
	public string HouseName { get; set; } = string.Empty;
	public string RoadNumber { get; set; } = string.Empty;
	public string RoadName { get; set; } = string.Empty;
	public string Area { get; set; } = string.Empty;
	public string Town { get; set; } = string.Empty;
	public string County { get; set; } = string.Empty;
	public string Country { get; set; } = string.Empty;
	public string PostCode { get; set; } = string.Empty;
}