City Not Found
city_not_found404
No locations matched your geocoding query. Try a different spelling, add a country, or pass lat/lon directly.
What this means
A geocoding request was structurally valid and the geocoder was available, but no locations matched the query string. The geocoder returned an empty result set. This is different from geocode_unavailable (the geocoder being down) or geocode_query_too_short (the query being rejected before submission).
When you'll see this
- A typo in the location name ("Mubai" instead of "Mumbai").
- An ambiguous query that the geocoder couldn't resolve ("Springfield" without state context).
- A non-English place name in a script the geocoder doesn't recognize.
- A historical place name that no longer exists in modern gazetteers.
- A very small village or hamlet not indexed by the geocoder.
Learn more about how this works
We use a third-party geocoder (currently Nominatim) for location-name → coordinates conversion. The geocoder has good coverage of major cities globally and reasonable coverage of smaller ones, but it's not exhaustive. When zero results come back, we surface that as city_not_found rather than guessing or falling back to a nearby match.
In practice: most occurrences of this error are user-input issues, not platform problems. The fix is usually on the input side — better spelling, more context, or skipping the geocoder entirely by passing lat/lon directly.
Example response
{
"success": false,
"error": "city_not_found",
"message": "No locations found matching your query.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/city_not_found",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Check the spelling of the location name. Many "city not found" errors are typos.
- Add country or region context: "Springfield, IL, USA" resolves better than "Springfield."
- If you have the latitude and longitude already (from a map picker, user database, etc.), skip the geocoder and pass them directly.
Don't retry the same query. Either reformulate the search or surface a location picker to the user.
Python:
Production handler
- Python
- TypeScript
import httpx
class CityNotFoundError(Exception):
"""Geocoder returned no matches for the query."""
def geocode(query, base_url, headers):
response = httpx.get(
f"{base_url}/v1/utils/geocode",
headers=headers,
params={"q": query},
timeout=10,
)
if response.status_code == 404:
body = response.json()
if body.get("error") == "city_not_found":
raise CityNotFoundError(
f"No location matched '{query}'. "
f"Try adding country, or use lat/lon directly."
)
response.raise_for_status()
return response.json()
class CityNotFoundError extends Error {}
async function geocode(query: string, baseUrl: string, headers: HeadersInit) {
const response = await fetch(
`${baseUrl}/v1/utils/geocode?q=${encodeURIComponent(query)}`,
{ headers },
);
if (response.status === 404) {
const body = await response.json();
if (body.error === "city_not_found") {
throw new CityNotFoundError(
`No location matched '${query}'. ` +
`Try adding country, or use lat/lon directly.`,
);
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Use an autocomplete UI for location input. Most "not found" cases are caught during typing instead of after submission.
- For known users in known locations, store coordinates after the first successful geocode. Re-geocoding the same string is wasteful and re-exposes you to this error.
- Encourage users to include country or state context in free-text location fields. Even short hints ("Paris, France" vs "Paris") dramatically reduce the not-found rate.
- For programmatic batch processing, validate locations against a sample geocoder run before committing to large batches.