GET
Ctrip Destination Lookup API
Find the city_id used by Ctrip hotel search from a city name and optional country.
Endpoint
GET https://api.stayapi.com/v1/ctrip/destinations/lookup
Authenticate with your StayAPI key in the X-API-Key header.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Required | City name in English or Chinese, 2–100 characters. Whitespace is trimmed. |
| country | string | Optional | Exact English or provider-localized country name, 2–100 characters. Case-insensitive; ISO codes and guessed aliases are not supported. |
| limit | integer | Optional | Suggestions to return, 1–15. Default 10. Does not suppress ambiguity checks. |
Request example
curl "https://api.stayapi.com/v1/ctrip/destinations/lookup?query=Hangzhou&country=China&limit=10" \
-H "X-API-Key: YOUR_API_KEY"Success response
{
"success": true,
"query": "Hangzhou",
"city_id": 17,
"name": "杭州",
"name_en": "Hangzhou",
"country": "中国",
"suggestions": [{
"city_id": 17,
"name": "杭州",
"name_en": "Hangzhou",
"display_name": "杭州, 浙江, 中国",
"province": "浙江",
"country": "中国",
"type": "domestic_city",
"search_url": "https://hotels.ctrip.com/hotels/list?cityId=17"
}],
"returned": 1
}
Limits and errors
- Names, province and country labels may be localized or null. A successful city_id is a city identifier, not a hotel or region identifier.
- HTTP 409 DESTINATION_AMBIGUOUS means several cities match. Inspect suggestions and candidate_count; reducing limit to 1 does not force a match. Add country or select a verified city_id.
- HTTP 422 DESTINATION_NOT_CITY identifies a region or island. The destination object includes region metadata and city_suggestions; suggestions contains typed city children when available. Do not use a region ID as city_id.
- For example, Murcia with country=Spain can return 422 with the municipality city_id 3496 among city_suggestions; inspect the typed child rather than assuming the province is a city.
- HTTP 404 DESTINATION_NOT_FOUND means no city matched. Invalid inputs return 400/422; upstream failures return 502 or 503. Errors are never successful empty city resolutions.
- Errors are non-2xx RFC 7807 Problem Details responses with
provider: "ctrip"and a correlation id.