Configuration

Configure the listingsapi-js client: API key resolution, base URL overrides, timeouts, and automatic retries.

Constructor options

ListingsAPI accepts a single, fully optional options object:

import { ListingsAPI } from 'listingsapi-js';
 
const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env
 
// Every default spelled out:
const custom = new ListingsAPI({
apiKey: process.env.LISTINGSAPI_KEY,
baseUrl: 'https://listingsapi.com',
timeout: 240000,   // 4 minutes per attempt
maxRetries: 2,     // up to 3 attempts total
});

API key resolution

Never hardcode the key in source. The zero-argument constructor reads LISTINGSAPI_KEY from the environment:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Or pass a key you fetched from a secrets manager:

import { getSecret } from './secrets.js';
 
const apiKey = await getSecret('LISTINGSAPI_KEY');
const client = new ListingsAPI({ apiKey });

If no key is found in either place, the constructor throws AuthenticationError immediately, before any request is made.

Base URL override

Point the client at an internal proxy or a staging environment:

const client = new ListingsAPI({
baseUrl: 'https://listings-proxy.internal.example.com',
});

Trailing slashes are stripped automatically, so 'https://listingsapi.com/' and 'https://listingsapi.com' behave the same.

Timeouts

Every attempt is wrapped in AbortSignal.timeout(timeout) internally (Node 18+), so you do not need your own AbortController around SDK calls. The default is 240000 ms (4 minutes) per attempt.

A timed-out attempt counts as a connection failure: the client retries it while attempts remain, and the final failure throws APIConnectionError. Lower the timeout for latency-sensitive paths:

const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt

Automatic retries

The client retries responses with status 429, 500, 502, 503, and 504, plus network-level failures (DNS errors, refused connections, timeouts). With the default maxRetries: 2, each call makes up to 3 attempts.

The delay before each retry:

1. If the response carries a Retry-After header with a positive number of seconds, the client waits exactly that long.
2. Otherwise it backs off exponentially: 500 ms before the first retry, doubling for each retry after that (1 s, 2 s, and so on).

Network failures are retried immediately, without a delay. Once attempts run out, the last response becomes a typed error (RateLimitError, InternalServerError, and friends; see Error handling), and an exhausted network failure throws APIConnectionError.

// Fail fast and own the retry policy yourself:
const client = new ListingsAPI({ maxRetries: 0 });

Location IDs

Anywhere the SDK takes a location ID, numeric IDs are encoded automatically to the API's base64 form (Location:<id>), and already encoded IDs pass through unchanged. The helper is exported if you need the encoded form yourself:

import { encodeLocationId } from 'listingsapi-js';
 
encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='
encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is

Header format

Every request is authenticated with:

Authorization: API <your-key>
Content-Type: application/json

The SDK sets these headers automatically on every call. You do not need to configure them.

TypeScript project setup

The SDK is TypeScript-first with bundled types, so there is no separate @types package to install. Pin the version for reproducible builds:

npm install listingsapi-js@0.3.0

A minimal tsconfig.json for a Node 18+ project:

{
"compilerOptions": {
  "target": "ES2022",
  "module": "Node16",
  "moduleResolution": "Node16",
  "strict": true,
  "outDir": "dist"
}
}

For ESM projects with "type": "module" in package.json, use "module": "Node16" and "moduleResolution": "Node16". For CJS projects, "module": "CommonJS" and "moduleResolution": "Node" work fine; the package ships both builds, and CommonJS code loads it with const { ListingsAPI } = require('listingsapi-js').

Using without TypeScript

listingsapi-js compiles to plain JavaScript with zero runtime dependencies. You can import it from a .js or .mjs file without a build step:

import { ListingsAPI } from 'listingsapi-js';
 
const client = new ListingsAPI();
const page = await client.fetchAllLocations({ first: 5 });
for (const location of page.locations) {
console.log(location.name, location.city); // Acme Dental Midtown
}

Next steps

• Quickstart, your first working script
• Use cases, end-to-end recipes
• Error handling, the error hierarchy and retry patterns