Application Programming Interfaces

The OpenRouteService API allows for programmatic access to our services and responds in JSON. We offer a comprehensive GET scheme for you to directly query the different services which is described in the following sections.


The query parameters are appended to the end of the specific service endpoint by means of query string encoding. Hence the general pattern for parameter usage is:

&parameter=value


Sections:


Routing Service

Returns a route between two or more locations for a selected profile and its settings as GeoJSON response. The routing endpoint uses /route? as the request action.


Query Parameters

The minimum requirements for a valid request are specified profile and coordinates parameters. Other parameters are optional but may contribute to the accuracy of your query.

Parameter Description
coordinates Pipe separated List of longitude,latitude coordinates visited in order.
profile Specifies the routing profile. Values are driving-car, driving-hgv, cycling-regular, cycling-road, cycling-safe, cycling-mountain, cycling-tour, foot-walking, foot-hiking and wheelchair.
preference Specifies the routing preference. Values are fastest(default), shortest and recommended.
units Specifies the distance unit . Values are m(meters, default) , km(kilometers) or mi(miles).
language Language for the route instructions. We currently support en(english - default), de(german), ru(russian), es(spanish) and cn(chinese), .
geometry Specifies whether to return geometry or not (default is True).
geometry_format Sets the format of a returned geometry. polyline, encodedpolyline(default) or geojson.
geometry_simplify Specifies whether to simplify the geometry (default is False). If True will be reset to False for a specified extra_info parameter.
instructions Specifies whether to return instructions or not (default is True).
instructions_format html for more verbose instructions. Default is text.
elevation Specifies whether to return elevation values for points or not (default is False).
extra_info # Pipe separated List of desired additional information. Values are steepness, suitability, surface, waycategory and waytype.
options # For advanced options formatted as json. Add object as string: "{...}".
id Arbitrary identification string of the request reflected in the meta information.

For further information regarding the differences between routing profiles, distance units and preference settings please visit our glossary.


Extra Information

For the encoding of the extra_info values see the response section or click on the respective link in the table:

Value Description
steepness Returns steepness information for each step.
surface Returns surface information for each step.
waytype Returns waytype information for each step.
waycategory Returns waycategory information for each step.
suitability Returns the suitability of a segment considering the chosen profile

Options

The following settings may be appended as strings to the options object.

Options Descriptions
maximum_speed Specifies a maximum travel speed in km/h.
avoid_features # Pipe seperated list of features to avoid. hills|ferries|...
vehicle_type Specifies the vehicle type.
profile_params # Specifies vehicle parameters.
avoid_polygons Comprises areas to be avoided for the route. Formatted as geojson polygon or geojson multipolygon.

Attention

The available parameters for avoid_features and profile_params may differ according to the selected routing profile.


Options Examples
- HGV example
- Cycling example
- Wheelchair example

Avoid Features

The following feature types provide means to avoid certain objects along your route:

Parameter Available For
highways driving-*
tollways driving-*
ferries driving-*, cycling-*, foot-*, wheelchair
tunnels driving-*
pavedroads driving-*, cycling-*
unpavedroads driving-*, cycling-*
tracks driving-*
fords driving-*, cycling-*, foot-*
steps cycling-*, foot-*, wheelchair
hills cycling-*, foot-*

Profile Parameters

For the driving-hgv profile we offer the following vehicle specifications to customize the route:

Parameter Description
length Specifies length restriction in meters.
width Specifies width restriction in meters.
height Specifies height restriction in meters.
axleload Specifies axleload restriction in tons.
weight Specifies weight restriction in tons.
hazmat Specifies whether to use appropriate routing for delivering hazardous goods and avoiding water protected areas. Default is false.

For the cycling-* profiles we offer the following fitness parameters to individualize the route:

Value Description
difficulty_level Specifies the fitness level. 0 = Novice, 1 = Moderate, 2 = Amateur, 3 = Pro.
maximum_gradient Specifies the maximum route steepness in percent. Values range from 1 to 15.

Attention

The maximum_gradient parameter can only be set if hills are avoided or difficulty_level is defined. Also you can only use difficulty_level or avoid hills at a time.


For the wheelchair profile we offer the following filters to individualize the route:

Parameter Description
surface_type Specifies the surface type. Default is "cobblestone:flattened".
track_type Specifies the grade of the route. Default is "grade1".
smoothness_type Specifies the smoothness of the route. Default is "good".
maximum_sloped_curb Specifies the maximum height of the sloped curb in meters. Values are 0.03, 0.06(default), 0.1 or any.
maximum_incline Specifies the maximum incline as a percentage. 3, 6(default), 10, 15 or any.

Response

The routing response consists of several components and is structured into summary, geometry_format, bbox, extras, geometry, segments and way_points for each route. By default it also includes the meta information.


Routes

Parameter Content
summary Contains total duration(in seconds), route distance(in units) and actual distance(in meters) of the route.
geometry_format Contains the defined geometry format.
bbox Contains the minimum bounding box of the route.
extras Contains the specified extra information.
geometry Contains the geometry in the defined geometry format.
segments List containing the segments and its correspoding steps which make up the route.
way_points List containing the indices of way points corresponding to the geometry.

Extras

For every information item there is an associated block divided into summary and values:

summary:broken down by information values.
Parameter Description
amount Percentage of the total route
distance Cumulative distance of this value
value Encoded value
values:broken down by way_points.
"values":[
        [
                0, // indice of the starting geometry for this section
                9, // indice of the end geometry for this section
                64 // value assigned to this section
        ], ...

Encoding of the extra information in detail:

Steepness
Value Encoding
-5 >16%
-4 12-15%
-3 7-11%
-2 4-6%
-1 1-3%
0 0%
1 1-3%
2 4-6%
3 7-11%
4 12-15%
5 >16%
Suitability

The suitability values for the selected profile range from 10 for best suitability to 1 for worst suitability.

Surface
Value Name
0 Unknown
1 Paved
2 Unpaved
3 Asphalt
4 Concrete
5 Cobblestone
6 Metal
7 Wood
8 Compacted Gravel
9 Fine Gravel
10 Gravel
11 Dirt
12 Ground
13 Ice
14 Salt
15 Sand
16 Woodchips
17 Grass
18 Grass Paver
WayCategory

The exponential assignment of the values is used for bit fields. One route section may belong to different categories. Hence a value of 97 would indicate a belonging to Paved road, Tunnel and Highway (64+32+1).

Value Name
0 No category
1 Highway
2 Tollway (driving-* profiles)
2 Steps (other profiles)
4 Ferry
8 Unpaved road
16 Track
32 Tunnel
64 Paved road
128 Ford
WayType
Value Name
0 Unknown
1 State Road
2 Road
3 Street
4 Path
5 Track
6 Cycleway
7 Footway
8 Steps
9 Ferry
10 Construction

Segments

duration:Contains the duration of the segment in seconds.
distance:Contains the distance of the segment in units.
steps:List containing the specific steps the segment consists of.

Steps

Parameter Description
duration The duration for the step in seconds.
distance The distance for the step in meters.
instruction The routing instruction text for the step.
type The instruction action for symbolisation purposes.
way_points List containing the indices of the steps start- and endpoint corresponding to the geometry.

Instruction Types
Value Encoding
0 Left
1 Right
2 Sharp left
3 Sharp right
4 Slight left
5 Slight right
6 Straight
7 Enter roundabout
8 Exit roundabout
9 U-turn
10 Goal
11 Unknown

The following example routes from coordinate 8.690614,49.38365 via 8.7007,49.411699 to 8.7107,49.45169 using the cycling-regular profile:

hostname/routing-test?profile=cycling-regular&coordinates=8.690614,49.38365|8.7007,49.411699|8.7107,49.45169&instructions=false&geometry_format=polyline&api_key=api-key

The resulting route has two segments with multiple steps. The geometry is returned as a polyline:

Toggle Example

Geocoding Service

We distinguish between geocoding and reverse geocoding depending on your input.

The geocoding endpoint uses /geocode? as the request action.


Geocoding

A geocoding request a returns a GeoJSON formatted list of objects corresponding to the search input.

Query Parameters

Parameter Description
query Name of location, street address or postal code.
lang Sets the language of the response. Available are de, en(default), fr and it.
limit Specifies the maximum number of responses. Default is set to 20.
id Arbitrary identification string of the request reflected in the meta information.

Response

The geocoding result contains as many features (if they exist) as the limit parameter was set to. It also contains the standard meta information.

geometry:Contains the coordinates and the geometry type which is a Point.
type:Specifies the JSON feature type.
properties:Contains the tag information of the point.

The following geocoding request searches for Berlin with a maximum of 5 response objects:

hostname/geocoding?format=json&query=Berlin&limit=5&api_key=api-key

As a response you will obtain the following JSON file with exactly 5 matches:

Toggle Example

Reverse Geocoding

As a result of a reverse geocoding request you will obtain one match (if it exists), namely the next enclosing object with an address tag which surrounds the given coordinate.

Query Parameters

Parameter Description
location Longitude,Latitude of the coordinate.
lang Language of the response. Available are de, en(default), fr and it
limit Specifies the maximum number of responses. Set to 1 for now.
id Arbitrary identification string of the request reflected in the meta information.

Response

The reverse geocoding result contains one feature (if it exists) as well as the meta information by default.

geometry:Contains the coordinate and the geometry type which is Point.
type:Specifies the JSON feature type.
properties:Contains the distance between the input location and the result point, the accuracy_score as well as the tag information of the point.

Hint

The accuracy_score is based on the distance. The closer a result is to the queried point, the higher the score.


The following example reverse geocodes the location 13.239515,52.514679:

hostname/geocoding-test?format=json&location=13.239515,52.514679&api_key=key

Resulting in one feature response:

Toggle Example

Isochrones Service

The Isochrone Service supports time and distance analyses for one single or multiple locations. You may also specify the isochrone interval or provide multiple exact isochrone range values. This service allows the same range of profile options listed in the ORS Routing section which help you to further customize your request to obtain a more detailed reachability area response. The isochrones endpoint uses /analyse? as the request action.

Query Parameters

Parameter Description
locations List of longitude,latitude coordinates delimited with pipe.
range_type time(default) for isochrones or distance for equidistants.
range # Maximum range value of the analysis in seconds for time and meters for distance. Alternatively a comma separated list of specific single range values
interval Interval of isochrones or equidistants for one range value. value in seconds for time and meters for distance.
units # Unit format. m(default), km or mi for distance. s for time.
location_type start(default) treats the location(s) as starting point, destination as goal.
profile Profile used for the analysis. driving-car(default), driving-hgv, cycling-road , cycling-mountain, cycling-tour, cycling-safe, foot-walking and foot-hiking.
attributes # Values are area and reachfactor. Delimit with pipe for both.
options # For advanced options formatted as json. Add object as string: "{...}".
intersections Specifies whether to return intersection polygons. Default is False.
id Arbitrary identification string of the request reflected in the meta information.

Range

There are three ways to use the range parameter:

single range:Returns one isochrone with the given range. range=value
with interval:Returns isochrones in interval gaps with range as outmost ring. range=value&interval=smaller_value
range list:Returns isochrones at the specified ranges. range=value_1,value_2,...,value_n

Units

range_type units
time m(meters default), km(kilometers) and mi(miles)
distance s(seconds)

Attributes

area:Returns the area of each polygon in its feature properties.
reachfactor:Returns a reachability score between 0 and 1

Note

As the maximum reachfactor would be achieved by travelling as the crow flies at maximum speed in a vacuum without obstacles, naturally it can never be 1. The availability of motorways however produces a higher score over normal roads.


Response

Every isochrone/equidistant will result in an object in the features-block. They will be sorted in groups for each location analysed (see group_index) as well as from closest to furthest range within each group. The result contains the standard meta informationby default.

geometry:Contains the coordinates and the geometry type which is Polygon.
type:Specifies the JSON feature type.
properties:Contains the center, group_index and value parameter for normal polygons. Contains contours for intersection polygons.
Properties Description
area The area of the polygon in square meters.
reachfactor The reachability score.
center The coordinates of the specific analysis location.
group_index The id of the isochrone based on the position in the locations query-parameter. Every location comprises its own group of polygons.
value The range value of this isochrone/equidistant in seconds/meters.
contours The indices of this intersection polygon.

Attention

Due to computational reasons we limit the total amount of received isochrones to 10 for each location.


Contours

Every intersection polygon comprises contours with an index array for each participating isochrone.

first value:Contains the group_index of the isochrone.
second value:Contains the isochrone-index numbered from the center, starting with 0.
Index Value Description
[X,..] Contains the group_index of the isochrone.
[..,X] Contains the isochrone-index numbered from the center, starting with 0.

The following example would indicate the intersection polygon between the 2nd isochrone of the 1st location, the 2nd isochrone of th 2nd location and the 1st isochrone of the 3rd location:

Toggle Example

This analysis request for the location 8.6984954,49.38092 uses the driving-car profile and searches for accessibility in range 500 seconds with an interval 200 seconds:

hostname/analyse?format=json&range=500&interval=200&locations=8.6984954,49.38092&profile=driving-car&api_key=api-key

The result supplies isochrones at 200 and 400 seconds and finally 500 seconds which corresponds to the range setting:

Toggle Example

Locations Service


Meta Information

The format of your response for all service endpoints is GeoJSON formatted.

Bbox

The Bbox object depicts the values of the minimum bounding box enclosing all feature results as follows:

{
        "bbox": [
                //minimum longitude,
                //minimum latitude,
                //maximum longitude,
                //maximum latitude
        ]
}

Info

The Info object summarizes your query settings.

About Description
service API endpoint used. geocoding, analysis or routing.
query Parameters that were specified in the query.
attribution Attribution for using our service.
version The ORS API version used for the request.
timestamp Unix timestamp of the precise request date.
id ID of the request specified in the id-Parameter.

Example:

{
        "info": {
            "service": "geocoding",
            "query": {
              "limit": 1,
              "location": [
                13.239515,
                52.514679
              ]
            },
            "attribution": "openrouteservice.org",
            "version": "4.0.0",
            "timestamp": 1484660155896
        }
}

Error Codes

HTTP Status Codes

The following table describes the supported HTTP status codes.

HTTP Status Code Description
200 Standard response for successfully processed requests.
400 The request is incorrect and therefore can not be processed.
405 The specified HTTP method is not supported. For more details, refer to the EndPoint documentation.
413 The request is larger than the server is able to process, the data provided in the request exceeds the capacity limit.
500 An unexpected error was encountered and more detailed internal error code is provided.
501 Indicates that the server does not support the functionality needed to fulfill the request.
503 The server is currently unavailable due to overload or maintenance.

Internal Error Codes

The following sections describes the list of possible internal error codes that might be provided by different ORS EndPoints.

Geocoding

Error Code Description
100 Unable to parse JSON request.
101 Required parameter is missing.
102 Invalid parameter format.
103 Invalid parameter value.
104 Parameter value exceeds the maximum allowed limit.
199 Unknown internal error.

Routing

Error Code Description
200 Unable to parse JSON request.
201 Required parameter is missing.
202 Invalid parameter format.
203 Invalid parameter value.
204 Parameter value exceeds the maximum allowed limit.
299 Unknown internal error.

Isochrones

Error Code Description
300 Unable to parse JSON request.
301 Required parameter is missing.
302 Invalid parameter format.
303 Invalid parameter value.
304 Parameter value exceeds the maximum allowed limit.
305 Requested feature is not supported.
399 Unknown internal error.

Locations

Error Code Description
400 Unable to parse JSON request.
401 Required parameter is missing.
402 Invalid parameter format.
403 Invalid parameter value.
404 Parameter value exceeds the maximum allowed limit.
499 Unknown internal error.