Tools & SDKs

TypeScript / JavaScript SDK

The official @scoutingapi/sdk — fully typed against the unified schema, with auth, automatic retries, cursor auto-pagination and async-job polling built in.

Install

Install @scoutingapi/sdk

npm install @scoutingapi/sdk

Quickstart

Construct one client with your key and call any endpoint. Every response is typed from @scoutingapi/schema, which the SDK re-exports — so data and meta are fully typed with no drift.

index.ts

import { ScoutingApiClient } from '@scoutingapi/sdk';

const scout = new ScoutingApiClient({ apiKey: process.env.SCOUTINGAPI_KEY });

// Search — fully typed against the unified schema
const { data, meta } = await scout.search({
  location: 'Split, HR',
  checkIn: '2026-07-13',
  checkOut: '2026-07-20',
  platforms: ['airbnb', 'booking'],
});

for (const stay of data) {
  console.log(stay.name, stay.price?.totalPrice, stay.price?.currency);
}
console.log('charged', meta.creditsCharged, 'credits');

Methods

Method	Endpoint	Returns
`scout.search(params)`	`GET /v1/search`	ScoutingResponse<Property[]>
`scout.availability(params)`	`GET /v1/availability`	ScoutingResponse<Availability[]>
`scout.listing(platform, id, params?)`	`GET /v1/listing/{platform}/{id}`	ScoutingResponse<Property>
`scout.price(params)`	`GET /v1/price`	ScoutingResponse<Price>
`scout.priceCompare(params)`	`GET /v1/price-compare`	ScoutingResponse<PriceCompare>
`scout.reviews(params)`	`GET /v1/reviews`	ScoutingResponse<Review[]>
`scout.getJob(jobId) / waitForJob(jobId)`	`GET /v1/jobs/{jobId}`	JobResponse / ScoutingResponse
`scout.searchAll / reviewsAll(params)`	`auto-paginated`	Property[] / Review[]

What’s built in

Auth — the Bearer header on every request from your apiKey.
Automatic retries — 429 and retryable 5xx / network errors are retried with exponential backoff and jitter (tune with maxRetries).
Async jobs — a 202 is auto-polled to completion by default; opt out with { awaitJob: false } and use waitForJob().
Typed errors — every failure maps to a typed class (RateLimitedError, InsufficientCreditsError, …).
Config — baseUrl, timeoutMs, fetch injection and more.

Error handling

Typed errors

import {
  ScoutingApiClient,
  RateLimitedError,
  InsufficientCreditsError,
  isScoutingApiError,
} from '@scoutingapi/sdk';

const scout = new ScoutingApiClient({ apiKey: process.env.SCOUTINGAPI_KEY });

try {
  const { data } = await scout.priceCompare({
    name: 'Hotel X Sibenik',
    location: 'Sibenik, HR',
    checkIn: '2026-07-13',
    checkOut: '2026-07-20',
  });
  console.log('cheapest', data.min);
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // 402 — top up and retry
  } else if (err instanceof RateLimitedError) {
    // 429 — the client already retried with backoff; handle exhaustion
  } else if (isScoutingApiError(err)) {
    console.error(err.type, err.code, err.message, err.requestId);
  }
}

Auto-pagination

Paginate & collect

// Auto-paginate: iterate every page…
for await (const page of scout.searchPaginate({ location: 'Zadar, HR' })) {
  console.log(page.data.length, 'on this page');
}

// …or collect across pages, bounded by maxItems
const stays = await scout.searchAll({ location: 'Zadar, HR' }, { maxItems: 100 });
const reviews = await scout.reviewsAll(
  { platform: 'booking', listingId: 'abramovic2' },
  { maxItems: 60 },
);

Point it at the sandbox

Pass a scout_test_ key (or set baseUrl to a staging host) to develop against deterministic fixtures at zero credits. Additional language SDKs are a fast-follow — until then, the curl and Python examples cover every endpoint.