Skip to content

Server API

Jump to bottom Edit New page
Emil Tin edited this page May 26, 2014 · 3 revisions

The API on routes.ibikecph.dk can be used to:

  • Compute route
  • Find nearest node
  • Find nearest point on a street

You can specify either normal bikes or cargobikes (which has separate road networks) by using one of these two base URLs:

http://routes.ibikecph.dk/normal/...

http://routes.ibikecph.dk/cargobike/...

You are welcome to use the API, as long as you adhere to our [API Usage Policy](API Usage Policy).

The API is served by a modified version of the OSRM software. See https://github.com/DennisOSRM/Project-OSRM/wiki for more info about the mainline version of OSRM.

The definitive specification on how we compute routes is the LUA file https://github.com/ibikecph/Project-OSRM/blob/master/profiles/bicycle.lua.

Location format

All locations are specified using (latitude,longitude) coordinates in the WSG-84 coordinate system. 5 decimal points are used. Note that you cannot pass address strings to the API. If you're UI accept address strings, you will need to first use an external geocoding service to translate addresses to coordinate points.

Compute route

To compute a route from (lat1,lon1) to (lat2,lon2):

http://routes.ibikecph.dk/normal/viaroute?loc=lat1,lon1&loc=lat2,lon2

To compute a route that includes via point, list all locations in the order they should be visited:

http://routes.ibikecph.dk/normal/viaroute?loc=lat1,lon1&loc=lat2,lon2&loc=lat3,lon3&loc=lat4,lon4&...

Optional parameters

A number of additional parameters can be passed when computing routes:

  • z=[0-18] specifies the zoom level and simplifies the route geometry accordingly. At low zoom level, the geometry is simplified further. At zoom levels 14 or lower, isolated ways will be filtered away to avoid 'route not found'.
  • output=[json|gpx] format the output as JSON or GPX. JSON is default.
  • jsonp=function. Format the output as JSONP (JSON wrapped by a JavaScript function. Also works for nearest/ and locate/.
  • &instructions=[true|false]. Pass false to supress instructions. For example, when a user drags a pin on a map, instructions should only be requested when the user stop moving the pin. Default is true.

Output

The output is formatted as JSON. For example the query http://routes.ibikecph.dk/standard/viaroute?&loc=55.66151,12.59617&loc=55.66500,12.60458 returns:

{
  "version": 0.3,
  "status": 0,
  "status_message": "Found route between points",
  "route_geometry": "ukvrI{d{kA]iCF]DWs@aEo@sDESu@iE[gBoAeGORo@r@e@`@oAhAOLEc@YcCc@wC[}CGc@UiBIm@Q}A",
  "route_instructions": [
    [
      "10",
      "{highway:service}",
      46,
      0,
      15,
      "46m",
      "E",
      69,
      1
    ],
    [
      "2",
      "Sundholmsvej",
      18,
      1,
      7,
      "18m",
      "SE",
      115,
      1
    ],
    [
      "8",
      "Brigadevej",
      336,
      3,
      90,
      "336m",
      "NE",
      65,
      1
    ],
    [
      "7",
      "Amagerbrogade",
      125,
      9,
      40,
      "125m",
      "NW",
      325,
      1
    ],
    [
      "3",
      "Holmbladsgade",
      253,
      14,
      39,
      "253m",
      "E",
      74,
      1
    ],
    [
      "15",
      "",
      0,
      22,
      0,
      "",
      "N",
      0.0
    ]
  ],
  "route_summary": {
    "total_distance": 781,
    "total_time": 216,
    "start_point": "{highway:service}",
    "end_point": "Holmbladsgade"
  },
  "alternative_geometries": [],
  "alternative_instructions": [],
  "alternative_summaries": [],
  "route_name": [
    "Brigadevej",
    "Holmbladsgade"
  ],
  "alternative_names": [
    [
      "",
      ""
    ]
  ],
  "via_points": [
    [
      55.66155,bike
      12.59614
    ],
    [
      55.66473,
      12.60474
    ]
  ],
  "hint_data": {
    "checksum": -1357205386,
    "locations": [
      "zjkRAK8AAACSAAAAbwAAAKr0FM7VIeI_AQEAAMvuVABeOBMAhn8AAK",
      "qU4AAPAAAABKAAAAcQAAAOuDAxAMQ9k_AQFDtAnwVAC6OxMAhn8AAG"
    ]
  },
  "transactionId": "OSRM Routing Engine JSON Descriptor (v0.3)"
}

You can view the example route on a map here: http://www.ibikecph.dk/#!/x50p5.7hz9k/x53dz.7i5r7.

Description of fields:

version

The version of the routing OSRM software that computes routes.

status

A status code indicating whether a route was found:

  • 0 - Route found
  • 207 - no route found between the two points. This can happen if a location is placed on a way that is not connected to the rest of the road network, or is located far away from any street.

status_message

A string containing a status message, which can be:

  • Found route between points
  • Cannot find route between points

route_geometry

A string containing the geometry of the route encoded with Encoded polyline algorithm. You need to decode the string to get the actual geometry. See https://github.com/ibikecph/ibikecphsite/blob/master/app/assets/javascripts/app/util.js.coffee#L73 for an example of how this is done in The ibikecph.dk CoffeeScript front-end.

route_instructions

Each route instruction is an array of 9 fields [instruction,"streetname",length,position,time,"length","earth_direction",azimuth,mode]. For example, the second instruction above is: ["2","Sundholmsvej",18,1,7,"18m","SE",115,1].

Explanation of the individual fields of instruction arrays:

  • 0 - Turn instruction (string). Defined as 0=NoTurn, 1=GoStraight, 2=TurnSlightRight, 3=TurnRight, 4=TurnSharpRight, 5=UTurn, 6=TurnSharpLeft, 7=TurnLeft, 8=TurnSlightLeft, 9=ReachViaPoint, 10=HeadOn, 11=EnterRoundAbout, 12=LeaveRoundAbout, 13=StayOnRoundAbout, 14=StartAtEndOfStreet, 15=ReachedYourDestinatio

  • 1 - Way name (string).

  • 2 - Length in meters (integer). The distance until the next turn instruction.

  • 3 - Position (integer)

  • 4 - Time in seconds (integer)

  • 5 - Length with unit (string). Same as field 0, but as a string with the unit appende, ex "125m".

  • 6 - Direction (string). The rough compass direction, one of N,NE,E,SE,S,SW,W,NW

  • 7 - Azimuth (float). The precise compass direction, from 0 to 360.

  • 8 - Mode. Defined as 1=Bike, 2=Pushing, 3=Ferry, 4=Train

route_summary

  • total_distance (integer): total length in meters

  • total_time (integer): total trip time in seconds

  • start_point (string): Name of the first street, or OSM way type.

  • end_point (string): Name of the first street, or OSM way type.

route_name

Array of strings giving the name of roads.

via_points

Array of via points, each via point is an array of coordinates: [lat, lon]

hint_data All start/end/via points are moved to the nearest point in a street before computing routes. The hint_data field contains the moved locations in encoded format.

  • checksum (integer). Only used for passing back to the API.
  • locations : Array of nearest locations on the road network.

When you compute a route similar to the previous one, for example when the user drags a pin on a map, passing the encoded locations will result in faster results. When using the API to compute several similar routes, client must therefore:

  • Append &checksum=..., using hint_data.checksum from the previous result as the value.
  • Append &hint=... after each &loc=... parameter if it did not change from the previous request. If a coordinate has changed, don't provide any hint. Hints have to be placed directly behind the corresponding &loc=... parameter.

Ways without names

If a street name has no name, the OSM way type will be passed instead, in the form "{highway:way_type}". You're expected want to decode and translate the way type, for example by translating "{highway:cycleway}" into "Cycleway" (english) / "Cykelsti" (danish) / etc.

Alternative routes

The API can optionally try to find suitable alternative routes. The API looks for routes that are sufficiently different that the main route, but not too much longer. Alternatives are not always found. When they are, they are always of the same fundamental route type (bike/cargobike). When alternatives are requested (alt=true), the following arrays may contain elements, one for each alternate route:

alternative_geometries Array of route_geometry

alternative_instructions Array of route_instructions

alternative_summaries Array of route_summary

alternative_names Array of route_name

Find nearest node

To find the nearest OSM node on the road network:

http://routes.ibikecph.dk/normal/locate?loc=_lat_,_lon_

Respons format:

{
    "version": 0.3,
    "status": 0,
    "mapped_coordinate": [
        52.41427,
        13.32626
    ],
    "transactionId": "OSRM Routing Engine JSON Locate (v0.3)"
}

Find nearest point on a street

To find the nearest point on a street:

http://routes.ibikecph.dk/normal/nearest?loc=_lat_,_lon_

Respons format:

{
    "version": 0.3,
    "status": 0,
    "mapped_coordinate": [
        52.42259,
        13.33383
    ],
    "name": "Mariannenstraße",
    "transactionId": "OSRM Routing Engine JSON Nearest (v0.3)"
}

Real-world examples

To see real-world examples of using the API, you can go to http://www.ibikecph.dk, and use the develop console to see what request are send when you place and move pins. The source code for the website is available at https://github.com/ibikecph/ibikecphsite. Code for iPhone and Android apps using the API can be found at https://github.com/ibikecph/ibikecph-app and https://github.com/ibikecph/ibikecph-android.

Add a custom footer
Add a custom sidebar
Clone this wiki locally