Skip to main content
GET
/
v1
/
countries
/
{iso2}
/
states
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 4008,
    "name": "Maharashtra",
    "iso2": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.75147980",
    "longitude": "75.71388840",
    "timezone": "Asia/Kolkata"
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve all states, provinces, regions, and territories for a specific country using the country’s ISO2 code.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.

​
Path Parameters

​
iso2
string
required
ISO2 code of the country (e.g., “IN” for India, “US” for United States)
Trim and order results: Add ?fields= to limit columns returned, or ?sort= to order the list. Both are available on Supporter+ plans. See the Field Filtering & Sorting guide for syntax and per-entity sortable fields.

​
Authentication

​
X-CSCAPI-KEY
string
required
Your API key for authentication

​
Query Parameters

​
q
string
Search filter on name. Case-insensitive match on name and native fields. Minimum 2 characters. Requires Supporter+ plan. Without this parameter, all results are returned (no plan restriction for search).

​
Response

​
id
integer
Unique identifier for the state/province
​
name
string
Official name of the state/province
​
iso2
string
ISO2 code for the state/province
​
country_id
integer
Unique identifier of the parent country
​
country_code
string
ISO2 code of the parent country
​
latitude
string
Approximate latitude of the state/province
​
longitude
string
Approximate longitude of the state/province
​
timezone
string
IANA timezone identifier (e.g., "Asia/Kolkata")
Additional fields like fips_code, iso3166_2, type, level, parent_id, native, population, translations, and wikiDataId are returned on higher tiers. See Tier-Based Field Availability below.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 4008,
    "name": "Maharashtra",
    "iso2": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.75147980",
    "longitude": "75.71388840",
    "timezone": "Asia/Kolkata"
  }
]

​
Common Use Cases

Create dependent dropdowns where states populate based on country selection.
const populateStatesDropdown = async (countryCode) => {
  const states = await getStatesByCountry(countryCode);
  const select = document.getElementById('state-select');
  
  // Clear existing options
  select.innerHTML = '<option value="">Select State...</option>';
  
  states.forEach(state => {
    const option = document.createElement('option');
    option.value = state.iso2;
    option.textContent = state.name;
    select.appendChild(option);
  });
};

// Listen for country changes
document.getElementById('country-select').addEventListener('change', (e) => {
  populateStatesDropdown(e.target.value);
});
Validate state codes against specific countries.
const validateStateForCountry = async (countryCode, stateCode) => {
  const states = await getStatesByCountry(countryCode);
  return states.some(state => state.iso2 === stateCode);
};
Cache states by country as they rarely change. Use this endpoint instead of filtering all states for better performance.

​
Tier-Based Field Availability

TierPlansFields
BasicCommunity, Starter, Legacyid, name, iso2, country_id, country_code, latitude, longitude, timezone
CoordinatesSupporterAll Basic + fips_code, iso3166_2, type, level, parent_id, native, population
FullProfessional, BusinessAll Coordinates + translations, wikiDataId
See Pricing for plan details.