Good news, everyone! The Mapzen Pelias team just released the first of several updates to our /reverse endpoint that moves functionality away from what could be considered “things nearby” to true reverse geocoding. First is an update to “coarse reverse geocoding”, or, searching for what administrative area(s) (city, state, country) contain a point. There’s no trick to invoking coarse reverse geocoding other than specifying a layers parameter with either coarse or any of the administrative area types, such as locality, region, or country in your /v1/reverse request.
A Quick Primer
The general idea of reverse geocoding is to determine the most granular geographical feature at a latitude/longitude pair for which there is data, be it an address, street, city, state, or country. The ideal data set for the target area (in our case, the planet) would contain a point for every single address, line strings with number ranges for every street, and polygons for every conceivable administrative area from microhoods to continents and oceans.
Some /reverse expectations:
- Appropriate thresholds are used in the case of addresses and streets to make sure things too far away are not presented as a match. A reverse geocoder populated with address data should return an address for a point if one is reasonably close (within, say, 25 meters).
- If no such address is found, it’s expected that the reverse geocoder should fall back to a reasonably close interpolated address point on a line string representing a street.
- If no interpolated point is found, a reverse geocoder should fall back to a street where the input point is reasonably close to the line string.
- If no street exists, the most granular polygon representing administrative areas should be returned.
If sufficient data exists, a point on Earth should always return a result, assuming that the input is a valid latitude/longitude pair, representing a geographical feature anywhere from an address in an alley in Tuscon, AZ all the way to somewhere in the Arctic Ocean.
In the general case, it’s expected that a reverse geocoder will return a single result but certain concessions can be made in the case of areas that are disputed or change hands on occasion, such as Doumera Island and Pheasant Island, respectively.
Pelias supports reverse geocoding with 2 required parameters containing the latitude and longitude pair and an optional 3rd parameter specifying 1 or more layers. An example request that finds the city for point 33.141112/-107.249610 is:
http://search.mapzen.com/v1/reverse?layers=locality&point.lat=33.141112&point.lon=-107.249610
What We’ve Changed
We now consider if the point is in the geometry of the polygon, not just its distance to the centroid.
We’re rolling out the improvements in a few phases, starting with the case where the user just wants to know what administrative area a point is in. These would be requests specifying layers=coarse or any other value representing an administrative area, such as neighborhood or country. Specifying venue, address, or street or no parameter at all will disable the new logic and utilize the existing “what’s nearby” approach to reverse geocoding, which could be venues, addresses, or administrative areas.
This update searches administrative area polygons for an input point, rather than only returning an administrative area if its geographical centroid happened to be close to that point. Effectively, this change means that we’re now doing a simple point-in-polygon lookup for coarse /reverse requests.
For example, the known hierarchy of a point is returned:
The Near Future
The work described in this post can be viewed as fallback logic: find the most granular polygon that contains the point, be it a neighbourhood, city, or even country. The next step in updating how the /reverse endpoint works is to ensure that addresses returned are relevant to the input point. That is, only return an address result if there is one within a certain distance threshold of the input point. The new approach to coarse reverse geocoding fits nicely in with this plan since if an address (either explicit or interpolated) is not found, Pelias is already set up to fall back to the most granular polygon that contains the point.
The Far Future
We’re in it for the long haul here at Mapzen, so even before Mars is colonized, Pelias should be able to reverse geocode on the red planet when there is a Martian gazetteer! (Note that planet is already a placetype in Who’s On First…) In fact, the only stipulation we make for whatever planets you want to load into a custom Pelias instance is that they be as spherical as possible. (Sorry, Phobos.) We’re not outright discriminating against non-sphere-ish astronomical bodies, we just can’t map their coordinate systems right now. We’ll cross that space bridge when we come to it.
Image credits:
Note: This post was updated on May 31, 2017 to update the API request links.
