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": "starter",
"requiredTier": "supporter",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
Search
Nearby Search
Find countries, states, and cities near a coordinate, ranked by straight-line distance
GET
/
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": "starter",
"requiredTier": "supporter",
"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: Supporter, Professional, and Business plans. Other plans receive
403. Compare plans, or see Trying it without a paid plan below.Response
Returns an array, nearest-first. Each item carries the standard fields for the entity at your planβs data-access level, plus: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": "starter",
"requiredTier": "supporter",
"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 Supporter plan or higher.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.Authorizations
API key for authentication. Get your free key at app.countrystatecity.in.
Query Parameters
Latitude of the search origin
Required range:
-90 <= x <= 90Example:
19.076
Longitude of the search origin
Required range:
-180 <= x <= 180Example:
72.878
Entity type to search
Available options:
city, state, country Example:
"city"
City classification filter. Valid only when type=city.
Available options:
settlement, administrative, section, unknown Example:
"settlement"
ISO 3166-1 alpha-2 country code. Invalid when type=country.
Required string length:
2Pattern:
^[A-Za-z]{2}$Example:
"IN"
State or province code for a city search. Requires country and is valid only when type=city.
Required string length:
1 - 20Example:
"MH"
Minimum population a result must have
Required range:
0 <= x <= 9007199254740991Example:
100000
Search radius in kilometers (1β500)
Required range:
1 <= x <= 500Example:
25
Maximum number of results (1β100)
Required range:
1 <= x <= 100Example:
20
Adds localized_name and matched_locale using exact locale β base language β native name β English name fallback. The English name, stable id, and distance stay unchanged. Supporter+ plans only.
Required string length:
2 - 7Pattern:
^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$Example:
"ja"
When true, includes the full translation JSON string. Supporter+ plans only.
Example:
true
Response
Matching results sorted from nearest to farthest
Entity ID
Example:
57606
English place name
Example:
"Mumbai"
Straight-line distance from the search origin in kilometers
Example:
3.42
Raw source type for a state or city. This is not the country/state/city query type. Available on the coordinates tier and above.
Example:
"city"
Derived city classification. Present on city results for every plan.
Available options:
settlement, administrative, section, unknown Example:
"settlement"
JSON string of translations. Supporter+ plans only, and only when include_translations=true is passed.
Localized display name selected by locale. The English name remains unchanged. Supporter+ plans only.
Example:
"γ γ³γγ€"
Translation or fallback used for localized_name: the exact locale, base language, native, or en. Supporter+ plans only.
Example:
"ja"
Country ISO2 code for countries or state ISO code for states. Not present on city results.
Example:
"IN"
Country ISO3 code. Present only on country results.
Example:
"IND"
Parent state code for city results. Available on the coordinates tier and above.
Example:
"MH"
Parent country code. Always present on state results; available on city results on the coordinates tier and above.
Example:
"IN"
Parent country name. Present on state and city results for every plan.
Example:
"India"
Parent state name. Present on city results for every plan; null when there is no parent state.
Example:
"Maharashtra"