SDKs overview

OpenStreetMap (OSM) is a collaborative project to create a free editable map of the world. Unlike commercial mapping providers that offer proprietary SDKs, OpenStreetMap primarily provides the raw geospatial data and a suite of tools and libraries developed by its community. Developers interact with OpenStreetMap through various client-side libraries for map rendering, data manipulation, and integration with services built on OSM data, such as Nominatim for geocoding or OSRM for routing. The ecosystem supports a wide range of programming languages and platforms, reflecting its open-source and community-driven nature.

These SDKs and libraries facilitate tasks such as displaying map tiles, overlaying custom data, performing geocoding lookups, and routing calculations. The choice of library often depends on the specific application requirements, the target platform (web, mobile, desktop), and the developer's preferred programming language.

Official SDKs by language

While OpenStreetMap itself is a data project, several highly adopted and widely considered 'official' or primary libraries are maintained by core contributors or closely aligned projects. These often serve as foundational components for more specialized community libraries. The following table outlines some of these key libraries, their primary language, and typical usage.

Language Package/Library Description Maturity
JavaScript Leaflet Mobile-friendly interactive maps for web applications. Stable, widely used
JavaScript OpenLayers High-performance feature-rich maps for web applications. Stable, comprehensive
Python OSMnx Retrieve, construct, analyze, and visualize street networks from OSM. Stable, active development
Java/Android osmdroid Offline-capable map library for Android applications. Stable, active development
C++ libosmium Fast and flexible C++ library for working with OSM data. Stable, foundational

Each of these libraries provides distinct functionalities. For instance, Leaflet's API documentation emphasizes ease of use for interactive web maps, making it a popular choice for straightforward integrations. In contrast, OpenLayers documentation showcases its advanced capabilities for complex geospatial data visualization and manipulation.

Installation

Installation methods vary based on the programming language and specific library. Below are common installation commands for some of the widely used OpenStreetMap-related libraries:

JavaScript (Web Applications)

For Leaflet and OpenLayers, you typically include them via CDN or install using npm.

Leaflet via CDN:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" integrity="sha256-p4NxAoJBhIINfQPDQwrADkHdF1AQA3+UlEkAKkELLjo=" crossorigin=""/>
<script src="https://unpkg.com/[email protected]/dist/leaflet.js" integrity="sha256-20nQCchB9co0qIjJZRGuk2/4K6pQ+oYbZHnC8Hn4m+o=" crossorigin=""></script>

Leaflet via npm:

npm install leaflet

OpenLayers via npm:

npm install ol

Python

Python libraries are typically installed using pip.

OSMnx:

pip install osmnx

Java/Android

For osmdroid, add it as a dependency in your build.gradle file (for Android projects).

osmdroid (in app/build.gradle):

dependencies {
    implementation 'org.osmdroid:osmdroid-android:6.1.18'
}

Ensure you check the osmdroid GitHub repository for the latest version and detailed setup instructions.

Quickstart example

This example demonstrates how to display a basic OpenStreetMap using the Leaflet library in a web application. This quickstart creates a simple HTML page with an interactive map centered on a specific latitude and longitude, displaying standard OSM tiles.

Leaflet Basic Map Quickstart (HTML/JavaScript)

Create an index.html file with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Leaflet OSM Map</title>
    <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css"
        integrity="sha256-p4NxAoJBhIINfQPDQwrADkHdF1AQA3+UlEkAKkELLjo=" crossorigin=""/>
    <script src="https://unpkg.com/[email protected]/dist/leaflet.js"
        integrity="sha256-20nQCchB9co0qIjJZRGuk2/4K6pQ+oYbZHnC8Hn4m+o=" crossorigin=""></script>
    <style>
        #mapid { height: 500px; width: 100%; }
    </style>
</head>
<body>
    <div id="mapid"></div>

    <script>
        // Initialize the map and set its view to a given geographical coordinate and zoom level
        var mymap = L.map('mapid').setView([51.505, -0.09], 13);

        // Add an OpenStreetMap tile layer to the map
        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
            attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
        }).addTo(mymap);

        // Add a marker to the map
        L.marker([51.5, -0.09]).addTo(mymap)
            .bindPopup("<b>Hello world!</b><br />I am a popup.").openPopup();

        // Add a circle to the map
        L.circle([51.508, -0.11], {
            color: 'red',
            fillColor: '#f03',
            fillOpacity: 0.5,
            radius: 500
        }).addTo(mymap).bindPopup("I am a circle.");

        // Add a polygon to the map
        var polygon = L.polygon([
            [51.509, -0.08],
            [51.503, -0.06],
            [51.51, -0.047]
        ]).addTo(mymap).bindPopup("I am a polygon.");
    </script>
</body>
</html>

This code snippet first includes Leaflet's CSS and JavaScript files from a CDN. It then defines a div element with the ID mapid which will host the map. The JavaScript initializes a map instance, sets its initial view, and adds a tile layer using OpenStreetMap's standard tile servers. It also demonstrates how to add basic interactive elements like markers, circles, and polygons. For more advanced features and customization, developers can refer to the Leaflet documentation examples.

Community libraries

Beyond the primary libraries, the OpenStreetMap community has developed a vast array of specialized tools and libraries across various programming languages and platforms. These libraries often extend the functionality of core components or provide tailored solutions for specific use cases.

  • Geocoding and Routing: Libraries like Photon (based on Nominatim) provide local geocoding solutions, while various wrappers exist for routing engines such as OSRM or GraphHopper, enabling developers to integrate navigation features into their applications.
  • Data Processing and Analysis: Tools like osmium-tool (a command-line tool built on libosmium) and Python libraries such as geopandas (which can work with OSM data after conversion) are used for parsing, filtering, and analyzing large OSM datasets. Pyrosm specifically allows for reading OpenStreetMap data from PBF format into networkx or geopandas data structures in Python.
  • Mobile Development: In addition to osmdroid for Android, iOS developers often utilize libraries like Mapbox GL JS (which can render OSM data) or other native mapping frameworks that support custom tile sources. Cross-platform frameworks also have plugins, such as react-native-maps which supports various map providers including OSM.
  • Desktop Applications: QtLocation for C++ and libraries for Java (e.g., JMapViewer) or .NET (e.g., BruTile) provide components for embedding maps in desktop environments. These often allow for custom tile servers and overlaying local data.
  • Web Framework Integrations: Many web frameworks have specific integrations. For example, React applications might use react-leaflet, an official React component for Leaflet, making it easier to manage map state within a React application. Angular and Vue also have similar wrappers for Leaflet or OpenLayers.

When selecting a community library, developers should evaluate its active maintenance, documentation quality, and community support to ensure long-term viability and ease of integration. The OpenStreetMap Wiki's Frameworks page provides a comprehensive list of tools and libraries, categorized by language and function, offering a broader view of the ecosystem.