Skip to content

Cities API

Endpoint

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

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

Authentication: Authorization: Api-Key <partner_key>

Query parameters

Parameter Type Required Description
limit integer No Max items to return
offset integer No Items to skip for paging
has_attractions boolean No When true, only cities with attractions data
country string No Filter by country UUID

Example requests

curl "https://api.backend.traveln.ai/v1/cities/?limit=20&offset=0&has_attractions=true&country=UUID_VALUE" \
  -H "Authorization: Api-Key <partner_key>"

const res = await fetch(
  "https://api.backend.traveln.ai/v1/cities/?limit=20&offset=0&has_attractions=true&country=UUID_VALUE",
  { headers: { Authorization: "Api-Key <partner_key>" } }
)
const data = await res.json()

import requests

res = requests.get(
    "https://api.backend.traveln.ai/v1/cities/",
    params={"limit": 20, "offset": 0, "has_attractions": True, "country": "UUID_VALUE"},
    headers={"Authorization": "Api-Key <partner_key>"},
)
data = res.json()

Example response

{
    "count": 21,
    "next": "http://dev.api.backend.traveln.ai/api/v1/cities/?country=e50e73e1-003a-4127-bacc-8e562662b332&has_attractions=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",
                "https://s3.me-south-1.amazonaws.com/traveln.media.data/cities/Lebanon/Beirut/beirut2.jpg",
                "https://s3.me-south-1.amazonaws.com/traveln.media.data/cities/Lebanon/Beirut/beirut3.jpg",
                "https://s3.me-south-1.amazonaws.com/traveln.media.data/cities/Lebanon/Beirut/beirut4.jpg"
            ],
            "country": "e50e73e1-003a-4127-bacc-8e562662b332"
        }
    ]
}

Error responses

  • 401 Unauthorized: missing/invalid Api-Key.
  • 403 Forbidden: key lacks permission.
  • 422 Validation Error: invalid query parameters.
  • 500 Server Error: unexpected error.