Our takes

Why we would rather answer with an error than a wrong guess

An API that always returns something, even for a request it cannot answer well, looks more capable on the surface than one that sometimes returns a clear error instead. The impression is misleading. A response that guesses at an answer rather than admitting uncertainty is not more useful. It is more dangerous, specifically because it looks exactly like a confident, correct response and gives the caller no signal to check further before acting on it.

We would rather return a clear error, or a response that plainly indicates a low-confidence or partial match, than silently substitute a best guess dressed up as a normal answer. This matters most for forward geocoding, reverse geocoding, and autocomplete, exactly the endpoints where a partial or ambiguous address can tempt a system into returning the closest plausible match rather than acknowledging that the input did not resolve cleanly. A closest plausible match presented as a normal result is the single most likely way for bad location data to end up embedded in a shipment, a service area check, or a customer record, because nothing about the response signals that anything was uncertain.

This is also part of why we are deliberately cautious about claiming a specific, verified accuracy figure for geocoding and autocomplete rather than asserting these are fully finished, proven features. A system confident enough to publish a specific accuracy number has to be equally confident about what happens on the inputs that number does not cover, and the honest answer, for any geocoding system, includes some share of addresses that should come back as unresolved or ambiguous rather than force-fit into an answer.

An error response costs something in the moment: it requires the calling application to handle a failure case instead of always getting a clean object back, and it can feel like a worse developer experience on the surface, since a guess that happens to be right looks identical to an error-free response and a guess that happens to be wrong looks identical too, until someone downstream notices. That is exactly the problem. A guess and a correct answer are indistinguishable from the outside, which is precisely why a system that cannot tell the difference internally should not paper over that gap by picking one and presenting it as certain.

We think this preference, a clear failure over a confident guess, should be a baseline expectation for any data API, not just ours. A caller can build real error handling around a system that tells the truth about what it does not know. No caller can build reliable error handling around a system that always answers, because there is no way to distinguish the requests it actually got right from the ones it silently guessed at and happened to land on the wrong side of.