States API

Use it in an application

When the country changes, clear the old state and city selections before requesting this endpoint. India returns 36 source subdivisions, including West Bengal with code WB.

5,320 source regions across countries; administrative levels vary.

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/states?country=IN");
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/states?country=IN · HTTP 200. This is a static documentation example, not a live playground result.

{
  "success": true,
  "data": [
    {
      "id": "csc-state-4023",
      "countryCode": "IN",
      "name": "Andaman and Nicobar Islands",
      "code": "AN",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4017",
      "countryCode": "IN",
      "name": "Andhra Pradesh",
      "code": "AP",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4024",
      "countryCode": "IN",
      "name": "Arunachal Pradesh",
      "code": "AR",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4027",
      "countryCode": "IN",
      "name": "Assam",
      "code": "AS",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4037",
      "countryCode": "IN",
      "name": "Bihar",
      "code": "BR",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4031",
      "countryCode": "IN",
      "name": "Chandigarh",
      "code": "CH",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4040",
      "countryCode": "IN",
      "name": "Chhattisgarh",
      "code": "CT",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4033",
      "countryCode": "IN",
      "name": "Dadra and Nagar Haveli and Daman and Diu",
      "code": "DH",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4021",
      "countryCode": "IN",
      "name": "Delhi",
      "code": "DL",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4009",
      "countryCode": "IN",
      "name": "Goa",
      "code": "GA",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4030",
      "countryCode": "IN",
      "name": "Gujarat",
      "code": "GJ",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4007",
      "countryCode": "IN",
      "name": "Haryana",
      "code": "HR",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4020",
      "countryCode": "IN",
      "name": "Himachal Pradesh",
      "code": "HP",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4029",
      "countryCode": "IN",
      "name": "Jammu and Kashmir",
      "code": "JK",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4025",
      "countryCode": "IN",
      "name": "Jharkhand",
      "code": "JH",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4026",
      "countryCode": "IN",
      "name": "Karnataka",
      "code": "KA",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4028",
      "countryCode": "IN",
      "name": "Kerala",
      "code": "KL",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4852",
      "countryCode": "IN",
      "name": "Ladakh",
      "code": "LA",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4019",
      "countryCode": "IN",
      "name": "Lakshadweep",
      "code": "LD",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4039",
      "countryCode": "IN",
      "name": "Madhya Pradesh",
      "code": "MP",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4008",
      "countryCode": "IN",
      "name": "Maharashtra",
      "code": "MH",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4010",
      "countryCode": "IN",
      "name": "Manipur",
      "code": "MN",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4006",
      "countryCode": "IN",
      "name": "Meghalaya",
      "code": "ML",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4036",
      "countryCode": "IN",
      "name": "Mizoram",
      "code": "MZ",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4018",
      "countryCode": "IN",
      "name": "Nagaland",
      "code": "NL",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4013",
      "countryCode": "IN",
      "name": "Odisha",
      "code": "OR",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4011",
      "countryCode": "IN",
      "name": "Puducherry",
      "code": "PY",
      "type": "union territory",
      "level": "1"
    },
    {
      "id": "csc-state-4015",
      "countryCode": "IN",
      "name": "Punjab",
      "code": "PB",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4014",
      "countryCode": "IN",
      "name": "Rajasthan",
      "code": "RJ",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4034",
      "countryCode": "IN",
      "name": "Sikkim",
      "code": "SK",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4035",
      "countryCode": "IN",
      "name": "Tamil Nadu",
      "code": "TN",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4012",
      "countryCode": "IN",
      "name": "Telangana",
      "code": "TG",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4038",
      "countryCode": "IN",
      "name": "Tripura",
      "code": "TR",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4022",
      "countryCode": "IN",
      "name": "Uttar Pradesh",
      "code": "UP",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4016",
      "countryCode": "IN",
      "name": "Uttarakhand",
      "code": "UK",
      "type": "state",
      "level": "1"
    },
    {
      "id": "csc-state-4853",
      "countryCode": "IN",
      "name": "West Bengal",
      "code": "WB",
      "type": "state",
      "level": "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": "source_subdivisions",
    "notice": "Source administrative levels vary. An empty result does not establish that a country has no subdivisions."
  }
}

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

This endpoint is not paginated. Countries returns the filtered reference list; States returns all source regions for one country. Do not send page or limit here.

Errors and troubleshooting

A 400 means the country is missing or unsupported. An empty successful response means no subdivisions are recorded in this snapshot; it is not proof that the country has no administrative divisions. Codes can be legacy upstream values rather than current ISO 3166-2 codes.

Example error for /api/v1/states?country=ZZ · HTTP 400:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "country must be a supported ISO alpha-2 code."
  }
}

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