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"
  },
  {
    "id": 4017,
    "name": "Karnataka",
    "iso2": "KA"
  },
  {
    "id": 4030,
    "name": "Tamil Nadu",
    "iso2": "TN"
  }
]
Retrieve all states, provinces, regions, and territories for a specific country using the country’s ISO2 code.

​
Path Parameters

​
iso2
string
required
ISO2 code of the country (e.g., “IN” for India, “US” for United States)

​
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
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 4008,
    "name": "Maharashtra",
    "iso2": "MH"
  },
  {
    "id": 4017,
    "name": "Karnataka",
    "iso2": "KA"
  },
  {
    "id": 4030,
    "name": "Tamil Nadu",
    "iso2": "TN"
  }
]

​
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.