Home/ Cities & Locations/ Get Cities

Cities & Locations

APIs to discover and select cities where experiences are available. The city's code field (ONDC city code) is required in SELECT, INIT, and CONFIRM.

# Get Cities

Returns a paginated, searchable list of active cities. Used for the city selector UI and for autocomplete when the user types a city name.

GET{{base_url}}/city

Bearer Token Required

Query Parameters

Field	Type	Required	Description
page	number	REQUIRED	Page number. Start with `1`.
limit	number	REQUIRED	Number of cities per page. Recommended: `10` or `20`.
name	string	OPTIONAL	Filter by city name (partial match). Example: `bengaluru` returns Bengaluru.

Response — 200 OK

{
  "data": {
    "cities": [
      {
        "id": "690db16605e92e251850e0c3",   // ← MongoDB ObjectId → use in GET /hero-sections/city/:id
        "slug": "karnataka-bengaluru",
        "code": "std:080",                   // ← ONDC city code → use in SELECT / INIT / CONFIRM
        "name": "Bengaluru",
        "state": "Karnataka",
        "image": { "downloadUrl": "https://...signed-s3-url..." },
        "isActive": true,
        "isTopCity": true,
        "tier": 1,
        "lat": 12.9719,
        "lng": 77.5936
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10
  }
}

Key Response Fields

Field	Description	Used In
id	MongoDB ObjectId of the city	GET /hero-sections/city/:id
code	ONDC city code (e.g., `std:080`, `std:011`). Critical for all ONDC transaction APIs.	SELECT, INIT → `cityCode`
lat / lng	City center coordinates	GET /items → latitude, longitude
isTopCity	Whether to feature prominently in city selector	UI display priority
image.downloadUrl	Pre-signed S3 URL (valid 24 hours)	City card images

Image URL Expiry: The downloadUrl is a pre-signed S3 URL valid for only 24 hours. Do not cache these URLs beyond their validity window. Re-call the API to refresh.

# Get Nearest City

Given GPS coordinates, returns the closest city with active experiences. Call this on app startup after the user grants location permission to automatically set their city context.

GET{{base_url}}/city/nearest-city

Bearer Token Required

Query Parameters

Field	Type	Required	Description
lat	number	REQUIRED	User's GPS latitude. Example: `28.6358`
lng	number	REQUIRED	User's GPS longitude. Example: `77.22445`

Response — 200 OK

{
  "data": {
    "id": "690db16605e92e251850de53",
    "slug": "delhi-delhi",
    "code": "std:011",            // ← Save as cityCode for ONDC transactions
    "name": "Delhi",
    "state": "Delhi",
    "image": { "downloadUrl": "https://..." },
    "isActive": true,
    "isTopCity": true,
    "latitude": 28.6358,
    "longitude": 77.22445,
    "distance": 0             // km from user's coordinates to city center
  }
}

Auto-detect city: Call this endpoint on app startup after location permission is granted. Use the returned code as cityCode when calling GET /items and all booking APIs. If distance = 0, the user is at the city center.

← PreviousCategories Next →Items & Experiences