Skip to content

Cities API

Endpoint

GET https://integrations.app.traveln.ai/api/v1/cities/?limit=20&offset=0&has_attractions_only=true&country={uuid}

List cities. Set has_attractions_only=true to only return Traveln-supported cities that have attractions data.

Authentication: Authorization: Api-Key <sso_hmac_secret>

Usage model: server-to-server only

Query parameters

Parameter Type Required Description
limit integer No Max items to return
offset integer No Items to skip for paging
search string No Search by city name
has_attractions_only boolean No When true, only cities with attractions data
hasAttractionsOnly boolean No Legacy camelCase alias for has_attractions_only
countries string No Repeatable country UUID filter
country string No Filter by country UUID
valid_for_trip boolean No Filter by trip-valid cities when supported upstream

Example requests

curl "https://integrations.app.traveln.ai/api/v1/cities/?limit=20&offset=0&has_attractions_only=true&country=UUID_VALUE" \
  -H "Authorization: Api-Key <sso_hmac_secret>" \
  -H "Accept: application/json"

const res = await fetch(
  "https://integrations.app.traveln.ai/api/v1/cities/?limit=20&offset=0&has_attractions_only=true&country=UUID_VALUE",
  {
    headers: {
      Authorization: "Api-Key <sso_hmac_secret>",
      Accept: "application/json",
    },
  }
)
const payload = await res.json()
console.log(payload)

import requests

res = requests.get(
    "https://integrations.app.traveln.ai/api/v1/cities/",
    params={
        "limit": 20,
        "offset": 0,
        "has_attractions_only": True,
        "country": "UUID_VALUE",
    },
    headers={
        "Authorization": "Api-Key <sso_hmac_secret>",
        "Accept": "application/json",
    },
    timeout=30,
)
payload = res.json()
print(payload)

Example response

{
  "success": true,
  "message": "Cities retrieved.",
  "data": {
    "count": 1,
    "next": "https://integrations.app.traveln.ai/api/v1/cities/?country=e50e73e1-003a-4127-bacc-8e562662b332&has_attractions_only=true&limit=20&offset=20",
    "previous": null,
    "results": [
      {
        "id": "ef14b0ed-87e8-4df0-b132-5a5829f9b568",
        "name": "Beirut",
        "coordinates": {
          "type": "Point",
          "coordinates": [
            35.5017767,
            33.8937913
          ]
        },
        "capital": "primary",
        "images": [
          "https://s3.me-south-1.amazonaws.com/traveln.media.data/cities/Lebanon/Beirut/beirut.jpg"
        ],
        "country": "e50e73e1-003a-4127-bacc-8e562662b332"
      }
    ]
  },
  "error": null
}

Error responses

  • 401 Unauthorized: missing or invalid integrations API secret.
  • 502 Bad Gateway: upstream API could not be reached.
  • 503 Service Unavailable: tenant backend API key is not configured.
  • Upstream 4xx and 5xx: returned with the same HTTP status and wrapped in the integrations error envelope.