Application Programming Interfaces

The ORS API allows for programmatic access to our services. We offer a GET scheme for you to directly query the API which is described in the following section. Please note that the response currently follows the OpenLS standard.

  1. Routing API
  2. Geocoding API
  3. Accessibility Analysis API

Routing API

The routing endpoint is defined as follows:

http://openls.geog.uni-heidelberg.de/route?

The query parameters are added to the end of the endpoint with query string encoding. Hence the pattern for parameter usage is:

&parameter=value

We distinguish between two types of parameters:

Required parameters:
 These are required.
Optional parameters:
 These parameters are not necessary for a functional request.

Required Parameters

The following parameters are required for the routing service to respond. For a valid request we require at least a starting and an end point in the form long,lat as well as your API key. If no further parameters are defined the API will fall back on a default object.

Parameter Description
start Pair of longitude,latitude coordinates used as the starting point of the route
end Pair of longitude,latitude coordinates used as the destination of the route
api_key your_api_key is inserted in this parameter

The Default Object

If one of these Parameters isn’t set, it will assume the below-mentioned default values.

Parameter Value
distunit KM
routpref Car
weighting Fastest

For further information regarding the specific routing profiles, distance units and weighting options please visit our glossary.


Optional Parameters

Parameters in this section are not required for a functional request, however these may contribute to the accuracy of your query. Some parameters only work with specific routing profiles. noSteps for example merely works with the Pedestrian or one of the Bicycle profiles. Please be aware which specific route preference you chose.

General Parameters

Parameter Description
via Semicolon-separated list of longitude,latitude coordinate pairs visited in order
lang Language for the route instructions. The default language is set to English en.
distunit Unit in which you want to view the distances in : km(kilometers)/m(meters)/mi(miles).
routepref Route profile for your course. Available profiles may be found in the table below.
instructions For routing instructions in your chosen language set to True.
geometry Set to False to exclude the route geometry from your response. Default is set to True
weighting Type of route the algorithm chooses. Modes are Fastest (default), Shortest and Recommended
maxspeed Maximum speed in km/h for the selected route profile e.g. maxspeed=10.

Hint

If you only want a route summary set geometry to false. Instructions are still available when set to true

routepref

The parameter routepref points to the selected routing mode. Please note that there are additional route preferences for the Bicycle and a subtype list for the HeavyVehicle type.

Preference Value Alternative Values
Car -
Pedestrian -
Bicycle BicycleMTB/BicycleRacer/BicycleTouring/BicycleSafety
Wheelchair -
HeavyVehicle There is a subtype list for the HeavyVehicle profile

Avoidable Features Parameters

The following feature types provide means to avoid certain objects along your route. Please be aware that these may be specific to your chosen route preference. Please note that avoidable parameters for alternative route preferences correspond to their parent profile. The default value is set to False.

Parameter Profiles
noMotorways Car, HeavyVehicle
noTollways Car, HeavyVehicle
noTunnels Car, HeavyVehicle
noPavedroads Bicycle
noUnpavedroads Car, Bicycle, HeavyVehicle
noTracks Car, HeavyVehicle
noFerries Car, Bicycle, Pedestrian, HeavyVehicle
noFords Car, Bicycle, Pedestrian, HeavyVehicle
noSteps Bicycle, Pedestrian

Bicycle Specific Parameters

For the Bicycle profiles we offer additional filters to finetune your route.

Parameter Description
elevation True to retrieve elevation information for each returned point in the response.
surface True to retrieve way surface information for your route.
noHills True to avoid steep gradients. You may either set this option or set the level parameter.
level Corresponds to the fitness level. 0 = Novice, 1 = Moderate, 2 = Amateur, 3 = Pro.
steep Which relates to the maximum steepness given as a percentage. The range of values is from 1 to 15.

The surface parameter provides decoded values for the surfacetype and the waytype.

Attention

The steep parameter can only be set if noHills or level is defined. Also you can only use noHills or level at a time.

Wheelchair Specific Parameters

For the Wheelchair profile we offer additional filters to finetune your route.

Parameter Description
surtype Corresponds to the surface type. Ranges from type 1 which only uses smooth surface types to 5 which uses all traversable surfaces. Default is set to 2
incline Relates to the maximum incline as a percentage. 3, 6(default), 10, 15 or any
curb Corresponds to the maximum height of the sloped curb in centimeter. 3, 6(default), 10 or any
surtype Encoding

This is the encoding for the surtype values which refer to a specific surface type.

Value Description
1 concrete, asphalt
2 flattened cobblestone and better
3 cobblestone and better
4 compacted
5 all traversable surfaces

HeavyVehicle Specific Parameters

For the HeavyVehicle profiles we offer additional filters to finetune your route according to specific vehicle options.

Parameter Description
haz True for an appropriate routing while delivering hazardous goods and avoiding water protected areas.
value_weight Maximum weight restriction in tons.
value_height Maximum height restriction in meters.
value_width Maximum width restriction in meters.
value_length Maximum length restriction in meters.
value_axleload Maximum axeload restriction in tons.
subtype Defines a HeavyVehicle subtype. hgv(default), Agricultural, Bus, Delivery, Foresty or Goods.

Examples

The shortest version of a full functioning query would comprise the following parameters:

http://openls.geog.uni-heidelberg.de/route?start=9.258506,49.240011&end=9.2556609,49.2397316&api_key=ee0b8233adff52ce9fd6afc2a2859a28

This example corresponds to a route for the route preference Car from a starting point to a destination with no direction-instructions. The distance values will be returned in kilometers and the route weight is set to Shortest. The response will be in the following format:

Show/Hide Code

Attention

Parameters as well as values are case sensitive. The input order doesn’t matter though.


Response Values

This is the encoding for the Surface and Waytype you will encounter in your response file if surface is set to True.

Response Surfacetype List

Value Encoding
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

Response Waytype List

Value Encoding
0 Unknown
1 State Road
2 Road
3 Street
4 Path
5 Track
6 Cycleway
7 Footway
8 Steps
9 Ferry
10 Construction

Response Steepness List

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%

Errors

Currently we are not supporting an error coding. If your route could’t be rendered the xml file will contain an error Message similar to this:

<xls:ErrorList>
 <xls:Error errorCode="Unknown" severity="Error" locationPath="OpenLS Route Service - RSListener, Message: " message="Internal Service Exception: java.lang.Exception Internal Service Exception Message: Cannot find point 0: 20.38325080173755,14.721679687500002 ..."/>
</xls:ErrorList>

In that case there aren’t any roads in the vicinity of the start and endpoint. Please try to place your points closer to the road network.

Restful Webservice

This Link contains a testclient with meta information and schema file in which an example for a routing request can be viewed.


Geocoding API

The geocoding endpoint is defined as follows:

http://openls.geog.uni-heidelberg.de/geocode?

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

Geocoding Parameters

A geocoding request returns a list of coordinates matching your search input.

Parameter Description
FreeFormAddress Name of location, street address or postal code.
MaxResponse Maximum number of responses. Default is set to 20.
api_key your_api_key which is placed within this parameter

Reverse Geocoding Parameters

As a result of a reverse geocoding request you will always get exactly one match, namely the next enclosing object which surrounds the given coordinate.

Parameter Description
lon Longitude of coordinate of interest.
lat Latitude of coordinate of interest.
pos Alternative and replaces the lat and lon parameter. Longitude Latitude of the coordinate.
lang Language settings of reversed geocode response de (Deutsch), en (English)(default)
api_key your_api_key which is placed within this parameter

Example

The following example shows a search request for Heidelberg, Mathematikon with a maximum of 10 response objects:

http://openls.geog.uni-heidelberg.de/geocode?FreeFormAddress=Heidelberg,%20Mathematikon&MaxResponse=10&api_key=ee0b8233adff52ce9fd6afc2a2859a28

As a response you will obtain the following xml file with exactly 3 matches:

Show/Hide Code

The following example shows a reverse geocoding example which will return exactly one object:

http://openls.geog.uni-heidelberg.de/geocode?pos=13.4127 52.5220&api_key=ee0b8233adff52ce9fd6afc2a2859a28

As a result you will obtain the full address as well as the distance from the queried point to the center of the response object:

Show/Hide Code

Restful Webservice

This Link contains a testclient with meta information and schema file in which an example for a geocode request can be viewed. The reverse geocode request can be found here.


Accessibility Analysis API

The accessibility analysis endpoint is defined as follows:

http://openls.geog.uni-heidelberg.de/analyse?

Parameters

As minimum requirements this endpoint will need the position and api_key parameters. There are default values for the remaining parameters.

Parameter Description
position Pair of longitude,latitude coordinates for the specific point of interest.
routePreference The route preference which may be Car(default), Pedestrian, Bicycle and HeavyVehicle.
method Method of generating the Isochrones. This may either be RecursiveGrid(default) or TIN
interval Interval of isochrones in seconds e.g. 300 for 5 minutes. The default is set to 300.
minutes Maximum range of the analysis in minutes e.g. 0-30. The default is set to 10.
api_key your_api_key is inserted within this parameter.

Note

The interval parameter must be equal or smaller than the minutes parameter. For a maximum range of minutes=30 the maximum interval would be interval=1800.


Example

The following example is rendered with the RecursiveGrid method and has a maximum range of 4 minutes with a 2 minute set interval:

http://openls.geog.uni-heidelberg.de/analyse?api_key=ee0b8233adff52ce9fd6afc2a2859a28&position=8.661367306640742,49.42859632294706&minutes=4&interval=120

The result gives us two isochrones with a corresponding 2 minute distance:

Show/Hide Code

Restful Webservice

This Link contains a testclient with meta information and schema file in which an example for a AA request can be viewed.