This repository stores the swagger specifications of the openrouteservice API in yaml and json format. For an API-Key please sign up at our developers portal. A live version of this documentation can be found in the API Playground.

This readme stores additional information, examples and encoding tables that go beyond the display options of swagger.

• Travel Time Calculation
  • Waytype
  • Surface
  • Tracktype
  • Pedestrian Speeds
  • Country Speed Sets
• URL Encoding
• Geocoding structured query
• Geocoding Response
  • Place Type
• Routing options
  • Examples
  • Border Restrictions
    • Country List
• Routing Response
  • Steepness
  • Suitability
  • Surface
  • WayCategory
  • Waytype
  • AvgSpeed
  • Tollways
  • TrailDifficulty
  • Instruction Types
  • Road Access Restrictions
  • Geometry Decoding
• Places Response
  • category_group_ids
  • category_ids
• Matrix Response

The travel time is calculated for each segment by using speed-limits for different waytypes and adjusting them for different grades or surfaces of the road. If multiple values apply for this segment, the lowest value is used. For cycling profiles also the steepness is considered. These limits can be reduced by setting the maxSpeed parameter in the options. The final average speed-limits can be requested by adding AvgSpeed to the extra_info parameter. The following table shows the initial speed-limits used for the main profiles:

(all Values in km/h)

Corresponds to the OSM highway tag value.

Corresponds to the OSM surface tag value.

Corresponds to the OSM tracktype tag value.

The foot-* profiles generally use 5 km/h on all allowed waytypes. Allowed waytypes consist of ways that are safe for use, ways that are better avoided (but still allowed) and other allowed ways in between:

As there are various traffic regulations in different countries. If maximum speed tag is not given in openstreetmap, we adjust the maximum speed according to the following key values taken from country specific speed limits.

To use the curl command string you have to encode special characters. Values you need are shown in this table:

Sometimes needs to be used for the options object.

A structured geocoding request is more precise than a normal one. It is also very useful for querying locations from tables. For a structured request insert a JSON Object with at least on of the following parameters into the query parameter of the geocoding request:

example:

{
  "address": "Berliner Straße 45",
  "locality": "Heidelberg",
  "country": "Germany",
  "postalcode": "69120"
}

uglyfied and encoded:

%7B"address": "Berliner Straße 45","locality": "Heidelberg","country": "Germany","postalcode": "69120"%7D

Explanation of returned parameters

Describes the returned location type

For advanced options formatted as json object. For structure refer to the examples below. The available parameters are:

• maximum_speed : Specifies a maximum travel speed restriction in km/h.

• avoid_features : Pipe (|) separated list of features to avoid. The available features are :

  Feature	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-*

• avoid_borders : "all" for no border crossing. "controlled" to cross open borders but avoid controlled ones. Only for driving-* profiles.

• avoid_countries : Pipe (|) separated list of countries to exclude from routing with driving-* profiles. Can be used together with "avoid_borders": "controlled". "11|193" would exclude Austria and Switzerland. List of countries and application examples can be found in the country list.

• vehicle_type (for profile=driving-hgv only): hgv,bus,agricultural,delivery,forestry and goods. It is needed for vehicle restrictions to work.

• profile_params : Specifies additional routing parameters.

  • weightings: Weightings will prioritize specified factors over the shortest path.

    • steepness_difficulty: Specifies the fitness level for cycling-* profiles.

      • level: 0 = Novice, 1 = Moderate, 2 = Amateur, 3 = Pro. The prefered gradient increases with level

    • green: Specifies the Green factor for foot-* profiles.

      • factor: Values range from 0 to 1. 0 equals normal routing. 1 will prefer ways through green areas over a shorter route.

    • quiet: Specifies the Quiet factor for foot-* profiles.

      • factor: Values range from 0 to 1. 0 equals normal routing. 1 will prefer quiet ways over a shorter route.

  • restrictions : Specifies restrictions for driving-hgv, wheelchair or cycling-* profiles.

    • for cycling-*:

      Parameter	Description
      gradient	Only for avoided hills or specified steepness_difficulty. Specifies the maximum route steepness in percent. Values range from 1 to 15. Routes with a higher gradient are avoided.

    • for driving-hgv: (you have to specify the vehicle_type in the options for these parameters)

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

    • for wheelchair:

      Parameter	Description
      surface_type	Specifies the minimum surface type. Default is "cobblestone:flattened".
      track_type	Specifies the minimum grade of the route. Default is "grade1".
      smoothness_type	Specifies the minimum smoothness of the route. Default is "good".
      maximum_sloped_kerb	Specifies the maximum height of the sloped kerb 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.

• avoid_polygons : Comprises areas to be avoided for the route. Formatted as geojson polygon or geojson multipolygon.

If your request works without the options object, but returns an error with it: try to %-encode the options object!

Some options examples in readable and minified JSON form:

for profile=driving-car:

{
    "maximum_speed": 100,
    "avoid_features": "ferries|tollways"
}

{"maximum_speed":100,"avoid_features":"ferries|tollways"}

for profile=cycling-*:

{
"maximum_speed": 18,
"avoid_features": "hills|unpavedroads",
"profile_params": {
    "weightings": {
        "steepness_difficulty": {
            "level": 2
        },
  "restrictions": {
            "gradient": 13
  }
    }
},
"avoid_polygons": {
    "type": "Polygon",
    "coordinates": [
        [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
 ]}
}

{"maximum_speed":18,"avoid_features":"hills|unpavedroads","profile_params":{"weightings":{"steepness_difficulty":{"level":2},"restrictions":{"gradient":13}}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}

for profile=foot-*:

{
    "avoid_features": "fords|ferries",
    "profile_params": {
        "weightings": {
            "green": {
                "factor": 0.8
              },
            "quiet": {
                "factor": 1.0
            }
        }
    },
    "avoid_polygons": {  
        "type": "Polygon",
        "coordinates": [
            [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
     ]}
}

{"avoid_features":"fords|ferries","profile_params":{"weightings":{"green":{"factor":0.8},"quiet":{"factor":1.0}}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}

for profile=driving-hgv:

{
    "avoid_features": "hills|ferries|tollways",
    "vehcile_type": "hgv",
    "profile_params": {
        "restrictions": {
            "length": 30,
            "width": 30,
            "height": 3,
            "axleload": 4,
            "weight": 3,
            "hazmat": true
        }
    },
    "avoid_polygons": {  
        "type": "Polygon",
        "coordinates": [
            [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
     ]}
}

{"avoid_features":"hills|ferries|tollways","vehcile_type":"hgv","profile_params":{"restrictions":{"length":30,"width":30,"height":3,"axleload":4,"weight":3,"hazmat":true}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}

for profile=wheelchair:

{
    "avoid_features": "hills|ferries|steps",
    "profile_params": {
        "restrictions": {
            "surface_type": "cobblestone:flattened",
            "track_type": "grade1",
            "smoothness_type": "good",
            "maximum_sloped_curb": 0.06,
            "maximum_incline": 6
        }
    }
}

{"avoid_features":"hills|ferries|steps","profile_params":{"restrictions":{"surface_type":"cobblestone:flattened","track_type":"grade1","smoothness_type":"good","maximum_sloped_curb":0.06,"maximum_incline":6}}}

Examples for routing options object with border restrictions:

Do not cross country borders at all:

{
    "avoid_borders":"all"
}

{"avoid_borders":"all"}

Do not cross controlled borders (i.e. USA - Canada) but allow crossing of open borders (i.e. France - Germany):

{
    "avoid_borders":"controlled"
}

{"avoid_borders":"controlled"}

Do not route through Austria or Switzerland:

{
    "avoid_countries": "1|120"
}

{"avoid_countries": "1|120"}

Pass open borders but do not cross into Switzerland:

{
    "avoid_borders": "controlled",
    "avoid_countries": "193"
}

{"avoid_borders": "controlled","avoid_countries": "193"}

Encoding of the Extra Information:

Negative values indicate decline, positive incline.

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

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 ).

This value is in km/h and equals the average speed for this way segment after grading and applying factors.

Tollway specific information for the selected mode of transport. Thus it depends on the profile if a ways is marked as tollway.

This extra provides information about a trails difficulty for hiking as well as for mountain-biking.

Provides information about possible restrictions on roads.

When a response include a geometry the data might be encoded as single string. When you request additional elevation data this encoded string can not be decoded with a the standard polyline decoders available (e.g. from Mapbox). The reason for that is, that the elevation data is included (additionally to the lat & lng values). To decode X,Y and X,Y,Z polylines the decoder needs to know whether the geometry has elevation information. Examples on how to decode X,Y,Z polylines can be found below:

Java:

import org.json.JSONArray;

public class GeometryDecoder {

    private static JSONArray decodeGeometry(String encodedGeometry, boolean inclElevation) {
        JSONArray geometry = new JSONArray();
        int len = encodedGeometry.length();
        int index = 0;
        int lat = 0;
        int lng = 0;
        int ele = 0;

        while (index < len) {
            int result = 1;
            int shift = 0;
            int b;
            do {
                b = encodedGeometry.charAt(index++) - 63 - 1;
                result += b << shift;
                shift += 5;
            } while (b >= 0x1f);
            lat += (result & 1) != 0 ? ~(result >> 1) : (result >> 1);

            result = 1;
            shift = 0;
            do {
                b = encodedGeometry.charAt(index++) - 63 - 1;
                result += b << shift;
                shift += 5;
            } while (b >= 0x1f);
            lng += (result & 1) != 0 ? ~(result >> 1) : (result >> 1);


            if(inclElevation){
                result = 1;
                shift = 0;
                do {
                    b = encodedGeometry.charAt(index++) - 63 - 1;
                    result += b << shift;
                    shift += 5;
                } while (b >= 0x1f);
                ele += (result & 1) != 0 ? ~(result >> 1) : (result >> 1);
            }

            JSONArray location = new JSONArray();
            try {
                location.put(lat / 1E5);
                location.put(lng / 1E5);
                if(inclElevation){
                    location.put((float) (ele / 100));
                }
                geometry.put(location);
            } catch (JSONException e) {
                e.printStackTrace();
            }
        }
        return geometry;
    }
}

JS:

  /**
   * Decode an x,y or x,y,z encoded polyline
   * @param {*} encodedPolyline
   * @param {Boolean} includeElevation - true for x,y,z polyline
   * @returns {Array} of coordinates
   */
  decodePolyline: (encodedPolyline, includeElevation) => {
    // array that holds the points
    let points = []
    let index = 0
    const len = encodedPolyline.length
    let lat = 0
    let lng = 0
    let ele = 0
    while (index < len) {
      let b
      let shift = 0
      let result = 0
      do {
        b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 // finds ascii
        // and subtract it by 63
        result |= (b & 0x1f) << shift
        shift += 5
      } while (b >= 0x20)

      lat += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1))
      shift = 0
      result = 0
      do {
        b = encodedPolyline.charAt(index++).charCodeAt(0) - 63
        result |= (b & 0x1f) << shift
        shift += 5
      } while (b >= 0x20)
      lng += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1))

      if (includeElevation) {
        shift = 0
        result = 0
        do {
          b = encodedPolyline.charAt(index++).charCodeAt(0) - 63
          result |= (b & 0x1f) << shift
          shift += 5
        } while (b >= 0x20)
        ele += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1))
      }
      try {
        let location = [(lat / 1E5), (lng / 1E5)]
        if (includeElevation) location.push((ele / 100))
        points.push(location)
      } catch (e) {
        console.log(e)
      }
    }
    return points
  }

The following tables contain the related names for the category_group_ids and the subordinate category_ids.

Category groups

Categories listed by group

The Matrix Response contains one matrix for each specified metrics value. In this matrix the items(rows) correspond to the number of sources and the entries(columns) of each item correspond to the number of destinations.

Here is a simple example for sources=2,3 and destinations=all with 4 locations:

The result is null if a value can't be determined.