Geocoding APIs can be broadly split two ways: Forward geocoding turns free text (like an address or place name) into coordinates, and reverse geocoding goes the opposite direction. Understanding the distinction between the two styles is relatively straightforward, but choosing the right endpoint and parameters can make a big difference.
Here's a guide to help you pick the best endpoint for your application.
Explaining Forward and Reverse Geocoding
Forward geocoding maps from natural language inputs to a location. A user types "1600 Pennsylvania Ave, Washington, DC", and the API returns what you need to put a pin on the map. And that's not all! Forward geocoding fills in additional information about each "hit," like country, region, and sometimes postal code. All in ways that you can cross-reference against other open datasets.
Reverse geocoding turns coordinates into a human-readable description. Whether it's a GPS tracker recording a driver's position, a dashboard grouping events by city, or a mobile app determining the closest street address, the input is geographic coordinates. Filtering to administrative layers ("country, region, county, locality") is all you need for analytical groupings by country or region (and it's super fast!). And if you need something more precise, you can filter results to the street, address, or POI layer.
The choice between forward geocoding and reverse geocoding is usually clear based on the shape of your data and what you're trying to answer. Forward geocoding has a bit more nuance.
Understanding Forward Geocoding Endpoints
Our Forward Geocoding API has three endpoints: search, structured, and autocomplete.
| Endpoint | Optimized for | Key Tradeoffs |
|---|---|---|
| Autocomplete | Type-as-you-search UI | Fast, but can't interpolate house numbers; direct matches only |
| Structured | Form-based input (discrete fields) | Best quality for address searches, but requires structured data (no free-form text) |
| Search | Free-text, natural language | Assumes that input is complete (not search-as-you-type); occasionally mis-parses address components |
Autocomplete is built for a type-as-you-search UI. It's optimized for speed and tries to provide the best results given incomplete input (e.g., "New Y" will return "New York"). Autocomplete can search all layers well and is a great fit when searching for either POIs or addresses interactively. The main tradeoff of autocomplete is that it can't guess interpolated house numbers… yet! You can work around this by hitting the search endpoint after some delay, or when the user presses the search button or enter key. We built this behavior into our search SDKs for you, including both SwiftUI and Jetpack Compose.
Our Autocomplete Search API is also very efficient: both for your user's network bandwidth and your wallet. Most of the intermediate keystrokes in a search-as-you-type UX aren't valuable to your users, and we understand that. The API returns only the minimal information you'd need to build your search UI and costs only a fraction of the other APIs. When the user selects a result, you call the place details API to get the full details. Our search SDKs also handle this for you out of the box.
Structured geocoding is optimized for address searches where you know what components your inputs represent. For example, if you're collecting shipping information, you already ask for information in structured fields. Structured search is primarily designed for address searches and can interpolate house numbers for new addresses not in our datasets.
Search is similar to autocomplete: it takes natural-language input as a single string, but assumes the input is reasonably complete. Search can be used in non-search-as-you-type UIs or integrated with autocomplete when the user presses enter or clicks a search button. Like structured geocoding, search can interpolate house numbers that aren't in our datasets.
Checkout Forms: A Practical Example
Let's look at a common example we're often asked about: collecting billing and shipping addresses in checkout forms. Which endpoint to choose? As with most decisions, it's a trade-off. The main question is what UX you think is best for your users. The forward geocoding endpoints are here to support your desired flow.
The classic checkout form has structured fields like "street", "city," and "state." This is the most common style for a reason. Your logistics provider and payments processor probably already expect data in this form, and it's fairly familiar to users by this point. This is a clear fit for structured geocoding. Most of your fields will map clearly to a structured geocoding parameter, so validating the address is easy. It doesn't validate as you type, but it has a very high hit rate, even for new addresses not yet in our datasets.
An alternative approach that's gaining popularity is to have a single autocomplete search box as the initial UX, then expand to the structured form after the user selects an address. This is typically easier and faster for the users, but search-as-you-type comes with the trade-off of not supporting interpolation, so you'll probably need to combine this with search.
Whichever route you take, our geocoding APIs both return detailed structured components, so you can build whichever UX you like. You can also show this on a map for the user to validate, reducing the chances of a failed delivery.
Alternate / Hybrid Flows: A Case Study of Korean Address Entry
If you're focused on a smaller geographic area or building for other use cases like vehicle navigation, you might consider hybrid approaches for a better user experience. For example, in South Korea, it's common to have buttons (in cars) or a drop-down menu selection (web or mobile) to "drill down" the hierarchy.
In a narrowly focused integration, you can even skip the country and start with a limited menu of administrative divisions. Presenting the user with just a few options speeds up the address selection process. For example, selecting Seoul and then Gangseo-gu. You can then pass this filtered context off to any of our forward geocoding endpoints to give the user a faster and more accurate search experience.
What's Next
No product is perfect, and we don't stop building! We've got some exciting improvements in the works, including an improved geocoding API v2, a "nearby" category-based POI search, and support for autocomplete interpolation.
If you have any questions that this post or our docs didn't cover, get in touch with our world-class support team. We'd love to hear from you!