Cities API

Use it in an application

For a West Bengal locality picker, request country=IN and state=WB. Search Kolkata to narrow the list, then save the source ID alongside the selected name. Use pagination instead of fetching every locality upfront.

India only: 4,335 source localities. Incomplete, including within India; some records are districts.

Query parameters

Unknown and repeated parameters are rejected. Send no request body. Optional empty playground fields are omitted from the URL. The server validates that country/state codes exist, not just their format.

Example request

Configured production base: https://techidea.online. These snippets show the contract, not a claim that a public deployment is live. Check the HTTP status before using data.

const response = await fetch("https://techidea.online/api/v1/cities?country=IN&state=WB&search=Kolkata&page=1&limit=2");
const body = await response.json();
if (!response.ok) {
  throw new Error(body.error?.message || "HTTP " + response.status);
}
console.log(body);

Example JSON response

Recorded from the M4A handler for /api/v1/cities?country=IN&state=WB&search=Kolkata&page=1&limit=2 · HTTP 200. This is a static documentation example, not a live playground result.

{
  "success": true,
  "data": [
    {
      "id": "csc-city-142001",
      "countryCode": "IN",
      "stateCode": "WB",
      "name": "Kolkata"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 1,
    "totalPages": 1
  },
  "meta": {
    "dataset": {
      "source": "Countries States Cities Database — Darshan Gada and contributors",
      "license": "ODbL-1.0",
      "revision": "a5078ba91302953cf17ff39c683344e09072c2f8",
      "manifest": "/datasets/v1/manifest.json",
      "licenseUrl": "/datasets/v1/LICENSE.txt"
    },
    "coverage": {
      "status": "partial",
      "includedCountries": [
        "IN"
      ],
      "notice": "Only source localities assigned to Indian states are included. Coverage is incomplete, including within India; some records describe districts. Empty results do not imply no cities exist."
    }
  }
}

Record fields

The envelope includes success, data and meta. Location metadata identifies the dataset and coverage; sample metadata marks the data fictional and records the seed.

Pagination

Defaults are page=1 and limit=20, with limit capped at 100 and page at 10000. The pagination object contains page, limit, total and totalPages. Filtering happens before pagination; an out-of-range page returns an empty array with the real total. No cursors are implemented.

Errors and troubleshooting

A valid non-Indian country/state pair returns an empty array with coverage.status=not_included. Indian results report partial coverage. An invalid state/country pair returns 400. Zero matches never establishes that a place does not exist.

Example error for /api/v1/cities?country=IN&state=ZZ · HTTP 400:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "state must match a subdivision code returned for this country."
  }
}

Access and rate limits

The prepared Nginx defaults are 60 requests/minute/IP with burst 20, a global 50 requests/second budget and 10 concurrent connections/IP. These are configurable deployment defaults, not verified live limits. A 429 includes Retry-After. The playground waits before permitting another request; your integration should also honor that header.

The browser sends no gateway token. Production defaults to disabled until the private Nginx gateway is configured; a direct request can return 503. CORS defaults to anonymous wildcard reads but can be restricted to exact origins. Do not send credentials. Responses are no-store with a default 256 KiB server cap. Read access and launch requirements →

Data source, license and limitations

Source: Countries States Cities Database by Darshan Gada and contributors, pinned revision a5078ba91302953cf17ff39c683344e09072c2f8. The adapted reference files are distributed under ODbL 1.0. Names, codes and locality coverage are source records, not an authoritative address or legal-boundary service.

Dataset manifest and hashes · ODbL license · Upstream source

Snapshot updates are reviewed manually. Region codes can be legacy values, and IDs are not guaranteed permanent across versions. Cities are India-only and incomplete. No external data provider is called on each request.

Related APIs