OpenStreetMap OSM Nominatim API tutorial

You've probably heard of OpenStreetMap (OSM), the free, editable map of the world created by an international team of volunteers using aerial imagery, GPS devices, and other sources to create an open source geographic database of the planet. But did you know that you can also use OSM to build your own free geocoding and reverse geocoding API? This tutorial series will show you how.

Part 1: OpenStreetMap OSM Nominatim API tutorial (this article)
Part 2: Run a free geocoder with Nominatim Docker
Part 3: Building a free geocoding and reverse geocoding service with OpenStreetMap
Part 4: How to draw neighborhood and administrative boundaries with OSM (coming soon)

How does OpenStreetMap work?

You can think of OSM as a specialized database that stores geographic information using a simple and flexible data structure consisting of nodes, ways, and relations, each of which can have associated tags to describe the real-world features they represent.

Nodes: These are individual points on the earth's surface defined by their latitude and longitude. Nodes can represent point features such as mountain peaks, water wells, or even a bench. When nodes carry tags, they describe specific features at a point location.

Ways: These are ordered lists of nodes that form a polyline or polygon. Ways can represent linear features like streets and rivers (polylines) or well defined areas like forests and lakes (polygons). Tags associated with ways describe the feature that the way represents.

Relations: These are a bit more complex and are used to model relationships between nodes, ways, and other relations. Relations can represent multi-part geometries or more complicated structures like turn restrictions in routing, routes that include multiple ways (such as bus or cycling routes), and boundaries that consist of many ways.

Tags are key-value pairs attached to nodes, ways, and relations to store information about the map features they represent. For example, a way might have tags indicating that it is a highway (highway=primary), its name (name=Main Street), and its speed limit (maxspeed=50). Tags are incredibly versatile and allow OSM to store detailed information about a wide range of geographic features. For example, here are what the tags look like for Canada Place in Vancouver, Canada. Canada Place is the main embarkation point for cruise ships leaving for Alaska.

OpenStreetMap (OSM) is fundamentally different from commercial mapping services like Google Maps and Mapbox in that it primarily serves as a database rather than offering a comprehensive suite of built-in APIs for various functionalities. This means that to access features like traffic updates or direction services using OSM's map data, you must rely on third-party tools. In our blog, we have thoroughly covered the use of one such tool, the Open Source Routing Machine (OSRM), to obtain turn-by-turn navigation instructions. In this tutorial series, we will introduce another tool, Nominatim, and demonstrate how to use Nominatim for free geocoding and reverse geocoding services.

What is Nominatim

Nominatim (latin for "to name" or "designate") is a geocoding and reverse geocoding service for OpenStreetMap. You can think of it as a specialized search engine for map data. To experiment with Nominatim and gain a hands-on understanding of how it works, you can use OpenStreetMap's free debugging tool to follow the examples in this tutorial and learn how to use Nominatim effectively.

What is address geocoding?

Geocoding is the process of converting addresses into geographic coordinates. For example , searching for "999 Canada Place, Vancouver, BC" on the OSM debugging tool will return the latitude longitude pair for that address. In this case, "49.288,-123.112".

What is reverse geocoding?

Reverse geocoding is the inverse of geocoding. It is the process of converting geographic coordinates into a human-readable address. Entering the same coordinates we got back in the previous section, "49.288,-123.112", returns "West Waterfront Road, Gastown, Downtown, Vancouver, Metro Vancouver Regional District, British Columbia, V6C, Canada" as the address.

If the coordinates you provided (indicated by a red circle in the screenshot) don't precisely align with what OSM has stored, Nominatim will offer its "best guess" address, linked to the nearest valid coordinate (indicated by a blue circle). Typically, these coordinates represent central points of buildings or their front entrances located near major roads.

What you'll learn in this tutorial

This course is divided into four sections designed to make you an expert on Nominatim and related OSM functionality. In the first (this article), we covered the basics of OSM and explained why we need a third party tool like Nominatim to efficiently extract data from OSM. In the second, you'll learn how to set up and install the Nominatim server locally using docker. In the third section, you'll learn how to use the Nominatim API to build a free geocoding and reverse geocoding service. And in the last section, we'll expand on Nominatim's geocoding functionality to extract neighborhood and administrative boundaries that you can display on a map.

👋 As always, if you have any questions or suggestions for me, please reach out or say hello on LinkedIn.

Next: Part 2: Run a free geocoder with Nominatim Docker