PostalDataPI Node.js SDK

Official TypeScript/Node.js client for the PostalDataPI global postal code API. Look up, validate, and search postal codes across 70+ countries with sub-10ms response times.

Installation

npm install postaldatapi

Quick Start

import { PostalDataPI } from "postaldatapi";

const client = new PostalDataPI({ apiKey: "your-api-key" });

// Look up a US ZIP code
const result = await client.lookup("90210");
console.log(result.city);               // Beverly Hills
console.log(result.stateAbbreviation);   // CA

// Look up a German postal code
const de = await client.lookup("10115", { country: "DE" });
console.log(de.city);                    // Berlin

// Validate a UK postcode
const gb = await client.validate("SW1A", { country: "GB" });
console.log(gb.valid);                   // true

// Search by city name
const cities = await client.searchCity("Beverly Hills", { state: "CA" });
console.log(cities.postalCodes);         // ['90209', '90210', '90211', ...]

// Get rich metadata
const meta = await client.metazip("90210");
console.log(meta.meta.county);           // Los Angeles County
console.log(meta.meta.timezone);         // America/Los_Angeles
console.log(meta.latitude);             // 34.1031
console.log(meta.longitude);            // -118.4163

API Methods

client.lookup(postalCode, options?)

Returns city and state for a postal code.

client.validate(postalCode, options?)

Checks whether a postal code exists. Returns ValidateResult with .valid boolean.

client.searchCity(city, options?)

Finds postal codes matching a city name. options.state is required for US queries.

client.metazip(postalCode, options?)

Returns rich metadata: coordinates, county (US), timezone (US), and all available data source fields.

All methods accept { country?: string } in options. Country defaults to "US" if omitted.

Country Support

Pass any ISO 3166-1 alpha-2 country code: US, GB, DE, FR, CA, JP, AU, and 60+ more.

Error Handling

import { PostalDataPI, NotFoundError, AuthenticationError } from "postaldatapi";

const client = new PostalDataPI({ apiKey: "your-api-key" });

try {
  const result = await client.lookup("00000");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Postal code not found");
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  }
}

Error classes: AuthenticationError (401), NotFoundError (404), ValidationError (400), RateLimitError (429), InsufficientBalanceError (402), ServerError (5xx).

Configuration

const client = new PostalDataPI({
  apiKey: "your-key",
  baseUrl: "https://staging.postaldatapi.com",  // override for staging
  timeout: 30_000,  // milliseconds
});

Account Balance

Every response includes your current account balance:

const result = await client.lookup("90210");
console.log(`Remaining balance: $${result.balance.toFixed(2)}`);

TypeScript

Full TypeScript support with exported types:

import type { LookupResult, ValidateResult, MetazipResult } from "postaldatapi";

Requirements

• Node.js 18+ (uses native fetch)
• Zero runtime dependencies

License

MIT