zipcodestack-js

Node.js client for the zipcodestack.com API.

• Website: https://zipcodestack.com/

This SDK wraps the public endpoints and supports authentication via apikey header (default) or apikey query parameter.

Installation

npm install zipcodestack-js
# or
yarn add zipcodestack-js
# or
pnpm add zipcodestack-js

Quickstart

import ZipcodestackClient from 'zipcodestack-js';

const client = new ZipcodestackClient({ apiKey: process.env.ZIPCODESTACK_API_KEY });

// Search by postal code and country
const result = await client.search({ postal_code: '10001', country: 'US' });
console.log(result);

// Compute distance between two postal codes
const dist = await client.distance({ from: '10001', to: '94105', unit: 'mi' });
console.log(dist);

// Get API status/quota
const status = await client.status();
console.log(status);

Authentication

You can pass your API key via an apikey header (default) or as a query parameter.

// Header-based (default) uses: apikey: <your_api_key>
const client = new ZipcodestackClient({ apiKey: 'your_api_key' });

// Query-param based
const clientQueryAuth = new ZipcodestackClient({ apiKey: 'your_api_key', authInQuery: true });

API

All methods return parsed JSON (as returned by the API). Errors throw with error.status and error.details.

• search(params)

  • Example: { postal_code: '10001', country: 'US' }
  • For full parameter options, refer to the official site: https://zipcodestack.com/

• distance(params)

  • Example: { from: '10001', to: '94105', unit: 'mi' }

• status()

  • Retrieves API availability and quota information.

Configuration

const client = new ZipcodestackClient({
  apiKey: 'your_api_key',
  baseUrl: 'https://zipcodestack.com/api',
  authInQuery: false,
  timeoutMs: 10_000,
  defaultHeaders: { 'X-App': 'my-app' }
});

Error handling

try {
  const res = await client.search({ postal_code: '10001', country: 'US' });
} catch (err) {
  console.error('Request failed', err.status, err.details);
}

License

MIT