Skip to content

Latest commit

 

History

History
145 lines (93 loc) · 9.86 KB

structured-geocoding.md

File metadata and controls

145 lines (93 loc) · 9.86 KB
Raw

Structured geocoding

Note: The structured endpoint is in beta. You may experience issues as the structured endpoint has not been as thoroughly tested as the search endpoint.

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 /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

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&region=NY, returns boroughs along with localities.

locality

Localities are equivalent to what are commonly referred to as cities.

Examples

county

Counties are administrative divisions between localities and regions.

Examples

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&region=Pennsylvania, then Peach Bottom in both the locality and localadmin layers are searched.