curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&radius=25&kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&type=state&radius=300&min_population=1000000' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&country=IN&state=MH&limit=5' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const params = new URLSearchParams({ lat: '19.0760', lng: '72.8777', radius: '25' });
const response = await fetch(
`https://api.countrystatecity.in/v1/search/nearby?${params}`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const results = await response.json();
results.forEach((r) => console.log(`${r.name} — ${r.distance_km} km`));
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/search/nearby',
params={'lat': 19.0760, 'lng': 72.8777, 'radius': 25},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
for result in response.json():
print(f"{result['name']} — {result['distance_km']} km")
[
{
"id": 57606,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07600000",
"longitude": "72.87770000",
"population": 12442373,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q1156",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 0
},
{
"id": 57612,
"name": "Thane",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.21830000",
"longitude": "72.97810000",
"population": 1841488,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q210421",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 17.36
}
]
{
"status": "error",
"message": "Invalid query parameters: lat: lat must be between -90 and 90"
}
{
"status": "error",
"message": "Invalid query parameters: state: country is required when filtering by state"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "nearbySearch",
"currentTier": "supporter",
"requiredTier": "professional",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
Search Endpoints
Nearby Search
Find countries, states, and cities near a coordinate, ranked by straight-line distance
GET
/
v1
/
search
/
nearby
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&radius=25&kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&type=state&radius=300&min_population=1000000' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&country=IN&state=MH&limit=5' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const params = new URLSearchParams({ lat: '19.0760', lng: '72.8777', radius: '25' });
const response = await fetch(
`https://api.countrystatecity.in/v1/search/nearby?${params}`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const results = await response.json();
results.forEach((r) => console.log(`${r.name} — ${r.distance_km} km`));
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/search/nearby',
params={'lat': 19.0760, 'lng': 72.8777, 'radius': 25},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
for result in response.json():
print(f"{result['name']} — {result['distance_km']} km")
[
{
"id": 57606,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07600000",
"longitude": "72.87770000",
"population": 12442373,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q1156",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 0
},
{
"id": 57612,
"name": "Thane",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.21830000",
"longitude": "72.97810000",
"population": 1841488,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q210421",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 17.36
}
]
{
"status": "error",
"message": "Invalid query parameters: lat: lat must be between -90 and 90"
}
{
"status": "error",
"message": "Invalid query parameters: state: country is required when filtering by state"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "nearbySearch",
"currentTier": "supporter",
"requiredTier": "professional",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
Find countries, states, or cities near a
lat/lng coordinate. Results are ordered from nearest to farthest.
This is not address search. It does not:
- Find a street address
- Check whether a point is inside a country or state border
- Return country/state map shapes
- Calculate travel time or road distance
Availability: Professional and Business plans. Other plans receive
403. Compare plans, or see Trying it without a paid plan below.Authentication
string
required
Your API key for authentication
Query Parameters
number
required
Latitude of the search origin.
-90 to 90.number
required
Longitude of the search origin.
-180 to 180.string
default:"city"
What to search. One of
city, state, or country.string
Only return results from this country. Use a two-letter country code such as
IN or US. Do not use this with type=country.string
Only return cities from this state. This works only with
type=city and requires country.string
Only return this kind of city. This works only with
type=city. Choose settlement, administrative, section, or unknown. See City Types.integer
Only return results with at least this population. Use a whole number of
0 or more.number
default:"25"
Search radius in kilometers.
1–500.integer
default:"20"
Maximum number of results to return.
1–100.string
Add
localized_name and matched_locale to each result. Example: ja or pt-BR. Professional and Business plans only. See Localized Place Names.boolean
default:"false"
Include the full raw
translations JSON string. Professional and Business plans only.Response
Returns an array, nearest-first. Each item carries the standard fields for the entity at your plan’s data-access level, plus:number
Straight-line distance from your coordinate, in kilometers, rounded to two decimal places.
string
The city kind. Included only in city results.
string
The display name for
locale, when requested and available on your plan.string
The locale used for
localized_name, including fallback values such as native or en.State and city results always include
country_name (and, for cities, state_name), regardless of your plan’s data-access level — useful for display without a second lookup. This differs from Autocomplete, which instead always includes country_code/state_code on city results; nearby search doesn’t force those two.curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&radius=25&kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&type=state&radius=300&min_population=1000000' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/search/nearby?lat=19.0760&lng=72.8777&country=IN&state=MH&limit=5' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const params = new URLSearchParams({ lat: '19.0760', lng: '72.8777', radius: '25' });
const response = await fetch(
`https://api.countrystatecity.in/v1/search/nearby?${params}`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const results = await response.json();
results.forEach((r) => console.log(`${r.name} — ${r.distance_km} km`));
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/search/nearby',
params={'lat': 19.0760, 'lng': 72.8777, 'radius': 25},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
for result in response.json():
print(f"{result['name']} — {result['distance_km']} km")
[
{
"id": 57606,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07600000",
"longitude": "72.87770000",
"population": 12442373,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q1156",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 0
},
{
"id": 57612,
"name": "Thane",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.21830000",
"longitude": "72.97810000",
"population": 1841488,
"timezone": "Asia/Kolkata",
"wikiDataId": "Q210421",
"country_name": "India",
"state_name": "Maharashtra",
"distance_km": 17.36
}
]
{
"status": "error",
"message": "Invalid query parameters: lat: lat must be between -90 and 90"
}
{
"status": "error",
"message": "Invalid query parameters: state: country is required when filtering by state"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "nearbySearch",
"currentTier": "supporter",
"requiredTier": "professional",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
Trying it without a paid plan
The interactive API documentation uses a shared Playground plan. It is only for trying the endpoint in the docs. For your own app, choose a Professional or Business plan.Related Endpoints
- Autocomplete — type-ahead search by name, not location
- Fuzzy Search — typo-tolerant search by name
- Get Cities by Country — list cities, filterable by
?q=
csc nearby command for this endpoint.Was this page helpful?
⌘I