9.6 KiB
Structured geocoding
With structured geocoding, you can search for the individual parts of a location. Structured geocoding is an option on the search endpoint, where a query takes the form of https://search.mapzen.com/v1/search/structured.
For example, you want to find 30 West 26th Street, New York, NY. With the geocoding parameter for search, you can only enter the entire location as one string, such as text=30 West 26th Street, New York, NY. However, with search/structured, you can specify that this location is composed of a street address, a locality, and a region.
{
address: '30 West 26th Street',
locality: 'New York',
region: 'NY'
}
Structured geocoding can improve how the items in your query are parsed and interpreted in a search. An address such as 10 Park Place North Charleston South Carolina could be viewed as a city name containing a directional (North Charleston in South Carolina), or as a street with a post-directional (10 Park Place North). By separating the components of the search input, you are reducing ambiguity in your query. This is also helpful because addresses and postal codes around the world are often formatted and ordered differently.
One common use for structured geocoding is for geocoding a list or table of addresses, where each column represents a different portion of a location.
| address | city | state | country |
|---|---|---|---|
| 1600 Pennsylvania Ave | Washington | DC | US |
| 10 Downing Street | London | GB | |
| 55 Rue du Faubourg Saint-Honoré | Paris | FR | |
| Bulevardul Geniului 1 | Bucharest | Romania |
With a regular search query, you would need to concatenate these columns into one string, but search/structured allows you to define a query that maintains the individual fields for address, city, state, and country.
Structured geocoding parameters
You can use structured geocoding to search for the following parameters:
- address
- neighbourhood
- borough
- locality
- county
- region
- postalcode
- country
Note that the other search parameters can also be combined with these, allowing you to filter and prioritize your results.
address
The address parameter can contain a full address with house number or only a street name.
Examples
neighbourhood
Neighbourhoods are vernacular geographic entities that may not necessarily be official administrative divisions but are important nonetheless.
Examples
- Notting Hill in London
- Flatiron District in Manhattan
- Le Marais in Paris
borough
Boroughs are mostly known in the context of New York City, even though they may exist in other cities, such as Mexico City.
Examples
A structured geocoding request for /v1/search/structured?locality=Manhattan®ion=NY, returns boroughs along with localities.
locality
Localities are equivalent to what are commonly referred to as cities.
Examples
- Bangkok
- Caracas
- Truth or Consequences in New Mexico
county
Counties are administrative divisions between localities and regions.
Examples
- Bucks in Pennsylvania
- Maui
- Alb-Donau-Kreis in Germany
Counties are not as commonly used in geocoding as localities, but can be useful when attempting to disambiguate between localities. For instance, there are three cities named Red Lion in Pennsylvania but only one in each of three counties. Specifying a county disambiguates this list to a single result.
region
Regions are normally the first-level administrative divisions within countries, analogous to states and provinces in the United States and Canada, respectively, though most other countries contain regions as well.
Examples
Regions in the United States have common abbreviations, such as PA for Pennsylvania and NM for New Mexico. The region parameter can be a full name or abbreviation, so specifying /v1/search/structured?region=NM is functionality equivalent to /v1/search/structured?region=New Mexico.
postalcode
Postal codes are used to aid in sorting mail with the format dictated by an administrative division, which is almost always countries. Among other reasons, postal codes are unique within a country so they are useful in geocoding as a shorthand for a fairly granular geographical location.
Examples
Keep in mind that you can search for postalcode exclusively. So requests like /v1/search/structured?postalcode=87801 will return matching postalcode records.
country
Countries are the highest-level administrative divisions supported in a search. In addition to full names, countries have common two- and three-letter abbreviations that are also supported values for the country parameter.
Examples
Who's On First layer mappings reference
The Who's on First gazetteer is one of the datasets used as a source of search data. Use this table is a reference between the parameters for structured geocoding and the types of places in Who's on First.
| Structured geocoding parameter | Who's on First placetype |
|---|---|
neighbourhood |
neighbourhood |
borough |
borough |
locality |
locality, localadmin (and borough if borough parameter is not supplied) |
county |
county, macrocounty |
region |
region, macroregion |
country |
dependency, country |
For example, Peach Bottom, Pennsylvania is only a localadmin place type and not a locality in Who's on First. For simplicity, if a structured geocoding request specifies locality=Peach+Bottom®ion=Pennsylvania, then Peach Bottom in both the locality and localadmin layers are searched.