“Search” and “geocoding” are blanket terms often used to describe any and all types of geospatial search operations. It can be pretty overwhelming when you’re first learning all the terminology, so we’re here to help make sense of all-the-things. We’ll go through what is what, and which of our API “endpoints” will help you find what you need.

First, a little vocabulary.

Words to know

au·to·com·plete

/ˌôdōkəmˈplēt/; synonyms: type-ahead

Anticipating what the user is trying to input and providing meaningful, real-time suggestions: “It was helpful when New York, USA popped up as an autocomplete suggestion after I started typing new.”

ge·o·cod·ing

/ˈjēəˌkōdiNG/; synonyms: forward geocoding, forward search, search

Assigning geographical coordinates to an address, venue, or other location type: “When geocoding the Mapzen NYC office address, you get the latitude, longitude of 40.744236, -73.990352.”

re·verse ge·o·cod·ing

/rəˈvərs ˈjēəˌkōdiNG/

Determining the nearest address or venue at a given latitude, longitude: “The app uses reverse geocoding to determine the address where the driver should pick me up.

struc·tured ge·o·cod·ing

/ˈstrək(t)SHərd ˈjēəˌkōdiNG/

Assigning geographical coordinates to an address, venue, or other location type that has been broken up into its constituent parts: "Because the user filled out the shipping address form in individual fields, structured geocoding was the easiest way of looking up that location because it was already in its component parts.”

Which API endpoint to use when

Now that we have the vocabulary in our arsenal, let’s examine a few different scenarios where geocoding is applicable. Each use case might call for a different variety of spatial search and it’s worth describing each in some detail.

You have a single address field that needs geographic coordinates (/search)

In this scenario, your data might have customer records, for example, with a single field provided for the address information. The address field might also have a variety of data in it, and is not guaranteed to be formatted in any specific way.

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

If your data is free-form like those entries, try forward search with the /search endpoint. It requires a single text input to be specified, which is set to the individual string for each of your records.

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’ll want to go with 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, so let’s just save everyone the trouble.

Your columns might vary depending on your database design or input forms used to collect the data, so don’t dismay if your columns don’t have the same names as the ones in our example. We support a variety of address parts so you can map your columns to each part as needed.

Tip: If you know more information about your data or would like to limit the search in some way, use filters for that. We allow filtering by country, rectangle, or circle. So for example, notice all the data in the above example is in GBR. The more specific you can be in your search requests, the less likely you are to get back an unexpected result.

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

When you use a mapping app, it’s 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.

You have users typing into a search box or address input field in real time (/autocomplete or /search)

When you have live users who type things into input fields or search boxes, their activity falls into two buckets, depending on when your app assumes they are ready to search.

The distinction in the results is visible when you consider the behavior with the text of lond. Autocomplete for lond, returns london (https://mapzen.com/search/explorer/?query=autocomplete&text=lond) because the user is still typing, but /search assumes the user is done entering text and returns the city of Lond in Pakistan (https://mapzen.com/search/explorer/?query=search&text=lond).

…and want to show feedback as they type (/autocomplete)

When you are searching for a hotel in a particular city, for example, you often see a list of matching results appear after each character as you type. In your own app, if you want your users to enter text and see real-time results as they type, use /autocomplete. This type-ahead functionality helps users find what they are looking for, without requiring them to fully specify their search term. Typically, your users start typing and a drop-down list appears where they can choose the term from the list.

Because /autocomplete results in many more individual requests to get a good result, autocomplete has higher free rate limits and lower per-request prices than /search.

…and want to search only when they finish typing (/search)

If you want the search to occur only when specifically executed, such as when your users press Enter, use /search. A search operates under the assumption that the input text is complete. A common design pattern is for an app to use autocomplete for the initial type-ahead behavior, and then switch to a /search when the user presses Enter or clicks an entry from the list.

The /search endpoint offers some functionality that is not currently available for /autocomplete. This includes structured searching and address interpolation for locations where data is incomplete.

(You probably noticed that the examples above point to our new Mapzen Search Explorer. This handy tool not only lets you dig into search endpoints, but lets you adjust parameters and see how they affect results, all on the fly. You can also send the URL to your friends, and they will see the query, its parameters, and the results!)

Image: Patent Model for Carpenter’s Combination Tool, 1867, Patent No. 70,547 invented by John Graham, via Cooper-Hewitt