API reference

Search

Create a search, read its ranked results, and fetch full rate sheets for individual products.

Check capabilities

Which product types are on sale in a market. Query: market, a 2-letter country code (default US). Anything else returns 400 validation_error.

{ "data": { "productTypes": ["hotel", "flight", "activity", "transfer"] }, "meta": {}, "error": null }

Create a search

Returns 201 with a searchId. Hotel searches return once the first batch is priced, or after about 4 seconds if that takes longer, and keep filling in the background; other products return complete. A hotel search that matches no hotels still returns 201 and completes with no results.

Common fields

Hotel fields

Flight fields

Activity fields

Transfer fields

{ "data": { "searchId": "66f1c0a2e4b0c1d2e3f4a5b6" }, "meta": {}, "error": null }

Errors: 400 validation_error, 400 unknown_destination (activities only), 400 invalid_hotel_selection, 404 not_found (unknown hotelId), 403 api_key_owner_missing.

Read results

data is an array of rows, ranked. Hotels are priced in batches of 300: within a batch, rows are cheapest first, with refundable rates preferred when prices are within 2%. Rows from later batches and slower sources come after.

"meta": {
  "nextCursor": "MjA",
  "session": {
    "status": "partial",
    "batchProgress": { "done": 1, "total": 3 },
    "lateArrivals": 0,
    "supplierOutcomes": [
      { "supplier": "src-3fa1c2", "status": "success", "latencyMs": 812, "rateCount": 143 }
    ]
  }
}

meta.session.status is pending, partial (still filling), completed or failed. lateArrivals counts every row that arrived late from a slower source — re-read from the first page when it rises. It is absent until something arrives late.

Errors: 404 not_found, 403 forbidden (another agency's search), 400 invalid_cursor, 400 invalid_limit.

Get a hotel's rate sheet

Queries live inventory for one hotel in the search and returns every room and rate, as an array of rows in the same shape as results. :productId is the hotel's canonicalProductId. No body. It queries every source live, so it can take several seconds.

The rows it returns are fresh quotes, each valid for 20 minutes, and the search itself is extended by 20 minutes. Quote IDs you got earlier — from results or a previous rate sheet — keep their original expiry.

Errors: 400 invalid_product_type (not a hotel search), 410 search_expired, 404 not_found, 403 forbidden.

Get all options for a product

Every option the search saved for one product — all modalities and sessions of an activity, all vehicles for a transfer. For these it returns the rows you already have, with their original quote IDs: it doesn't query live inventory, create new quotes or extend the search. A product with no saved options returns an empty array. For hotels it behaves like the rate sheet above.

Errors: 410 search_expired, 404 not_found (unknown search), 403 forbidden.