TheCodeGuy.Postcode 1.0.0

TheCodeGuy.Postcode

A simple .NET client for The Code Guy Postcode API. UK postcode lookup, validation, nearest search, and autocomplete powered by ONS data.

Installation

dotnet add package TheCodeGuy.Postcode

Usage

using TheCodeGuy.Postcode;

// Create client with your API key
var client = new PostcodeClient("wt_your_api_key");

// Look up a postcode
var result = await client.LookupAsync("SW1A 1AA");
if (result != null)
{
    Console.WriteLine($"Country: {result.Country}");
    Console.WriteLine($"Coordinates: {result.Latitude}, {result.Longitude}");
}

// Validate a postcode
bool isValid = await client.ValidateAsync("SW1A 1AA");

// Bulk lookup (up to 100 postcodes)
var results = await client.BulkLookupAsync(new[] { "SW1A 1AA", "EC1A 1BB", "M1 1AE" });

// Find nearest postcodes to a location
var nearest = await client.NearestAsync(
    latitude: 51.5074,
    longitude: -0.1278,
    limit: 5,
    radiusMetres: 1000);

foreach (var pc in nearest)
{
    Console.WriteLine($"{pc.Postcode} - {pc.Distance}m away");
}

// Autocomplete suggestions
var suggestions = await client.AutocompleteAsync("SW1A", limit: 10);

Dependency Injection

Configure the client using dependency injection:

// In Program.cs or Startup.cs
services.AddPostcodeClient("wt_your_api_key");

// Or with custom options
services.AddPostcodeClient(options =>
{
    options.ApiKey = "wt_your_api_key";
    options.BaseUrl = "https://api.codeg.uy";
});

Then inject the client:

public class MyService
{
    private readonly PostcodeClient _postcodeClient;

    public MyService(PostcodeClient postcodeClient)
    {
        _postcodeClient = postcodeClient;
    }

    public async Task<string?> GetCountryForPostcode(string postcode)
    {
        var result = await _postcodeClient.LookupAsync(postcode);
        return result?.Country;
    }
}

API Methods

License

This client library is licensed under the MIT License - you are free to use, modify, and distribute it.

Note: This library connects to The Code Guy API service at https://api.codeg.uy. While the library itself is free, API usage may be subject to rate limits. See the API documentation for details.