My Geocode

Guides

Set up a fallback when a lookup returns no result

· 2 min read · My Geocode · #error-handling#fallback#edge-cases

A request that returns successfully with no useful result inside it is easy to mishandle, because it does not look like a failure at the HTTP level, it just does not have the answer you were hoping for.

What an empty result looks like

A forward geocoding search for something too vague or entirely fictional returns a 200 status with an empty results array, not an error code.

GET /v1/forward?q=xyzzy nonexistent place&limit=1
{
  "status": "ok",
  "query": "xyzzy nonexistent place",
  "results": []
}

An IP lookup for an address in an unallocated or private range returns found: false rather than an error, along with whatever fields it can still populate.

{
  "status": "ok",
  "ip": "10.0.0.5",
  "version": 4,
  "found": false
}

Building an explicit fallback path

Check for an empty results array, or found: false, as its own branch in your code, separate from both the success path and the error handling path for 4xx and 5xx responses. Decide deliberately what happens next: ask the user to refine their input, fall back to a broader search with a higher limit, or show a clear "location not found" message rather than a blank space or a misleading default value.

Common causes worth checking for first

A genuinely nonexistent place is one cause, but a poorly formatted input string, a typo, or a query that mixed languages or scripts unexpectedly can also produce an empty result for an address that actually exists. Before assuming the location itself does not exist, consider whether normalizing the input or trying a version with the countries parameter set would resolve it.

Logging empty results separately

Track how often your integration hits an empty result path, separately from your error rate. A rising rate of empty results often points to a data quality problem upstream, in how addresses are being collected or formatted, rather than anything wrong with the lookup itself.

Cost of a no-result lookup

An empty result still costs one request, the same as a successful match, since the lookup was performed either way. There is no separate discounted rate for a lookup that comes back empty.

Treating an empty result as its own deliberate outcome, rather than an afterthought bolted onto error handling, makes an integration noticeably more solid. The errors page covers actual error responses, while empty results are documented alongside each endpoint's normal response shape, such as the forward geocoding docs.

More in Guides