OS Routing API Beta
Technical Specifications
Contents
Technical Specifications ............................................................................................................................ 1
Introduction ..................................................................................................................................................... 2
Purpose of this specification and disclaimer ............................................................................................ 2
Copyright in this specification .................................................................................................................... 2
Chapter 1
Overview .................................................................................................................................... 3
Capabilities ................................................................................................................................................. 3
Service Content and Structure .................................................................................................................. 3
Chapter 2
Service Requests ...................................................................................................................... 5
Resource Summary................................................................................................................................ 5
HTTP Codes ........................................................................................................................................... 5
Error Messages ...................................................................................................................................... 5
Chapter 3
Service Requests ...................................................................................................................... 8
Route Request Parameters .................................................................................................................... 8
Route Request Response ..................................................................................................................... 10
Introduction
Purpose of this specification and disclaimer
This is the technical specification (hereafter referred to as the specification) applicable to the OS Routing API
Beta (hereafter referred to as the product), which is referred to in the Framework Direct Licence, Specific Use
Framework Partner Licence or your other customer contract for the product.
Copyright in this specification
This specification, (including for the avoidance of doubt any mapping images reproduced herein), is
© Crown copyright 2012. All rights reserved.
Any part of this specification may be copied for use internally in your organisation or business so that you can
use OS Routing API Beta for the purpose for which it is licensed to your organisation or business (but not
otherwise).
No part of this specification may be reproduced or transmitted in any form or by any means (including
electronically) for commercial exploitation without the prior written consent of Ordnance Survey.
No part of this specification may be copied or incorporated in products, services or publications that you
generate for onward sale, or as free promotional or support materials, without the prior written consent of
Ordnance Survey
Chapter 1
Overview
This documentation is intended to give a technical description of the OS Routing API Beta. The service will
enable customers to perform on-road and off-road routing with multiple transport options. The service is
based on the graphHopper Directions API which can be found here:
https://github.com/graphhopper/directions-api/blob/master/README.md
The URL for the service is:
https://api.ordnancesurvey.co.uk/
For vehicular routing, the resource collection is routing_api, and for nonvehicle routing it is
non_vehicle_routing_api, each with the resource sub-collection of route, resulting in the URLs:
https://api.ordnancesurvey.co.uk/routing_api/route
https://api.ordnancesurvey.co.uk/nonvehicle_routing_api/route
Capabilities
The purpose of the OS Routing API is to allow turn-by-turn A –> B navigation across Great Britain for vehicular
and non-vehicular methods of transport. Currently this includes navigation for cars (roads), cycling and, within
National Parks, walking. There is also the capability to add waypoints allowing for A -> B -> C routing. The
service supports EPSG:27700 and EPSG: 4326.
Service Content and Structure
The Service shall be a collection of RESTful resources that shall accept HTTPS requests and return
responses over HTTPS.
The service protocol shall be HTTPS.
The sub-domain shall be api.ordnancesurvey.co.uk
The resource collections shall be routing_api and nonvehicle_routing_api
The resource sub-collection shall be /route
The version shall be v1
The Service shall respond to GET requests. The Service shall also respond to OPTIONS requests.
OPTIONS is supported as part of implementing the Cross-Origin Resource Sharing specification
The Service shall support the W3C Cross Origin Resource sharing specification
(http://www.w3.org/TR/cors/).
All parameters and values shall be accepted in any mix of lower or upper case characters.
The Service shall accept Resource Name's in lowercase.
The format of the response can be specified using the type parameter The Service shall return
responses in XML (GPX) and JSON. Default value is JSON.
The Service shall include the Content-Type in the HTTP header for all responses.
The Service shall return data using a Unicode character set (UTF-8) - that includes accents.
If no data is found for the customer’s request then an empty list should be returned (in either JSON or
XML depending on the request. Default is JSON).
The Service shall use the authentication method of API key - the parameter for the API key shall be
key. This key is generated within the Business Support System (Apigee)
Chapter 2
Service Requests
Resource Summary
Below is a table that contains the resources for the service
Method
Resource
Authorisation
Description
GET
/route
API Key
To get a route
OPTIONS
/route
API Key
To implement CORS and pre-flight requests
GET
/nearest
API Key
To get the nearest point on the network
OPTIONS
/nearest
API Key
To implement CORS and pre-flight requests
HTTP Codes
The following table summarises the HTTP response codes the service should be able to respond with.
Code
Description
200
Request has been successful
400
Bad request. E.g. missing query parameter, malformed syntax
401
Unauthorized – the client has not provided authentication or incorrect authentication
404
The server has not found anything matching the Request-URI.
405
Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
500
Generic internal server error
503
Service unavailable due to overloading or maintenance.
Error Messages
The OS Routing API Beta also provides detailed error messages in text/json or text/xml dependent on what has been
requested. Default is json. Values in italics should be replaced with the relevant variable.
Error Type: Requested resource name that does not exist
Error Message: Resource requested_resource does not exist. Valid resources are list_valid_resources
Example JSON:
Example XML:
{
"error": {
"statuscode": "404",
"message": "Resource N does not exist. Valid
resources are route, nearest."
}
}
<?xml version="1.0"?>
<error>
<statuscode>404</statuscode>
<message>"Resource N does not exist. Valid
resources are route, nearest."</message>
</error>
Error Type: Request does not include a mandatory parameter
Error Message: No missing_parameter provided
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "No point parameter provided"
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"No point parameter
provided"</message>
</error>
Error Type: Request includes a non-valid value for a parameter
Error Message: Non-valid_value is not a valid value for parameter parameter_name. Valid values are
list_valid_values.
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "blah is not a valid value for
parameter type. Valid values are JSON, GPX."
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"blah is not a valid value for
parameter type. Valid values are JSON,
GPX."</message>
</error>
Error Type: Request includes a parameter name that is not valid for the chosen resource
Error Message: Non-valid_parameter_name is not a valid parameter for resource requested_resource. Valid
parameters are list_valid_parameters.
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "Parameter blah is not a valid
parameter for resource nearest. Valid
parameters for requested
resource are point."
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"Parameter blah is not a valid
parameter for resource nearest. Valid
parameters for
requested resource are point."</message>
</error>
Error Type: Request has an invalid point for nearest or route resource
Error Message: Point requested_point is not a valid point. Point must be a comma separated coordinate in
requested_or_default_SRS projection.
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "Point requested_point is not a
valid point. Point must be a comma separated
coordinate in r
equested_or_default_SRS projection."
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"Point requested_point is not a valid
point. Point must be a comma separated
coordinate
in requested_or_default_SRS
projection."</message>
</error>
Error Type: Request has an invalid vehicle – ITN based
Error Message: Vehicle requested_vehicle is not a valid vehicle. Valid vehicles are car.
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "Vehicle requested_vehicle is not a
valid vehicle. Valid vehicles are car."
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"Vehicle requested_vehicle is not a
valid vehicle. Valid vehicles are
car."</message>
</error>
Error Type: Request has an invalid vehicle – DPN based
Error Message: Vehicle requested_vehicle is not a valid vehicle. Valid vehicles are foot.
Example JSON:
Example XML:
{
"error": {
"statuscode": "400",
"message": "Vehicle requested_vehicle is not a
valid vehicle. Valid vehicles are foot."
}
}
<?xml version="1.0"?>
<error>
<statuscode>400</statuscode>
<message>"Vehicle requested_vehicle is not a
valid vehicle. Valid vehicles are
foot."</message>
</error>
Chapter 3
Service Requests
Route Request Parameters
The GetTile parameter follows the OGC WMTS request structure specification for mandatory and optional
parameters :
point (coordinate)
Specify multiple points for which the route should be calculated. The order is important. Specify at least two
points.
Use: mandatory
locale (text)
The locale of the result. E.g. pt_PT for Portuguese or de for German. See
https://docs.google.com/spreadsheets/d/10HKSFmxGVEIO92loVQetVmjXT0qpf3EA2jxuQSSYTdU for
supported list. Note this has been crowdsourced.
Default: “en”
Use: optional
instructions (text)
If instructions should be calculated and returned.
Default: “true”
Valid values: true, false
Use: optional
vehicle (text)
The vehicle for which the route should be calculated.
Default: “car”
Valid values: car, foot , bike
Use: mandatory
weighting (text)
Which kind of route calculation is required.
Default: “fastest”
Valid values: fatest, shortest
Use: optional
algorithm (text)
The algorithm to calculate the route.
Default: “dijkstrabi”
Valid values: dijkstrabi, dijkstra, astar, astarbi
Use: optional
points_encoded (text)
If false , a GeoJson array in point is returned. If true, the resulting route will be encoded leading to big
bandwidth reduction. A special handling for the decoding of this string on the client-side will be required.
Open source code can be found here for Java and JavaScript.
Default: “true”
Valid values: true, false
Use: optional
debug (text)
If true, the output will be formatted.
Default: “false”
Valid values: true, false
Use: optional
pretty (text)
If true, output will include carriage returns and spacing.
Default: “false”
Valid values: true, false
Use: optional
calc_points (text)
If the points for the route should be calculated at all. Sometimes only the distance and time is necessary.
Default: “true”
Valid values: true, false
Use: optional
type (text)
Specifies the resulting format of the route. For json the content type will be application/json. For jsonp, the
content type will be application/javascript. For gpx, the content type will be application/xml.
Default: “json”
Valid values: json, jsonp, gpx
Use: optional
avoidances (text)
Specify the list of hazards separated by a comma that need to be avoided while calculating the route.
Default: n/a
Valid values: aroad, boulders, cliff, inlandwater, marsh, quarryorpit, scree, rock, mud,
sand, shingle
Use: optional
srs (text)
Specify the input srs for your point list. It will also specify the output srs unless the output_srs parameter is
not set. Only JSON format will be transformed on output as gpx is specified to be in WGS84.
Default: “bng”
Valid values: bng, EPSG:27700, WGS:84, EPSG:4326
Use: optional
output_srs (text)
Specify the output srs for your point list. Only JSON format will be transformed on output as gpx ios
specified to be in WGS84.
Default: the srs parameter value
Valid values: bng, EPSG:27700, WGS:84, EPSG:4326
Use: optional
Route Request Response
JSON path/attribute
Description
info.took
How many ms the request took on the server
without accounting for network latency.
paths
An array of possible paths.
paths[0].distance
The overall distance of the route, in meters.
paths[0].time
The overall time of the route, in ms.
paths[0].points
The polyline encoded coordinates of the path.
Order is lat, lon, elevation.
paths[0].points_encoded
Is true if the points are encoded. If not,
paths[0].points contains the geo json of the
path. This consumes more bandwidth
compared to the encoded version.
paths[0].bbox
The bounding box of the route. Format:
minLon, minLat, maxLon, maxLat.
paths[0].instructions
Contains information about the instructions for
the requested route. The last instruction is
always the Finish instruction.
paths[0].instructions[0].text
A description what the user has to do in order to
follow the route. Language depends on the
locale parameter.
paths[0].instructions[0].distance
The distance for the current instruction. In
meters.
paths[0].instructions[0].time
The time for the current instruction. In
milliseconds.
paths[0].instructions[0].interval
An array containing the first and last index
(relative to paths[0].points) of the points for the
current instruction.
paths[0].instructions[0].sign
A number which specifies the sign to show:
TURN_SHARP_LEFT = -3
TURN_LEFT = -2
TURN_SLIGHT_LEFT = -1
CONTINUE_ON_STREET = 0
TURN_SLIGHT_RIGHT = 1
TURN_RIGHT = 2
TURN_SHARP_RIGHT = 3
FINISH = 4
VIA_REACHED = 5
USE_ROUNDABOUT = 6
paths[0].instructions[0].exit_number
Only available for USE_ROUNDABOUT
instructions. The count of exits at which the
route leaves the roundabout.
paths[0].instructions[0].turn_angle
Only available for USE_ROUNDABOUT. The
radian of the route within the roundabout:
0<r<2*Pi for clockwise and -2Pi<r<0 for
clockwise transit. Is null if the direction of
rotation is undefined.
paths[0].instructions[0].annotation_text
Returns a list of hazards on the section of the
route following the instruction. Follows the
same values as for the avoidances part of the
request, and are comma separated.
