openrouteservice.org SDKs & Libraries: Python, JavaScript, Java

SDKs overview

openrouteservice.org offers a suite of Software Development Kits (SDKs) and community-contributed libraries designed to simplify interaction with its geospatial APIs. These APIs provide functionality for routing, geocoding, matrix calculations, isochrones, and points of interest (POIs) based primarily on OpenStreetMap data. The SDKs abstract the underlying HTTP requests and JSON responses, allowing developers to integrate location-based services into their applications with reduced boilerplate code. The official SDKs support key programming languages, ensuring broad compatibility across different development environments.

The SDKs are maintained to align with the latest API versions, ensuring access to features such as multimodal routing, elevation data, and advanced route constraints. Developers can find comprehensive documentation for each SDK, detailing installation procedures, authentication methods, and usage examples for various API endpoints. The open-source nature of openrouteservice.org means that both the core API and its associated SDKs benefit from community contributions and transparency in development, a model also seen in projects like the Mapbox GL JS documentation for web mapping libraries.

Official SDKs by language

openrouteservice.org provides official SDKs for popular programming languages, facilitating direct integration with its API services. These SDKs are maintained by the openrouteservice.org team and are typically available through standard package managers for each language. They encapsulate the nuances of API communication, handling aspects like URL construction, parameter serialization, and response parsing.

Each SDK is designed to offer a consistent interface for the various openrouteservice.org APIs, including the Directions API reference, Isochrones API, and Geocoding API. This allows developers to switch between different API functionalities without learning entirely new paradigms.

Installation

Installing the openrouteservice.org SDKs typically involves using the respective language's package manager. Before installation, developers need to obtain an API key from the openrouteservice.org dashboard, which is essential for authenticating requests. The API key ensures that usage is tracked and managed according to the chosen plan, which includes a free tier of up to 2,500 requests/day.

JavaScript SDK Installation

For JavaScript projects, the openrouteservice-js package can be installed via npm or yarn. This SDK is compatible with both browser-based applications and Node.js environments.

npm install openrouteservice-js
# or
yarn add openrouteservice-js

After installation, the library can be imported into your JavaScript files. For web applications, consider optimizing the bundle size if only specific API functionalities are required, as some tools like Webpack's code splitting guide can assist with this.

Python SDK Installation

The Python SDK, openrouteservice-py, is available through pip, Python's package installer. It supports various Python versions and is commonly used in data science, backend services, and scripting for geospatial analysis.

pip install openrouteservice-py

Once installed, the Python library can be imported and utilized in any Python script or application. It provides convenient methods for constructing requests and parsing responses, aligning with typical Pythonic conventions.

Java SDK Installation

For Java developers, the openrouteservice-java library can be included in projects using Maven or Gradle, common build automation tools in the Java ecosystem. The dependency entry needs to be added to your project's pom.xml (Maven) or build.gradle (Gradle) file.

Maven

<dependency>
    <groupId>org.openrouteservice</groupId>
    <artifactId>openrouteservice-java</artifactId>
    <version>X.Y.Z</version> <!-- Replace X.Y.Z with the latest version -->
</dependency>

Gradle

implementation 'org.openrouteservice:openrouteservice-java:X.Y.Z' // Replace X.Y.Z with the latest version

After adding the dependency and refreshing your build, the Java client classes will be available for use within your Java application. The openrouteservice.org documentation portal provides the most current version numbers for each SDK.

Quickstart example

This section provides quickstart examples for fetching directions using the Python and JavaScript SDKs. These examples demonstrate basic API interaction, including client instantiation, setting up parameters, and processing the API response.

Python Quickstart: Get Directions

This Python example demonstrates how to use the openrouteservice-py SDK to request a driving route between two points. Replace 'YOUR_API_KEY' with your actual openrouteservice.org API key.

import openrouteservice

# Initialize the client with your API key
client = openrouteservice.Client(key='YOUR_API_KEY')

# Define coordinates (longitude, latitude for start and end)
start = [-87.65005, 41.85003]
end = [-87.65584, 41.85303]

# Request directions
# The profile can be 'driving-car', 'driving-hgv', 'cycling-road', 'cycling-mountain', 'cycling-electric', 'walking', 'foot-hiking', 'wheelchair'
routes = client.directions(
    coordinates=[start, end],
    profile='driving-car',
    format='geojson',
    instructions=True,
    units='km'
)

# Print the route geometry (GeoJSON LineString)
if routes and 'features' in routes:
    print("Route found:")
    print(routes['features'][0]['geometry']['coordinates'])
    print("\nFirst instruction:")
    if 'properties' in routes['features'][0] and 'segments' in routes['features'][0]['properties']:
        if routes['features'][0]['properties']['segments']:
            print(routes['features'][0]['properties']['segments'][0]['steps'][0]['instruction'])
else:
    print("No route found.")

JavaScript Quickstart: Get Directions

This JavaScript example illustrates how to use the openrouteservice-js SDK to obtain a driving route. This code can be run in a browser environment or with Node.js. Ensure you replace 'YOUR_API_KEY' with your valid openrouteservice.org API key.

import Openrouteservice from 'openrouteservice-js';

// Initialize the client with your API key
const ors = new Openrouteservice({
    api_key: 'YOUR_API_KEY'
});

// Define coordinates (longitude, latitude for start and end)
const start = [-87.65005, 41.85003];
const end = [-87.65584, 41.85303];

// Request directions
ors.Directions.get({
    coordinates: [start, end],
    profile: 'driving-car',
    format: 'geojson',
    instructions: true,
    units: 'km'
})
.then(function(response) {
    if (response && response.features && response.features.length > 0) {
        console.log("Route found:");
        console.log(response.features[0].geometry.coordinates);
        console.log("\nFirst instruction:");
        if (response.features[0].properties && response.features[0].properties.segments && response.features[0].properties.segments.length > 0) {
            console.log(response.features[0].properties.segments[0].steps[0].instruction);
        }
    } else {
        console.log("No route found.");
    }
})
.catch(function(err) {
    console.error("Error fetching route:", err);
});

These quickstart examples demonstrate the fundamental steps: client initialization with an API key, defining input parameters (like coordinates and routing profile), and handling the asynchronous response. The structure is similar across different API endpoints, requiring adjustment of the specific method call and parameters.

Community libraries

Beyond the official SDKs, the openrouteservice.org ecosystem benefits from community-driven libraries and integrations. These contributions often extend functionality, provide bindings for additional programming languages, or integrate openrouteservice.org capabilities into broader geospatial frameworks. While not officially maintained by openrouteservice.org, these libraries can offer alternative approaches or specialized tools for specific use cases.

Community libraries typically emerge from developers' needs to use openrouteservice.org in environments not directly covered by official SDKs or to add features like advanced visualization components. It is advisable to consult the respective project repositories for documentation, support, and discussions regarding the stability and maintenance status of these community efforts. Examples of such community engagement can be seen in other large open-source projects, where Google Maps Platform community resources often highlight user-contributed tools and examples.

Developers interested in contributing to the openrouteservice.org ecosystem or exploring existing community projects can often find links and discussions on the official openrouteservice.org community page, GitHub repositories, or forums dedicated to geospatial development. These resources provide avenues for sharing code, reporting issues, and collaborating on new tools that enhance the utility of openrouteservice.org APIs.