openrouteservice Io is here!

The openrouteservice from HeiGIT has just had its latest update, and we want to introduce you to Io (version 5.0). This new version brings something that has been a while in the making and will make things a lot easier when it comes to requesting information from the openrouteservice – a new API (v2) that is based purely on POST requests using JSON objects. Now, rather than encoding all of the information needed for generating a route inside the querystring of a GET request, (almost) all the information is now contained in a nicely formatted and structured JSON body request.
The request information itself remains mostly unchanged, with just some alterations to improve the structure. One of the biggest changes for that is that all pipes are gone (yay!) when it comes to providing multiple values for a parameter – now they are all contained in nice JSON arrays.
All responses follow the same format as the previous API (though for the directions service, geometry in the JSON response format is now restricted to Encoded Polyline – we strongly recommend the use of the GeoJSON format when the size of data transmission is not an issue). This means that if you want to update your own services to use the new API (which we thoroughly encourage), handling of the route that is returned should require minimal alterations, if any are needed at all. You will need to update your request generator, but with the use of nice clean JSON objects, that should be relatively straightforward. And if you do get stuck, we have our forum where you can post questions and we will be happy to lend our eyes and minds to helping you out. If you are not feeling up to moving to the v2 API yet, don’t worry as the old API will stay exactly the same for the next year (though you may miss out on some cool new features that are coming which will only be in the new API).

Examples

Requests to the openrouteservice v2 API use POST requests with the following format:

https://api.openrouteservice.org/v2/{service}/{profile}

For the routing endpoint, you can also add the response format (json, geojson, gpx) to the url:

https://api.openrouteservice.org/v2/directions/{profile}/{response format}

All parameters that are used for the services are passed as the request body in a JSON object.

For a request to the routing service using the old API, you would use something like

https://api.openrouteservice.org/directions?profile=driving-car&coordinates=
49.2315,8.89267|49.47223,8.72366&preference=shortest&extra_info=surface|waytype&format=geojson

With the new API you would send to

https://api.openrouteservice.org/v2/directions/driving-car/geojson

the body request of

{
  "coordinates": [
    [49.2315,8.89267],
    [49.47223,8.72366]
  ],
  "preference": "fastest",
  "extra_info": [
    "surface",
    "waytype"
  ]
}

For a full list of parameters that can be passed, you can look at our interactive documentation where you can also have a play around.

More features

The Io release didn’t just update the API, but also introduced a number of additional features and fixes including (amongst others):

Updating Isochrones so that smaller distance isochrones are more accurate

When you generate isochrones for smaller distances, the algorithms have been updated to make them more accurate.

Allowed the passing of ISO country codes when choosing to avoid countries

The avoid countries/borders functionality has been available for some time on the openrouteservice, but now we have made it better by allowing you to pass the ISO 2 or 3 digit country code rather than our internal country ID. So now rather than passing …avoid_countries:39|130|2… you can use …avoid_countries:DEU|CHZ|FRA…

Inclusion of freehand route segments

Now it is possible to skip segments of a route using the freehand route segments. Using these, you can define waypoints (as normal) and then tell openrouteservice to not generate routes between combinations of these waypoints, which can be of great use when you know your own way between two places and don’t want suggestions. More information about this will be coming soon, so watch this space…

Also, to allow an upcoming enhancement relating to super fast routing whilst still using restrictions, some options have unfortunately had to be removed from the API. These include some avoid_features (pavedroads, unpavedroads, tunnels, tracks, and hills) as well as the maximum_speed, fitness_level and maximum_steepness (for cycling and walking profiles).

Io

Io is the closest of Jupiter’s so called 4 “Galilean Moons” which got their names as they were first viewed by a human when Galileo pointed his telescope to the bright dot in the night sky that was Jupiter. It is the most geologically active body in the solar system which is due to the constant squeezing inflicted on it by Jupiter and the other Galilean Moons which heats up its interior to cause volcanic eruptions up to 500km high (The International Space Station orbits Earth 408km above the Earth’s surface…).