curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
def get_state_details(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
state = response.json()
print(f"{state['name']} is located at {state['latitude']}, {state['longitude']}")
return state
else:
print('State not found')
return None
state = get_state_details('IN', 'MH')
const getStateDetails = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const state = await response.json();
console.log(`${state.name} is located at ${state.latitude}, ${state.longitude}`);
return state;
} else {
console.error('State not found');
}
};
getStateDetails('IN', 'MH');
<?php
function getStateDetails($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode == 200) {
$state = json_decode($response, true);
echo $state['name'] . " is located at " . $state['latitude'] . ", " . $state['longitude'] . "\n";
return $state;
} else {
echo "State not found\n";
return null;
}
}
$state = getStateDetails('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getStateDetails(countryCode, stateCode string) {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s", countryCode, stateCode)
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
res, _ := client.Do(req)
defer res.Body.Close()
if res.StatusCode == 200 {
body, _ := ioutil.ReadAll(res.Body)
var state map[string]interface{}
json.Unmarshal(body, &state)
fmt.Printf("%s is located at %s, %s\n",
state["name"], state["latitude"], state["longitude"])
} else {
fmt.Println("State not found")
}
}
func main() {
getStateDetails("IN", "MH")
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.Map;
public class StateDetails {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 200) {
Gson gson = new Gson();
Type mapType = new TypeToken<Map<String, Object>>(){}.getType();
Map<String, Object> state = gson.fromJson(response.body(), mapType);
System.out.println(state.get("name") + " is located at " +
state.get("latitude") + ", " + state.get("longitude"));
} else {
System.out.println("State not found");
}
}
}
require 'net/http'
require 'json'
def get_state_details(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_code}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'
response = http.request(request)
if response.code == '200'
state = JSON.parse(response.body)
puts "#{state['name']} is located at #{state['latitude']}, #{state['longitude']}"
state
else
puts 'State not found'
nil
end
end
state = get_state_details('IN', 'MH')
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata"
}
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata",
"fips_code": "16",
"iso3166_2": "IN-MH",
"type": "state",
"level": 1,
"parent_id": null,
"native": "महाराष्ट्र",
"population": 112374333
}
{
"error": "No State/Region found."
}
{
"error": "Unauthorized. You shouldn't be here."
}
States Endpoints
Get State Details
Retrieve detailed information for a specific state using country and state ISO2 codes
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'
import requests
def get_state_details(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
state = response.json()
print(f"{state['name']} is located at {state['latitude']}, {state['longitude']}")
return state
else:
print('State not found')
return None
state = get_state_details('IN', 'MH')
const getStateDetails = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const state = await response.json();
console.log(`${state.name} is located at ${state.latitude}, ${state.longitude}`);
return state;
} else {
console.error('State not found');
}
};
getStateDetails('IN', 'MH');
<?php
function getStateDetails($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode == 200) {
$state = json_decode($response, true);
echo $state['name'] . " is located at " . $state['latitude'] . ", " . $state['longitude'] . "\n";
return $state;
} else {
echo "State not found\n";
return null;
}
}
$state = getStateDetails('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getStateDetails(countryCode, stateCode string) {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s", countryCode, stateCode)
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
res, _ := client.Do(req)
defer res.Body.Close()
if res.StatusCode == 200 {
body, _ := ioutil.ReadAll(res.Body)
var state map[string]interface{}
json.Unmarshal(body, &state)
fmt.Printf("%s is located at %s, %s\n",
state["name"], state["latitude"], state["longitude"])
} else {
fmt.Println("State not found")
}
}
func main() {
getStateDetails("IN", "MH")
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.Map;
public class StateDetails {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 200) {
Gson gson = new Gson();
Type mapType = new TypeToken<Map<String, Object>>(){}.getType();
Map<String, Object> state = gson.fromJson(response.body(), mapType);
System.out.println(state.get("name") + " is located at " +
state.get("latitude") + ", " + state.get("longitude"));
} else {
System.out.println("State not found");
}
}
}
require 'net/http'
require 'json'
def get_state_details(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_code}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'
response = http.request(request)
if response.code == '200'
state = JSON.parse(response.body)
puts "#{state['name']} is located at #{state['latitude']}, #{state['longitude']}"
state
else
puts 'State not found'
nil
end
end
state = get_state_details('IN', 'MH')
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata"
}
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata",
"fips_code": "16",
"iso3166_2": "IN-MH",
"type": "state",
"level": 1,
"parent_id": null,
"native": "महाराष्ट्र",
"population": 112374333
}
{
"error": "No State/Region found."
}
{
"error": "Unauthorized. You shouldn't be here."
}
Retrieve detailed information for a specific state or province using the country’s ISO2 code and the state’s ISO2 code.
See Pricing for plan details.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.
Path Parameters
ISO2 code of the country (e.g., “IN”, “US”)
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
Your API key for authentication
Response
Unique identifier for the state/province
Official name of the state/province
Unique identifier of the parent country
ISO2 code of the parent country
ISO2 code for the state/province
Approximate latitude coordinate of the state/province center
Approximate longitude coordinate of the state/province center
IANA timezone identifier (e.g.,
"Asia/Kolkata")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'
import requests
def get_state_details(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
state = response.json()
print(f"{state['name']} is located at {state['latitude']}, {state['longitude']}")
return state
else:
print('State not found')
return None
state = get_state_details('IN', 'MH')
const getStateDetails = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const state = await response.json();
console.log(`${state.name} is located at ${state.latitude}, ${state.longitude}`);
return state;
} else {
console.error('State not found');
}
};
getStateDetails('IN', 'MH');
<?php
function getStateDetails($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode == 200) {
$state = json_decode($response, true);
echo $state['name'] . " is located at " . $state['latitude'] . ", " . $state['longitude'] . "\n";
return $state;
} else {
echo "State not found\n";
return null;
}
}
$state = getStateDetails('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getStateDetails(countryCode, stateCode string) {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s", countryCode, stateCode)
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
res, _ := client.Do(req)
defer res.Body.Close()
if res.StatusCode == 200 {
body, _ := ioutil.ReadAll(res.Body)
var state map[string]interface{}
json.Unmarshal(body, &state)
fmt.Printf("%s is located at %s, %s\n",
state["name"], state["latitude"], state["longitude"])
} else {
fmt.Println("State not found")
}
}
func main() {
getStateDetails("IN", "MH")
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.Map;
public class StateDetails {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 200) {
Gson gson = new Gson();
Type mapType = new TypeToken<Map<String, Object>>(){}.getType();
Map<String, Object> state = gson.fromJson(response.body(), mapType);
System.out.println(state.get("name") + " is located at " +
state.get("latitude") + ", " + state.get("longitude"));
} else {
System.out.println("State not found");
}
}
}
require 'net/http'
require 'json'
def get_state_details(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_code}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'
response = http.request(request)
if response.code == '200'
state = JSON.parse(response.body)
puts "#{state['name']} is located at #{state['latitude']}, #{state['longitude']}"
state
else
puts 'State not found'
nil
end
end
state = get_state_details('IN', 'MH')
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata"
}
{
"id": 4008,
"name": "Maharashtra",
"country_id": 101,
"country_code": "IN",
"iso2": "MH",
"latitude": "19.75147980",
"longitude": "75.71388840",
"timezone": "Asia/Kolkata",
"fips_code": "16",
"iso3166_2": "IN-MH",
"type": "state",
"level": 1,
"parent_id": null,
"native": "महाराष्ट्र",
"population": 112374333
}
{
"error": "No State/Region found."
}
{
"error": "Unauthorized. You shouldn't be here."
}
Common Use Cases
Location-Based Services
Location-Based Services
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
);
};
Administrative Type Validation
Administrative Type Validation
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
| Tier | Plans | Fields |
|---|---|---|
| Basic | Community, Starter, Legacy | id, name, iso2, country_id, country_code, latitude, longitude, timezone |
| Coordinates | Supporter | All Basic + fips_code, iso3166_2, type, level, parent_id, native, population |
| Full | Professional, Business | All Coordinates + translations, wikiDataId |
Was this page helpful?
⌘I