How Reverse Geocoding Works

Are you ready to roll your own reverse geocoder? If your use cases are specific enough, that may be the best way to get the exact results you need. On the other hand, you should find open data and tools along the way to make sure you don't have to do all the work yourself.

We'll cover five important steps to build your own reverse geocoder:

1. Determine what's needed for your use case
2. Find and stage your data sources
3. Determine what data you will return
4. Format the data how users expect
5. Maintain and improve your geocoder

When you build a geocoder, there's a lot that goes into it. You want to consider the effort required to find data, keep it updated, write the code (or tune an existing geocoder), and maintain that code. That all starts with a crystal clear idea of how you'll use it.

Your reverse geocoding use cases determine how complex the requirements are to build your own. For example, if you simply need to know the continent of a location, you may not even need a database to produce a result. On the other hand, returning fully formatted addresses and various annotations about a place may find you running multiple geocoders.

We'll look at the types of reverse geocoders, review the effort required to build, and how they can be assembled into a single geocoding solution.

The general definition for a reverse geocoder is incredibly broad: based on latitude and longitude coordinates, return a human-readable description of the location. The location might be a very specific place, a nearby landmark, or a larger area.

The geography represented by a reverse geocoder is typically one of the following:

• A nearby point to coordinates
• A nearby path to the coordinates
• A shape surrounding the coordinates

These three geographic features generically describe many different types of place data. Here are some common results from geocoders:

• Full address of location (point)
• Country, region, county/province, or state boundaries (shape)
• Road or highway (path)
• City or postal code boundaries (shape)
• Landmark or prominent point of interest (point)
• Ocean and sea boundaries (shape)
• Rivers and streams (path)
• Time zones (shape)

In addition, there are many other pieces of information you might be able to infer based on a location. For example, OpenCage returns currency, calling code, sunrise/sunset, and more. The full list is available within our annotations documentation.

There are many potential areas of geographic intelligence that a reverse geocoder can return. Many have already been implemented by others, often with data easily sourced. In other circumstances, you might need to compile it on your own.

Once you know the geocoders needed for your use case, you can put them together, likely as a single service. It might be possible to call each geocoder separately, but that puts additional pressure on your applications to determine what result each service produces.

For example, if you require a full address and time zone, those are likely two separate geocoders. Your application could request the address from the first geocoder, then call the second geocoder for the time zone. Alternatively, write wrapper code - or your own API service - to call each geocoder and return both results at once.

At OpenCage we run 10 geocoders that are exposed via a single, flexible API. You can see the full list. Behind the scenes, we run microservices for each geocoder, which are called by a service that compiles the results into a single API response.

A reverse geocoder relies on one or more data sources to determine nearby and geographic features. These are many places to discover this data covered in the reverse geocoding resources chapter.

Typically, data sources fall into a few categories:

• Self-generated
• Licensed
• Government
• Public domain

Each of these takes effort to compile and prepare. A licensed data source may reduce this effort, though pricing can vary. The most cost effective approach is to review whether open data sources can meet your needs.

The best publicly available source for worldwide geographic data is OpenStreetMap (OSM). A global community of mappers creates and maintains the dataset. Like Wikipedia for the physical world, anyone can make edits - and many do.

For over 15 years, volunteers have uploaded tracks from GPS-enabled devices, labeled landmarks, and corrected OSM data. Due to the large number of contributions, OSM is a robust source to use for many projects, including reverse geocoding.

The biggest advantage of open data like OSM is you can use it without restrictions. Compared to proprietary data, there are no commercial limitations or requirements to combine it with other services.

OpenCage is a proud corporate member of the OSM Foundation, and we do a lot to support the geo community. We contribute to the tools, host geo innovation events, and have long been committed geo geeks.

It takes a lot of data to describe the whole world. Before you download OSM data, determine the regions that your reverse geocoder needs to support. A subset of OSM data is much easier to download and install, if that's an option.

If you need worldwide coverage, you'll need to grab the latest snapshot of OSM data. This initial download is nearly a terabyte of data. It includes every feature, line, and label needed to build many projects from OSM - geocoders, maps, and more. It can take up to a week to install!

You can start with a subset of data defined by a bounding box. This can help you determine whether OSM is a fit for your use case without committing all the time and bandwidth to the worldwide dataset. There are download instructions of full and partial data on the OSM site.

Once you have an initial dataset, you'll be able to use much smaller downloads to incorporate the community's frequent updates.

In addition to the data itself, there are a number of tools in the OSM ecosystem. Popular among those is Nominatim, a geocoder first written to help community mappers. You can use it to find places by name, address, or location.

You can try out Nominatim for reverse geocoding with the OSM-hosted version of the service. It supports millions of queries every day, but is not built for production projects. It serves the search bar for the primary OpenStreetMap site, which helps the community contribute new data to the project.

Nominatim's Administration Guide provides details on installing your own server, which you can pair with OSM data.

Among the Nominatim requirements are:

• PostgreSQL 9.3 or later
• PostGIS 2.2 or later
• PHP 7.0 or later

There are also some prerequisites to compile and test Nominatim, as well as apply OSM updates.

Keep in mind that by default it will search everything included in OSM. You'll return results for a lot of data you might not want to include in a reverse geocoder, like park benches. With some feature filtering, Nominatim can be a great foundational geocoder.

Nominatim is the most important of the 10 geocoders run by OpenCage. In fact, one of the OpenCage founders is a top Nominatim contributor. However, it can take some tuning for general purpose geocoding, which comes down to formatting and selecting the appropriate data to return.

Earlier we described how your use case influences what type of reverse geocoder you need. Similarly, the data that you return from your geocoder is impacted by what your application needs. From potentially terabytes of data, you need to decide what small subset to return.

You may only need high level data, or perhaps address-level details. And what contextual data needs to come along? There's a lot to consider, even running in a single geocoder.

The simplest reverse geocoders will return a single text string that describes the location. Even within that basic use case are a number of decisions. The top consideration is granularity - what level of naming do you want to include?

There are many potential names for a place. For example, consider this inexhaustive list in roughly hierarchical order:

• Hemisphere
• Continent
• Multi-country region
• Country
• Intra-country region
• Province or state
• Metropolitan area
• County or other sub-division
• City
• Postal or ZIP code
• Census designation
• Road or highway
• Street address

As you can see, there's nothing "simple" about a single text string. At the very least, it's hiding a lot of complexity and decisions behind the scenes. In many cases, you'll want to include more than one of the above names. A complete address would include the street address, as well as additional city and regional information.

Finally, you might also include geographic data along with the written labels for a place. Here you also need to make a decision about granularity. If you return the country name, do you also provide the geographic center of the nation? Based on your needs, you might even want the boundaries of the country. You'll need to determine the scale for those boundaries, as more granularity will return larger data.

Each of the decisions you make about granularity impacts how you will build, maintain, and consume your reverse geocoder.

It can be tempting to keep adding things for your reverse geocoder to return. The location intelligence can become addicting! Each additional data point, which we call annotations, adds complexity in your geocoder and in the applications it powers. You'll need to decide what data your use case really needs and weigh that with the effort required to produce it.

OpenCage includes a number of annotations based on customer requests and our own research. Some of the most useful supplementary data includes:

• Speed limits
• Time zone
• United Nations M49 codes
• European Union NUTS codes
• Local currency
• Time of sunrise and sunset

You can see a full list in our annotations documentation. We periodically add new data to expand what we provide. Of course, we run a geocoding service, so that's our job. You want to think carefully before adding additional layers of results for your reverse geocoder.

Each annotation becomes another project to build and maintain. We run 10 geocoders, but you probably shouldn't. The reverse geocoder tutorial uses a sample oceans dataset to show how you might add regional annotations to your project. While a basic example, it gives a taste of what's required to include even a simple annotation in your geocoder.

The entire point of reverse geocoding is to take a machine-readable location and make it something humans can easily understand. Knowing what data to return is not the same as determining how to return it.

Reverse geocoding exposes itself as the end user experience. A result that doesn't consider what users expect might provide mental hurdles to the expected meaning. Great reverse geocoding will feel natural, which means paying attention to how data is formatted.

Users expect your application to speak their language, which means your reverse geocoder will also need to be understood internationally. If English is the only language you support, it's easier. But if you support multiple countries, there are differences you should consider.

Regions, countries, and bodies of water can have completely different names. Based upon your approach above, you can determine what to send to the user. However, this requires that your data is available in each language you intend to support. Some datasets may already have multiple languages available, while others will need to be translated.

There are three common approaches you might take to localization:

• The language set in the current web browser
• The native language of the current location
• The user's preferred language

OpenCage makes much of our results available in different languages. We support all three of the common approaches mentioned above by using the optional language parameter when making an API request.

Perhaps even harder than multiple languages are the various ways addresses are formatted. The ordering and inclusion of address components is different everywhere. If you attempt to apply your formatting bias to every result, you'll end up with confused users.

For example, a postal code may appear before a city, after a state, or in many other locations (or not at all!). Here's the address of the capital of the US state Georgia's reverse geocode result:

Martin Luther King Junior Drive Southeast
Atlanta, GA 30303-3506
United State of America

And now the parliament address for the country of Georgia:

Rustaveli Avenue 8
0136 Tbilisi
Georgia

The two barely appear related. These issues occur even with simple city names. You wouldn't think twice in the United States about "New York, New York". Yet, in Germany, you won't find anyone referring to "Berlin, Berlin". Like New York City, Berlin is part of a state with the same name. However, since the boundaries of Berlin (the state) and Berlin (the city) are the same, it's simply called "Berlin."

We wrote about this issue in our guide to address formatting.

"Berlin, Berlin" is technically correct in some theoretical sense, but stylistically it is wrong. It's the type of little detail that makes a digital service feel clunky and non-local.

To solve the problem, we created a templating format to describe the local structure of place names. We open sourced the address formatting templates we wrote to avoid those results that "feel wrong". Every country has a template that can help you return results that feel right.

OpenCage's reverse geocoder returns the individual components of each result. In addition, we apply the local template and provide a well-formatted string in the formatted portion of each API result.

Language and formatting have plenty of variation, but these issues don't stop there. Building a reverse geocoder will help you uncover plenty more small inconsistencies. Each time you come upon one, you can either apply a custom fix for it (adding to the code required to run your geocoder) or ignore it (adding to the cognitive overload for your users).

For example, Washington DC is part of the United States. However, it is specifically not considered a state. If your results display "District of Columbia" as if its state, they would be inaccurate. It must be treated differently than any other city in the United States.

Here's the thing: almost every country has some historical anomaly like this. Everywhere you look, there are geographic edge cases to consider. And as we learned with formatting, when you don't catch these issues, users simply see the results as wrong.

The topic gets even hotter when you consider disputed territories. In some cases, the name you use ("Myanmar" vs "Burma") may say more than you intend to by providing a label. In other circumstances, two countries may lay claim to the same land along a border. You need to decide which country name to return - and whether to use different results based on other factors about the request.

A truly worldwide reverse geocoder will need to consider all of these touchy issues and many, many more, all while keeping data and code updated.

A lot of effort goes into building a reverse geocoder. At a minimum, you must source data and have a way to query that data. As we've seen, you also need to determine what data is returned and how it's formatted. Finally, every decision you make, data you include, and code you write must be maintained for as long as you need to run the geocoder.

Even proprietary data requires maintenance. You'll need to download and install updates. If you built the dataset yourself, you'll need some mechanism to report bugs and determine what requires a fix.

Likely, at least part of your geocoder is based on open data, such as OSM. It makes sense to use this Wikipedia-like source. However, like the online encyclopedia, OSM is ever-evolving. To stay accurate, you need to frequently refresh your reverse geocoder's data.

There are millions of OSM updates every single day, as people around the world improve the map. There are millions of OSM editor accounts and many thousands are active every month. Whether updates, corrections, or brand new data, these edits continue to grow, as shown by a chart from OSM stats.

Once you've downloaded the OSM data you need, you will need to regularly apply "changeset" or diffs of the database. These downloads are much smaller and contain a description of only the data that has changed since the previous update.

Changesets are released continually, but if you go too long between updates, then refreshing your data can take multiple days. To keep your OSM-driven reverse geocoder updated, you'll want a plan for overseeing and producing these updates on a continual basis.

Keep in mind what makes OSM and other open data projects work is the community of contributors. If you build your reverse geocoder off of OSM data or software, you want to do your part to give back.

There are many ways to get involved in open data and OpenStreetMap. Here are just a few ideas:

• Submit edits to OSM. See our tutorial.
• Join the OSM Foundation
• Participate in community discussions and events
• Submit bugs and patches to opensource geo software projects
• Open source your tools and data

OpenCage is a proud corporate member of the OSM Foundation, and has a long history of supporting the geo community. We've also open-sourced many of our projects.

How can you and your organization help to improve OSM and the tools around it?

For most companies, developer time is extremely expensive. At the very least, it's finite. You need to decide where to focus that time. Should it be spent reinventing the reverse geocoding wheel or improving the experience of your core product?

There are many open source and open data tools that can help you build a reverse geocoder. As you've seen in this guide, doing this well requires a lot of effort. If you're geo geeks like us, you might want to give it a shot yourself. But we've found most developers want to get the data, so they can build something original. That's why we built a service that makes reverse geocoding easy for developers.

To give OpenCage a shot, we recommend you save yourself even more time and use one of our libraries. We provide SDKs in over 30 programming languages to get you started quickly.