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

{
  "id": 4008,
  "name": "Maharashtra",
  "country_id": 101,
  "country_code": "IN",
  "iso2": "MH",
  "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 detailed information for a specific state or province using the country’s ISO2 code and the state’s ISO2 code.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.

​
Path Parameters

​
country_iso2
string
required
ISO2 code of the country (e.g., “IN”, “US”)
​
state_iso2
string
required
ISO2 code of the state/province (e.g., “MH” for Maharashtra, “CA” for California)
Trim response columns: Add ?fields=name,iso2,... to receive only the columns you need. Available on Supporter+ plans. See the Field Filtering & Sorting guide for syntax.

​
Authentication

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

​
Response

​
id
integer
Unique identifier for the state/province
​
name
string
Official name of the state/province
​
country_id
integer
Unique identifier of the parent country
​
country_code
string
ISO2 code of the parent country
​
iso2
string
ISO2 code for the state/province
​
latitude
string
Approximate latitude coordinate of the state/province center
​
longitude
string
Approximate longitude coordinate of the state/province center
​
timezone
string
IANA timezone identifier (e.g., "Asia/Kolkata")
​
type
string
Administrative division type (e.g., "state", "province", "region"). Coordinates tier and above.
Additional fields like fips_code, iso3166_2, 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/MH' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

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

​
Common Use Cases

Use coordinates for distance calculations and mapping.
const calculateDistance = (lat1, lng1, lat2, lng2) => {
  const R = 6371; // Earth's radius in km
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLng = (lng2 - lng1) * Math.PI / 180;
  
  const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
            Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
            Math.sin(dLng/2) * Math.sin(dLng/2);
  
  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
};

const getDistanceFromState = async (countryCode, stateCode, targetLat, targetLng) => {
  const state = await getStateDetails(countryCode, stateCode);
  return calculateDistance(
    parseFloat(state.latitude), 
    parseFloat(state.longitude),
    targetLat, 
    targetLng
  );
};
Validate administrative division types for data processing.
const isStateType = async (countryCode, stateCode, expectedType) => {
  const state = await getStateDetails(countryCode, stateCode);
  return state && state.type === expectedType;
};
Use this endpoint when you need precise geographical coordinates or want to validate specific state/country combinations.

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