Putting results on a map

Mapping software needs precise coordinates like those returned by our geocoder to know exactly where to position pins on a map.

Basically, the process is

1. You have an address
2. You geocode the address to turn it into coordinates
3. You pass those coordinates to a mapping library to display a pin on a map

You can use the OpenCage geocoding API for step 2 of this process.

Two points to note before you dive in:

• Along with a single geometry (a lat/lng point), many results also include a bounds box describing the extent of the result. For a building address, the point is usually all you need. But for larger areas (a city, a region, a country) fitting the map to the bounds (rather than just centering a pin on the point) usually gives a much better result, since it shows the whole area rather than an arbitrary center point.
• A forward geocoding (address to coordinates) request can return more than one result for an ambiguous query (e.g. "Springfield" matches dozens of places). Decide up front whether you want to just use the first, best-guess result, or show all the candidates as separate markers and let the user pick.

Some geocoding services, for example Google, restrict where you can display the results their geocoder returns. They require that you only display results on their maps, or that you purchase an expensive license if you'd like to display the map behind a firewall, or that you can only store the geocoding results for a limited time period or while you remain a customer.

Because we use open data you are free to display results on any mapping software you like. This is one of the many benefits of using open data.

The exact technical process will depend on which mapping software you are using, but most are similar.

Almost all web and mobile based maps are manipulated via the programming language javascript.

It is important to understand the distinction between mapping libraries: javascript code libraries that allow you to add a map to a webpage, and mapping providers: services that create map tiles that you can display on a webpage by using a mapping library. Some companies like Google provide mapping libraries and maps. Others provide only maps which you can integrate with open source mapping libraries.

There are many companies offering maps based on OpenStreetMap. We recommend Thunderforest. Note that OpenStreetMap-based tiles generally require you to display an attribution notice on the map. This isn't just good practice, it's usually a condition of the tile provider's terms of use, so don't skip it.

Here is a list of popular web mapping libraries

• Leaflet is a very popular, beginner-friendly, open source library. In the QuickStart tutorial they show how to add a pin (a "marker", in Leaflet terminology) to a map at any coordinates.
• OpenLayers is another mature, open source mapping library, typically used for more complex mapping applications.
• MapLibre offers fast vector-tile rendering with no vendor lock-in.
• Google Maps API is probably the most widely used, non-open source mapping library, they also provide maps.

This is just a brief overview, there are many other mapping applications, some available for free, others costing money. But all work on the same basic concept. You convert addresses into coordinates and then use the coordinates to position points on a map.

• OpenCage geocoding API reference
• Why using open data matters
• Leaflet QuickStart tutorial