ORS API (OpenRouteService)
Aug 27,2026

GISBox is a one-stop 3D GIS data editing, conversion and publishing platform that supports editing in multiple GIS formats such as OSGB/GEOTIFF/RVT, converting to 3DTiles/Terrain and publishing.

Introduction

ORS API (OpenRouteService) is an open-source geospatial routing service based on OpenStreetMap data. It provides RESTful interfaces and supports route planning for multiple travel modes including driving, walking, and cycling, as well as isochrone analysis, distance matrix calculation, geocoding, elevation queries, track matching, and multi-point route optimization. It is developed in Java, follows the GPLv3 open-source license, and can be deployed independently via Docker or accessed directly through its public API. It is widely used in scenarios such as navigation applications, logistics and delivery, urban planning, and outdoor sports.

File Structure

The core file structure of the ORS (OpenRouteService) project is mainly as follows:

docs/: Project documentation directory, containing user manuals, API interface descriptions, configuration guides, and other documentation.
docs/run-instance/configuration/: Directory dedicated to storing service deployment and runtime configuration files; the core file is ors-config.yml.
ors-engine/: Core routing engine module directory, responsible for core algorithmic logic including path calculation, isochrone analysis, and matrix calculations.
ors-engine/src/main/files/osm/: Directory used to store OpenStreetMap (OSM) data files; map data must be placed here and referenced in the configuration.
logs/: Log directory, where log files generated during service operation (e.g., ors.log) are stored for error troubleshooting and operational status monitoring.
ors-api/: RESTful API interface layer directory, exposing HTTP endpoints such as /v2/directions, /v2/isochrones, /v2/matrix, /v1/geocode, and /v2/status.
tests/: Test suite directory, containing unit test and integration test code.
docker/ (or related deployment directory): Contains configuration files required for Docker deployment (such as Dockerfile, docker-compose.yml, etc.) to facilitate containerized deployment.

Pros

Completely open-source and free: Based on the GPLv3 license, with no API call fees or licensing costs. Costs are limited to server hardware and data storage, and it can be quickly deployed via Docker.
Data privacy and sovereignty controllable: Supports on-premises deployment, with all route calculations and geocoding completed on your own servers. Sensitive location data never leaves the corporate intranet, meeting privacy compliance requirements such as GDPR.
Feature-rich and modular: Provides multiple API endpoints including directions, isochrones, distance/time matrices, geocoding, elevation queries, and track matching. Supports multiple travel modes such as driving, walking, cycling, and wheelchair.
Highly customizable: Allows customization of routing rules, speed configurations, turn costs, road type preferences, avoidance areas, and custom weight functions to meet specific needs in logistics, urban planning, outdoor sports, and other scenarios.
Strong technical autonomy: Code is permanently accessible, unaffected by commercial service price increases, API changes, or service shutdown risks. The community continues to maintain it, ensuring sustainable project development.
Active community and documentation: Features comprehensive official documentation, a Swagger UI interactive test interface, multi-language client libraries (Python, JavaScript, Dart, etc.), and a rich case library.

Cons

Relatively high deployment and configuration barriers: Mandates specifying the configuration file path via environment variables, which goes against the "out-of-the-box" principle, requiring additional configuration from new users before it can run. First-time deployment requires manually downloading OSM data, writing a YAML configuration file, and starting the Java service.
Outdated or biased road network data: OSM data update cycles vary by travel mode (quarterly for driving, annually for cycling, semi-annually for walking, etc.). Issues such as missing one-way streets, ignored overpass levels, unincorporated footbridges, and insufficient slope accuracy may exist.
High performance and resource demands: Built on Java, route calculation requires significant memory and CPU resources (JVM heap size of 4–8 GB is recommended). Large-data-volume scenarios require chunked processing and SSD storage support. Self-hosted services require undertaking operations, maintenance, and optimization work.
Matrix API does not return specific paths: The time/distance matrix API can only compute distances and times between multiple points and cannot return the specific route geometry between any two points.
Limited real-time traffic data support: ORS itself does not provide real-time traffic conditions. Additional paid access to third-party data sources such as TomTom or Here is required to enable dynamic route planning.
Free public API has usage limits: The free tier of the official public API is limited to only 500 requests per month. Exceeding this limit returns a 403 error, and high-traffic applications still require self-hosted instances.

Application Scenario

ORS API is widely used in logistics and delivery for planning multi-stop optimal delivery routes and calculating delivery isochrone ranges. In urban planning and traffic management, it can assist in analyzing walkability and cyclability, evaluating road accessibility, and conducting public transit stop coverage analysis. In outdoor sports and tourism scenarios, it provides track navigation and distance calculation services for hiking and cycling applications. Additionally, it can be used for shortest path searching in emergency rescue, commuting time assessment in real estate, and spatial accessibility and travel behavior research by scientific institutions, among various other scenarios.