Use cases

Verifying a delivery address before it ships

A failed furniture delivery is expensive in a way a failed parcel delivery is not. A truck, a two-person crew, and a scheduled window all get wasted when the address on the order does not lead anywhere useful, and a furniture retailer shipping large items on scheduled delivery windows was absorbing that cost several times a week.

Most of the failures traced back to the same root cause: an address that was typed correctly according to the customer but did not actually resolve to a deliverable location, whether because of a typo in the street name, a postal code that did not match the city entered, or an apartment number missing entirely. None of these are obvious from looking at the text of the address. They only become obvious when something tries to match that address against real geographic data.

The retailer added a check at order confirmation, before the order was ever handed to the delivery scheduling system. The address the customer entered was sent to /v1/forward, which attempts to match it and returns a location result along with an indication of match quality, showing how confidently the address resolved rather than pretending every input is equally reliable. Separately, the postal code the customer entered was checked against /v1/postcode, which looks up what that code corresponds to, catching the specific case where a postal code and a city name did not agree with each other, a mismatch that is easy for a customer to make by autofill error and very hard to catch by reading the order form.

Orders where both checks came back clean moved straight to scheduling. Orders where the address only partially matched, or where the postal code and city disagreed, got flagged for a quick confirmation call or email before a delivery window was ever booked. That single extra step, run automatically and taking effect before any truck cost was incurred, moved the correction earlier in the process, from "discovered by a crew standing at the wrong address" to "resolved by an email the same day the order was placed."

The retailer was careful about what it claimed to customers. A verification check like this confirms that an address is well-formed and geographically plausible. It does not confirm that a specific unit number exists inside a large apartment complex, or that the person ordering actually lives there, so the flagging logic was tuned to catch clearly broken addresses rather than to reject anything even slightly unusual, which would have created more false alarms than it solved.

Because the check ran once per order rather than per page view, volume was easy to predict and stayed well inside the free daily allowance for a retailer of this size, with prepaid credit covering any overflow during a sales event. The return on the change showed up directly in fewer wasted delivery slots, which is a cost easy to measure and easy to justify against a very small per-request price.

Documentation for both endpoints, including how match quality is represented, is at /docs/forward-geocoding/ and /docs/postal-code-lookup/.