ZipCodeStack 0.1.3

ZipCodeStack .NET SDK

A lightweight C# client for the zipcodestack.com API providing search, distance, and status endpoints.

• Website: https://zipcodestack.com/

• License: MIT

Installation

dotnet add package ZipCodeStack

Quickstart

using System;
using System.Net.Http;
using System.Threading.Tasks;
using ZipCodeStack;

public class Example
{
  public static async Task Main()
  {
    var client = new ZipCodeStackClient("YOUR_API_KEY");

    var status = await client.GetStatusAsync();
    Console.WriteLine($"API up: {status.Up}, remaining: {status.QuotaRemaining}");

    var search = await client.SearchAsync("10001", country: "US");
    Console.WriteLine(search.FirstOrDefault?.City);

    var distance = await client.GetDistanceAsync("10001", "94105", country: "US", unit: "mi");
    Console.WriteLine($"Distance: {distance.Distance} {distance.Unit}");
  }
}

Configuration

using var http = new HttpClient();
var options = new ZipCodeStackOptions
{
  ApiKey = "YOUR_API_KEY",
  BaseUrl = "https://api.zipcodestack.com/v1", // default
  UseQueryApiKey = false,                         // default: use header
  ApiKeyHeaderName = "apikey",                // default
  ApiKeyQueryParameterName = "key"               // if UseQueryApiKey = true
};
var client = new ZipCodeStackClient(http, options);

• Authentication: Use header apikey: <KEY> by default or set UseQueryApiKey=true to pass ?apikey=<KEY>. See the official site for details on authentication, rate limits, and endpoints: https://zipcodestack.com/

API

• GetStatusAsync() → API status and quota info
• SearchAsync(code, country?) → zip/postal code information
• GetDistanceAsync(from, to, country?, unit="km") → distance between codes

All methods throw ZipCodeStackException on non-2xx responses with StatusCode, optional parsed Error, and RawContent.

Exceptions

try
{
  var info = await client.SearchAsync("invalid");
}
catch (ZipCodeStackException ex)
{
  Console.WriteLine($"Failed: {ex.StatusCode} {ex.Message}");
}

Building locally

# from repo root
dotnet build

Publishing to NuGet

Make sure you have NUGET_API_KEY set in your environment, then run:

# pack
dotnet pack ./src/ZipCodeStack/ZipCodeStack.csproj -c Release -o ./nupkgs

# push
dotnet nuget push ./nupkgs/ZipCodeStack*.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json

License

MIT © ZipCodeStack