GET
KAYAK Destination Lookup API
Find KAYAK city IDs by name.
Copy for your AI agent
Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.
Overview
Find KAYAK city IDs by name. Use StayAPI with an X-API-Key through REST or MCP.
Scope
City-only suggestions, not a hotel search. Use the returned city_id in Buzz Calendar. limit controls the maximum number returned; total counts this response. No pagination, locale, or currency controls are supported.
Authentication
Send your StayAPI key in the X-API-Key header. Each successful request uses one credit and returns JSON; failures use RFC 7807 Problem Details.
Endpoint URL
GET https://api.stayapi.com/v1/kayak/destinations/lookup
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Required | City name, 2–100 characters after trimming surrounding whitespace. |
| limit | integer | Optional | Maximum suggestions, 1–50. Default: 10. |
Response schema
| Field | Type | Description |
|---|---|---|
| success | boolean | True on success. |
| total | integer | Number of entries returned. |
| destinations | array | City suggestions. |
| destinations[].city_id / name / display_name | string | City ID, name, and display label. |
| destinations[].country / country_code / region | string or null | Country name, country code, and region where available. |
| destinations[].latitude / longitude | number or null | City coordinates where available. |
| destinations[].timezone | string or null | City timezone where available. |
Errors and limitations
Errors use RFC 7807 Problem Details with provider: "kayak", an instance and correlation id.
- 400: invalid query, city identifier, or numeric limit outside 1–50.
- 422: required parameter missing or limit is not an integer.
- 401/402/429: authentication, credit, or rate-limit error.
- 502/503/504: source data temporarily unavailable or request could not complete. Errors are never returned as successful 2xx responses.