pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
506 Commits
5 Branches
0 Tags
13 MiB
 
Tree: 7509fef259
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '7509fef259'
${ noResults }
documentation/structured-geocoding.md

11 KiB
Raw Blame History

Structured geocoding

With structured geocoding, you can search for individual components by specifying that the item you are searching for is an address, a city, or one or more types of locations.

For example, if you have a table of addresses where each column represents a different part of an location, use structured geocoding. With the text parameter for search, you would need to concatenate these fields into one string.

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

Structured geocoding allows you to specify exactly how to interpret a location, as concatenating fields introduces ambiguity in your data. For example, 10 Park Place North Charleston South Carolina could be a city name containing a directional (North Charleston in South Carolina), or as or as a street with a post-directional (10 Park Place North). In addition, addresses and postal codes around the world are often formatted differently.

Structured geocoding parameters

You can use structured geocoding on any of these parameters, as well as the other search parameters.

  • address
  • neighbourhood
  • borough
  • locality
  • county
  • region
  • postalcode
  • country

address

The address parameter can contain a full address including house number or just a street name. Pelias stores addresses as separate number and street fields so libpostal is utilized to parse the number and street values.

Examples

neighbourhood

Neighbourhoods are vernacular geographic entities that may not necessarily be official administrative divisions but are important nonetheless.

Examples

borough

Boroughs are a bit of an oddity in the realm of spatial data. For the most part they fit in between neighbourhoods and localities but are mostly identifiable to the general public in the context of New York City even though other cities such as Mexico City have them, too. In fact, they're commonly thought of as cities themselves rather than as subsidiaries of New York City.

Examples

locality

Localities are equivalent to what are commonly referred to as cities, but can range anywhere in size from the smallest hamlet to the most populous metropolis on the planet.

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 3 cities named Red Lion in Pennsylvania but only 1 in each of 3 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 (almost always countries). Among other reasons, postal codes are unique within a country so they're useful in geocoding as a shorthand for a fairly granular geographical location.

Examples

Pelias doesn't currently import postal codes, though addresses from OpenAddresses and OpenStreetMap are sometimes annotated with postal codes and used for scoring.

country

Countries are the highest-level administrative divisions supported by Pelias. In addition to full names, countries have common 2- and 3-letter abbreviations which are also supported values for the country parameter.

Examples

The more astute geocoding blog reader that has spent entirely too much time perusing Who's on First would have noticed that Bermuda is actually a British Overseas Territory (a dependency, in Who's on First nomenclature) and not a country, similar to the relationship Puerto Rico and New Caledonia have to the United States and France, respectively. To reduce the number of parameters and potential confusion about data organization, dependencies are searched for using the country parameter value.

Caveats

Any combination of the above parameters can be sent as structured geocoding requests with the exception of postalcode-only as Pelias does not currently import postal codes as separate records, only as augmenting address data. For example, a request consisting only of /v1/search/structured?postalcode=87801 is not valid at this time and an error will be returned to the caller.

Who's On First Layer Mappings

This section is for people who are well-versed in the nuances of Who's on First place types in or have spent a bit of time looking at data in it.

As stated previously, we don't expect our users to understand the complexities of Who's on First layer mappings. While there are very good reasons why our gazetteer supports both locality and localadmin, it would be pretty cumbersome to include both as parameters, so we have added some convenience mappings to make structured geocoding easier:

structured geocoding parameter Who's on First placetype(s)
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, but we don't expect the user to know the distinction, so if a structured geocoding request specifies locality=Peach+Bottom&region=Pennsylvania, then Pelias will lookup Peach Bottom in both the locality and localadmin layers.