Geocoding in Cesium using Pelias
This is a guest post by Julian Simioni, a core maintainer of the Pelias geocoder and co-founder of Cleared for Takeoff, Inc., which helps organizations of all sizes with their geocoding needs. Pelias is the open-source geocoder used by Cesium ion. - Sarah
A few weeks ago, the Cesium team added support for Pelias-based geocoders in CesiumJS.
Ultimately, geocoders bridge the gap between the mathematical world of coordinates, boundaries, and distances, with the textual world of placenames, languages, and addresses. Since Cesium already has amazing mathematical and graphical powers, it only makes sense to pair it with a geocoder, and as another open-source project, Pelias is a good fit.
What is a geocoder?
A geocoder converts the textual name of a place or area into some form of mathematical coordinates.
If you’ve ever typed the name of a place into a search box on a map, you’ve already interacted with a geocoder, even if you didn’t know it!
What’s Pelias?
Pelias is an open-source geocoder with support for geocoding all over the planet. It can be installed yourself, and there are also geocoding providers that will host it for you.
Pelias is designed to be largely data-agnostic: it works out of the box with some well known open data projects like OpenStreetMap, OpenAddresses and Geonames. Additionally, Pelias supports importing custom data via common formats like CSV.
What can a geocoder do for you?
Since Cesium is capable of displaying and analyzing data all over the globe, a geocoder is indispensable simply for navigating around. By returning coordinates in its search results, a good geocoder can help you seamlessly pan a map from the location of an address (say 10 Downing Street, London), to a city (like San Francisco, CA), to a country (for example, Japan).
The response from a geocoder contains more than just latitude and longitude: geocoders know a lot about the places you search for. The data below shows everything Pelias returns about the city of Detroit. Geocoders know about the relationship between places, and here Pelias lists the state and country that Detroit is in, as well as a helpful label which combines all these properties together and is perfect for displaying as a label on a map.
Geocoders also know all about languages, and in this case it’s been asked to return results in French.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-83.164515,
42.398649
]
},
"properties": {
"id": "85951091",
"layer": "locality",
"source": "whosonfirst",
"source_id": "85951091",
"name": "Détroit",
"confidence": 1,
"accuracy": "centroid",
"country": "États-Unis",
"country_a": "USA",
"region": "Michigan",
"region_a": "MI",
"county": "Wayne County",
"localadmin": "Detroit",
"locality": "Détroit",
"continent": "Amérique du Nord",
"label": "Détroit, MI, USA"
},
"bbox": [
-83.287803,
42.255192,
-82.910451,
42.45023
]
}
An abridged example of output from Pelias, showing all the information returned about the city of Detroit, after querying for it in French.
A subtle but crucial part of the response is the bounding box. A geocoder can return any type of result from an address to a country, but they shouldn’t all be treated the same. Zooming out to show half the planet after searching for an address wouldn’t be very useful. Likewise, showing a small area in response to a query for Russia wouldn’t be a good thing either.
Autocomplete: When every keystroke matters
One of the hardest challenges in geocoding is autocompletion: returning the right result to a user as it’s being typed. Besides the raw performance needed to keep up with the fast typers out there, partial input is almost always ambiguous.
Imagine trying to search for London, typing it out letter by letter. Unfortunately, most of the words you’ll type along the way are in fact the name of a place somewhere! Lond is a populated place in Pakistan, and Londo is the name of places in Indonesia, Tanzania, and a few other countries. Even Lon is the name of a Census Designated Place in Missouri!
Clearly, the best text match isn’t always the right one. In the case of London specifically, it’s a prominent enough city that it’s easy to resolve the ambiguity, but there are lots of trickier situations. Geocoders take many factors, such as population, whether or not the city is a capital, or sometimes even whether the place has a Wikipedia page into account for autocomplete to solve this problem.
One of the best ways to resolve this ambiguity is to use a focus point. Many geocoders, Pelias included, support sending a latitude and longitude point in combination with text. Places nearer to that point will be preferred, all else being equal, to those farther away.
This can help the residents of Paris, Texas find their city without confusing it with the more well known one in France. Visitors to one of the 33 Springfields across the United States surely appreciate this too.
Some of the many Springfields in the world
Throw it in reverse
While taking advantage of the textual and language features of a geocoder is useful, the other half of a geocoder’s functionality, managing geospatial and geometric data, is at least as important.
Reverse geocoding gives information about a given point on the Earth. This can include finding nearby points representing addresses…
Reverse geocoding in New York city
…or using geometries to determine what city, state, or country a point belongs to.
The geometry of a region in Denmark. Its unique shape once caused a little bug.
Reverse geocoding’s mathematical nature makes it veryfast, and so it’s a perfect fit for Cesium’s ability to display data in real time. Reverse geocoding is handy for displaying information about the location of cars, planes, and satellites as they buzz around the planet.
This baby is fast, but even it isn’t fast enough to outpace Pelias’s reverse geocoding.
What’s coming soon?
Building a geocoder is a job that’s never done: the world is constantly changing, and every geocoder has to change with it. Besides keeping up with countries changing their name, and swapping territory, we have lots of new features and fixes in the pipeline. Here’s just a few most relevant to Cesium users:
- Returning polygon data: Pelias knows about the geometries of cities, states, and countries. In the future it will be able to return that geometry directly. Once it does, polygon data returned by a geocoder could be visualized right in Cesium
- Reverse geoocding street polylines: Like Cesium, Pelias supports the polyline format, which it uses to load street data from OSM. We intend for reverse geocoding to also consider the geometry of these streets.
- Better, faster autocomplete: : As mentioned earlier, autocomplete is especially tricky to get right. We’ll continue to improve all aspects of autocomplete, but in particular we’ll be revamping how autocomplete uses city and country names to distinguish places (for example, Berlin, CT vs. Berlin, Germany).
Both CesiumJS and Pelias are open source projects because the world is a big place: too big to handle without the help of others. If you’re looking to learn more about the Pelias project, report issues, or contribute to the project, come find us on GitHub. Happy mapping!