Skip to main content
Server

Node.js SDK

Geocoding from TypeScript or JavaScript. Install, authenticate, and make your first call.

The Node.js SDK includes typed requests, normalized results, and optional Google/HERE fallbacks. It uses native fetch and has no runtime dependencies.

Installation​

Requires Node.js 22+. ESM, CommonJS, and TypeScript declarations are included.

The package is not yet published. Build it from the repository:

Build the package
cd sdk/typescript
npm ci
npm pack

Install the generated tarball in your application. Replace the path with your checkout:

npm install /path/to/pelias/sdk/typescript/affordable-geo-apis-sdk-0.1.0.tgz

npm pack builds both module formats. Use the emitted filename if the version changes.

Quick start​

Create a client with your deployment URL and API key, then submit an address:

TypeScript
import { GeocodingClient } from '@affordable-geo-apis/sdk';

const client = new GeocodingClient({
  baseUrl: process.env.GEOCODING_BASE_URL!,
  apiKey: process.env.GEOCODING_API_KEY!,
});

const response = await client.geocode({
  street: '11 Wall Street',
  city: 'New York',
  state: 'NY',
  zip: '10005',
});

console.log(response.results);

results is an array of address candidates. Check that it is nonempty before selecting a candidate. A no-match request succeeds with an empty array.

For JavaScript, remove TypeScript's ! assertions. For CommonJS, use const { GeocodingClient } = require('@affordable-geo-apis/sdk') inside your application and await calls in an async function.

Authentication​

Set the primary URL and key in your backend environment:

Environment
export GEOCODING_BASE_URL='http://localhost:8000'
export GEOCODING_API_KEY='YOUR_API_KEY'

Pass both values to the constructor as shown above. The SDK sends the key in the apikey header. Use your assigned HTTPS URL in production; the base URL excludes /v1/geocode.

Available methods​

MethodUse
client.geocode(request, options?)Find coordinates for a street address
client.search(request, options?)Find addresses and places from one line of free text
client.reverseGeocode(request, options?)Find address candidates for coordinates
client.autocomplete(request, options?)Suggest addresses for partial text and a required country
client.resolveAutocomplete(suggestion, options?)Resolve the selected suggestion into one address

Geocode, search, and reverse geocode return Promise<GeocodingResponse>. Autocomplete returns Promise<AutocompleteResponse>; resolution returns Promise<GeocodingResult>. See the client reference for request and result types.

Common operations​

Free-text search​

const response = await client.search({
  q: '11 Wall Street, New York, NY',
  country: 'US',
  limit: 5,
});

console.log(response.results);

Search accepts one line of text, such as an address, place name, city, or ZIP code, and returns matches of any type. q is required (1 to 256 characters). country restricts results, near: { lat, lon } prefers nearby results, and limit is 1 to 40 (default 10). Use geocode when the address is already split into fields. See search.

Address autocomplete​

const response = await client.autocomplete({ q: '11 Wall', country: 'US', limit: 5 });
const suggestion = response.suggestions[0];
if (suggestion) {
  const address = await client.resolveAutocomplete(suggestion);
  console.log(address.label, address.lat, address.lon);
}

Keep the suggestion object unchanged until selection. Resolution calls only its provider and does not run fallback selection or use fallback budgets/circuits. See autocomplete.

Reverse geocoding​

const response = await client.reverseGeocode({
  lat: 40.7074,
  lon: -74.0113,
});

console.log(response.results);

Excluding a data source​

const response = await client.geocode({
  street: '11 Wall Street',
  city: 'New York',
  exclude_sources: ['osm'],
});

Exclusions affect primary candidates only. See data sources.

TypeScript types​

import type { AddressRequest, GeocodingResponse } from '@affordable-geo-apis/sdk';

const request: AddressRequest = { street: '11 Wall Street', city: 'New York' };
const response: GeocodingResponse = await client.geocode(request);

Configuration​

Provider fallbacks​

Add the providers you want to call, in order:

const client = new GeocodingClient({
  baseUrl: process.env.GEOCODING_BASE_URL!,
  apiKey: process.env.GEOCODING_API_KEY!,
  confidenceThreshold: 0.8,
  fallbackBudget: { maxRequests: 1000 },
  fallbacks: [
    { provider: 'google', apiKey: process.env.GOOGLE_MAPS_API_KEY! },
    { provider: 'here', apiKey: process.env.HERE_API_KEY! },
  ],
});

The first nonempty backup wins when primary has no results, low confidence, or an eligible outage. Backups are off by default. A request with country: 'GB' skips primary and uses configured backups. See fallback policy for triggers, budgets, and circuit breakers.

Error handling​

import { GeocodingError } from '@affordable-geo-apis/sdk';

try {
  await client.geocode({ street: '11 Wall Street', city: 'New York' });
} catch (error) {
  if (!(error instanceof GeocodingError)) throw error;
  console.error(error.code, error.status, error.message);
  console.error(error.attempts);
}

Primary HTTP 4xx and malformed responses do not trigger fallback. Terminal provider errors include the complete attempt history.

Timeouts and cancellation​

Each provider request times out after ten seconds by default. Set constructor timeoutMs to change it. To bound the whole provider chain:

const response = await client.geocode(
  { street: '11 Wall Street', city: 'New York' },
  { signal: AbortSignal.timeout(15_000) },
);

Pass an AbortController signal for caller-controlled cancellation. Its abort reason propagates and stops the chain.

Retries​

The SDK does not retry automatically. If your application retries, bound the attempts and use backoff. Each call can consume primary and backup usage.

Raw provider response​

if (response.provider !== 'primary') {
  console.log(response.providerResponse);
}

providerResponse contains the full parsed body of the selected Google/HERE response. It is absent for primary results.

Reuse a client to share fallback budgets and circuits. No close method is required.

Client referenceConstructor options, types, and error fields.More examplesCancellation, fallbacks, and structured error handling.

For partial address entry, see address autocomplete.