Common geocoding workflows

Mapzen Search provides several API endpoints, and each is best suited for a particular geocoding workflow. Match your use case to these common scenarios to determine which endpoint to use for tasks in your app.

You have an address split into its constituent parts (/search/structured)

You might have data that is broken up into columns, where each column represents a part of the address.

id name address city country occupation
321 Jane Banks 17 Cherry Tree Lane London GBR student
654 Paddington Bear 32 Windsor Gardens London GBR bear
987 Sherlock Holmes 221B Baker St London GBR private investigator

You should use structured geocoding (/search/structured) for this scenario. If you already know which part of the address corresponds to which field, there is no need to concatenate them all together only to need to break them up again to search. This will help avoid potential errors in both the concatenation and the parsing processes.

Your columns might vary depending on your database design or input forms used to collect the data, so it is okay if your columns have different names as the ones in this example. Structured geocoding supports a variety of address parts so you can map your columns to each part as needed.

Tip: Use filters if you know more information about your data or want to limit the search in some way. You can filter by country, rectangle, or circle. So, for example, notice all the data in the example is in GBR. The more specific you can be in your search requests, the less likely you are to receive an unexpected result.

You have latitude and longitude data and want the corresponding address (/reverse)

When you use a mapping app, it is common to click a location to find out the address there. Similarly, when you use your phone to request assistance from the police, for example, your location is often automatically translated to an address where the officers can be routed. In these cases, reverse geocoding is happening behind the scenes.

You use the /reverse endpoint when you know the coordinates of your location, and want to learn the address or information about nearest point of interest, such as the name of a business, restaurant, or park.

You have latitude and longitude data and want the administrative area it falls within (/reverse with layers)

Sometimes, when you click on a map, you want information about the region containing that location. This is a variation of a reverse search, known as coarse reverse geocoding, where you can look up administrative hierarchy information for a given set of coordinates. This can be very useful when you have linked the administrative boundary with other datasets–for example, allowing you to click a house to find out its local government representative or which fire department serves it.

For coarse reverse, use the /reverse endpoint and layers=coarse or include any of the administrative area types, such as locality, region, or country. If you only want the administrative information, using coarse reverse can improve performance because there are far fewer administrative regions globally than there are individual addresses to query.