Lookup export

GET/v1/lookup/{type}/export

Accepts X-Api-Key · oauthClientCredentials · bearer

Bulk + delta export of one lookup type as NDJSON

The offline-sync mechanism, in two calls to this one route.Show more

The offline-sync mechanism, in two calls to this one route. ISSUE (no `sig`): without `since` it answers a handle to a full snapshot as of `asOfVersion`; with `since` a handle to only the records changed or tombstoned after it. DOWNLOAD: the handle's `url` is this same route on the platform's own origin with the query parameters `asOf`, `expires` and `sig` (plus `since` and `locale` as issued); a GET on it answers the NDJSON file itself, one LookupRecord per line, content type application/x-ndjson, header X-Export-As-Of-Version. The link is HMAC-signed and lives 15 minutes, and it is NOT presigned: the download still needs the caller's credential, like every lookup. A tampered link is 403 PERMISSION_DENIED details.reason EXPORT_URL_INVALID, an expired one EXPORT_URL_EXPIRED, and a dataset that moved since the link was issued 400 VALIDATION EXPORT_SNAPSHOT_SUPERSEDED (issue a new export). Tenant-filtered like every lookup; answered with Cache-Control no-store.

Path parameters

typestringRequired
Registered lookup type key

Query parameters

sinceintegerOptional
Per-type monotonic version from a previous export's asOfVersion; absent = full snapshot.Show more
Per-type monotonic version from a previous export's asOfVersion; absent = full snapshot. As built, a date-versioned dataset (version yyyyMMdd) also accepts an ISO-8601 date or instant here, read as "changed after the day before"; the schema stays integer so the change is additive, and a typed client sends the version. A version ahead of the dataset is 400 VALIDATION details.reason SINCE_AHEAD; an instant on a dataset that is not date-versioned is 400 VALIDATION SINCE_INSTANT_UNSUPPORTED.
localestringOptional
asOfintegerOptional
DOWNLOAD only — the asOfVersion the signed link was issued at; set by the platform in `url`, never by hand
expiresintegerOptional
DOWNLOAD only — link expiry, epoch seconds; set by the platform in `url`
sigstringOptional
DOWNLOAD only — the link's HMAC-SHA-256 signature (base64url); its presence makes the GET a download

Request body

This operation takes no request body.

Responses

200ISSUE: an export handle. DOWNLOAD: the NDJSON file (application/x-ndjson, one LookupRecord per line, header X-Export-As-Of-Version).LookupExport
400
VALIDATION: a malformed parameter (details.field, details.value), or details.reason SINCE_AHEAD (details.currentVersion), SINCE_INSTANT_UNSUPPORTED, or EXPORT_SNAPSHOT_SUPERSEDED on a download whose…Show more
VALIDATION: a malformed parameter (details.field, details.value), or details.reason SINCE_AHEAD (details.currentVersion), SINCE_INSTANT_UNSUPPORTED, or EXPORT_SNAPSHOT_SUPERSEDED on a download whose dataset moved since issue.
ApiErrorResponse
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403PERMISSION_DENIED: the caller lacks the route permission, or on a download details.reason EXPORT_URL_INVALID (signature does not verify) or EXPORT_URL_EXPIRED.ApiErrorResponse
404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
429
RATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry.Show more
RATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry. Every routed request is counted against two token buckets, the key's and the tenant's (all its keys together): 50 requests a second with a burst of 100 on the standard plan. Every travel verb except polling a search also spends from a supplier budget, per key and per tenant: 10 requests a second with a burst of 20, and a plan may add a daily quota of supplier calls. Answers carry the IETF RateLimit header fields for the tightest bucket consulted (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); a refusal adds Retry-After and details.scope (KEY or TENANT), details.budget (PLATFORM or SUPPLIER), details.reason (RATE or DAILY_QUOTA), details.tier and details.retryAfterMs. A sandbox may run with the limiter off, in which case none of these headers is sent. A search that is still warming is a different answer with a different meaning (keep polling). with the key-velocity check on, also details.reason VELOCITY_LIMIT, a soft breach of the API key's own scope (components/responses/VelocityLimited), nextAction slow_down.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400	VALIDATION since 30000 is ahead of the airports dataset, currently at 20887	not retryable
401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED The export link is not valid. Request a new export.	not retryable
404	NOT_FOUND searchRef SR-F-7b31d0a9 is unknown or has expired; re-search	not retryable
405	VALIDATION This method is not served.	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
429	RATE_LIMITED Too many requests for this key on the supplier budget. Wait for the Retry-After interval before trying again.	retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable