The INRIX Routing Service provides integrated traffic-influenced routing services, such as fastest route based on traffic, lists of directional maneuvers and faster alternative routes based on traffic conditions. This information is based on current as well as predictive traffic.
Overview
Many existing route calculation systems predict travel time using road classes or speed limits as the basis for route calculations. Some even use real-time traffic data, but estimated travel times along the route, for any given route segment, are limited to current conditions at the time of calculation. As such, the calculated travel time for a given route is based on free-flow traffic conditions, or limited to the current traffic conditions.
By contrast, the INRIX routing service provides routing data based on the predicted or actual conditions at the time the vehicle reaches a given route segment. It is unique in that the route calculation uses predictive and real-time traffic information from a number of different sources as the basis of route calculations, including incident data, along the entire route. The routing engine employs a time-based “look-ahead” algorithm to not only identify what traffic is at the time of route calculation, but how it will evolve during the course of a route. This results in a seamless blending of real-time, historical, predictive, road closure, and incident data to produce the most informed route decision possible. Such comprehensive route data enables a routing application to offer the user better alternatives based on time and the complexity of the route.
Routing APIs
The following APIs are available to get routing information:
FindRoute - Takes a set of waypoints and calculates one or more routes from the first waypoint to the last waypoint, passing through other optional waypoints in turn.
GetRoute - Takes a route previously defined by FindRoute and returns current data about that route.
GetRouteTravelTimes - Takes a route previously defined by FindRoute and returns a list of travel times based on current or future traffic conditions.
GetSegmentsInRoute - Retrieves segments for a routeId returned by FindRoute
Finding Routes and Refreshing Route Data
To find a route, call FindRoute with origin and destination points, as well as other parameters. This will return a Trip, which contains one or more routes that have a unique ID, as well as data for each of the routes, including travel time, maneuvers, and incidents along the route. Each route represents a specific, static way to go from the origin to destination.
Once a route has been found, you may decide at some point in the future to get up-to-date data on that route. To do this, call GetRoute.
Note that calling FindRoute at a different time may return different routes. For example, you can call FindRoute at one point in time and request only one route, and it will return the optimal path between the origin and destination. Now, imagine an incident has happened such that the optimal route now takes significantly longer than before. Calling FindRoute may now return a different route. However, if you call GetRoute using the ID from the original FindRoute call, it will always return data for that route, even if that route is no longer the optimal route.
If you need travel times for the present time or near future, then call GetRouteTravelTimes after calling FindRoute. GetRouteTravelTimes is useful for determining when to best to leave to take a route, or it can be used to create charts of how travel times are expected to vary over time.
Note that GetRoute and GetRouteTravelTimes are less computationally intensive than FindRoute. Also, if the origin, destination, or other waypoints change, then you need to call FindRoute again.
Trips and Routes
FindRoute returns a Trip element, which contains a collection of Route elements. The Trip element is defined by its waypoints, whereas the Route element contains the actual path taken through those waypoints.
Expiration of Routes and Trips
When FindRoute is called, a trip with routes is created, each with unique IDs. These trips and routes may be re-used for a period of time (a number of hours) through GetRoute and GetRouteTravelTimes. However, eventually, you will need to call FindRoute again.
Routing Options and Returned Data
FindRoute allows you to specify:
Up to 10 waypoints, through either longitude and latitude, or saved locations, as well as a text description for those waypoints
Departure or arrival time
The maximum number of alternate routes, up to two alternates
Whether to use or ignore traffic data
Whether to return the fastest or shortest route
Whether to list all maneuvers or just the major ones
Whether to use English or metric units
Geometric tolerance for the route coordinates
What data to return
FindRoute and GetRoute can return:
A list of the waypoints
A route (for FindRoute, up to three routes), containing:
Travel times for uncongested conditions and predicted conditions
Route quality
Whether the route has closures
Average speed
Total distance
Textual summary
Bounding box that encloses the route
Points along the route
Incidents along the route
You may specify which of these types of data you want returned by FindRoute and GetRoute through the RouteOutputFields parameter.
Description: Finds a new route.
/?Action=FindRoute
GETGenerates a new route based on waypoints
Parameters
= required
Name
Located In
Type
Description
action
Path
String
Use findRoute
Token
Path
String
A valid authorization token returned in response to a GetSecurityToken request.
WP_Heading
Path
Integer
The heading of the starting waypoint expressed as degrees. Heading is used to determine best route. It is important for non-divided (non-freeway/motorway/expressway) roads. Value can range from 0 to 359. 90 degrees indicates a due east heading.
WP_1
Path
Point
A valid starting waypoint for the route. This first point can also take a position-speed-heading (PHS) record. For instance, the first waypoint and heading (233 in this example) can be specified as follows - WP_1=47.613458,-122.188086,233
WP_2
Path
Point
The next waypoint.
WP_[3-10]
Path
Point
Any additional waypoints. You can specify up to 8 additional points.
WP_[n]description
Path
Point
A textual description that can be attached to each associated waypoint.
WP_[n]ID
Path
Integer
A location ID from a previous call to CreateLocation.
DepartureTime
Path
Datetime
The time of departure. Defaults to “now” if not specified. DepartureTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ; for example 2009-04-04T13:42:41Z.
ArrivalTime
Path
Datetime
The time of arrival. Ignored if DepartureTime is specified. ArrivalTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ; for example 2009-04-04T13:42:41Z.
MaxAlternates
Path
Integer
Determines the number of alternate routes calculated. By default, only one route is returned but you can request up to 2 alternates. If all the routes have closures and cannot be driven, the third route returned is replaced with a fastest traffic-aware route that is navigable. In other words, no matter what the conditions are on the primary (and maybe secondary) routes, the API always returns at least one navigable route.
Value
Description
0 (default)
Return one route.
1
Return up to two routes.
2
Return up to three routes.
UseTraffic
Path
Boolean
If UseTraffic is True, the current traffic flow is used in calculating the route. The default is True (calculate route based on current traffic conditions). Ignored if RouteType is 1.
RouteType
Path
Integer
A value of 0 returns the fastest route; 1 returns the shortest route. The default is 0. If 1 is specified, UseTraffic is ignored.
Units
Path
Integer
Use 0 for English units, 1 for metric. The default is 0.
RouteOutputFields
Path
String
The route elements to output in the response XML. Multiple fields can be specified in a comma-delimited list. You can use either the entire field name, or just the first letter.
Value
Description
D,S,W,B,I,U (default)
Returns the Descriptions, Summary, Waypoints, BoundingBox, and Incidents fields.
All
Returns all fields.
D – Descriptions
The textual descriptions of the trip and route.
S – Summary
The route summary contains a high level summary of the major roads on the route.
W – Waypoints
The waypoints used to calculate the route.
B – BoundingBox
The geographical bounding box of the entire route.
P – Points
A list of points along the route, returned in latitude/longitude pairs.
I – Incidents
A list of any incidents occurring on the route.
U – RouteSpeedBucket
A list of colors along the route based on INRIX Speedbuckets to allow a route to be colored according to congestion
IncidentOutputFields
Path
String
The incident fields to output. Multiple fields can be specified in a comma-delimited list. The default is the primary incident element attributes, short and long description, TMCs and Parameterized description. This parameter is only used if Incidents are set to be returned in the RouteOutputFields.
Value
Description
All
This option returns all of the options available including new fields added in the future. Incident head, tail and last detour point are now available by specifying this option.
ID
The unique identifier of an incident.
Version
The version number of the incident report, incremented each time an incident report is updated.
Type
The type of the incident (Crashes and Hazards; Events; Construction; and Congestion Alerts, also known as Flow incidents).
Severity
The severity of the incident. This value can be in the range of 0-4, with 4 indicating the highest severity.
EventCode
The event code of the incident. These are standard Alert-C event codes.
LatLong
The latitude and longitude of the incident.
Impacting
Whether the incident impacts traffic flow. This field is set to “yes” if the appearance of the incident changes the traffic flow below a certain percentage from that which is normally expected for the given segment of road at that time, given the current conditions.
StartTime
The starting time of the incident.
EndTime
The ending time of the incident.
DelayImpact
Provide the delay in minutes versus typical conditions and versus free flow conditions.
Area
The points in a polygon that describes an incident that is returned, in GML format. For more information about GML format, see http://www.opengeospatial.org/standards/gml.
RDS
The Radio Data System data. See the RDS element for more information.
ShortDescription
Short textual description of the incident including language code.
FullDescription
Longer textual description of the incident including language code.
GeometryTolerance
Path
Integer
Reduces the number of latitude/longitude points returned when describing a route as requested by the Points value of the RouteOutputFields parameter. This value should be greater than or equal to 0 and is specified in yards for English units and meters for metric units. The default is 0, which means exact (no inaccuracy is tolerated), and results in the entire Points set being returned when points are requested in the output field. Higher values will reduce the number of points by eliminating points whose distance from each other is less than the specified tolerance. Based on the level of zoom used to draw the map, you can save bandwidth by reducing the size of the return payload. For example, if the map is zoomed to a 300-mile level, you may want to return fewer data points by specifying a larger value for GeometryTolerance. If the value for GeometryTolerance is larger than the length of the route, only the origin and destination points are returned.
IsAmbiguousOrigin
Path
Boolean
Set to true to indicate that the starting waypoint latitude and longitude are not exact. In particular, if the origin is a major highway that has separate roads going in opposite directions, specify true so that Inrix is free to choose the road which is going in the most optimal direction. Default is false.
Criteria
Path
String (* see comment with asterisk in the notes)
Any avoidance criteria which should be considered in calculating the Route. Possible criteria are avoid Ferries, TollRoads etc. Specify the first letter of the criteria or multiples in a comma separated list. For instance, to avoid highways and toll roads specify Criteria=H,T.The following criteria and abbreviations are supported.
Value
Description
NoRestrictions (default)
Report all road types.
AvoidTollRoads
T
AvoidHighways
H
AvoidFerries
F
AvoidVignette
V
PreferExpress
E
PreferCarPool
C
Format
Path
String
The format of the response in either XML or JSON. Default is XML.
SpeedBucketID
Query
Integer
A speed bucket is a range of speeds or percentages that is used to categorize Segment data. All speed buckets are identified by a unique number called a speedbucketID. Default is to use the INRIX default speed bucket ID (id=1) which is described in the CreateSpeedBucket api . Custom speed buckets can be defined by using the CreateSpeedBucket API.
The root element of a collection of routes that share the same origin and destination.
Property
Type
Description
tripId
String
The id of the trip returned.
wayPoints
Array
Points that the first route of the trip is required to take; all routes use first and last waypoint.
Property
Type
Description
id
String
The id of the waypoint.
geometry
Geojson point
Longitude and lattitude of that waypoint
routes
Array
Route information, including travel times and maneuvers.
Property
Type
Description
uncongestedTravelTimeMinutes
Unsignedbyte
The travel time, given no traffic congestion.
routeQuality
Unsignedbyte
Quality of the route, typically scaled from 0 (most congested) to 3 (least congested).
id
String
The route ID.
hasClosures
Boolean
Whether or not there are road closures along the route. If true, then travel times will not be returned.
hasRestrictions
Boolean
Whether or not there are restrictions along the route, such as times when traffic is not allowed to flow in a particular direction. If true, then travel times will not be returned.
travelTimeMinutes
Unsignedbyte
The currently calculated travel time. If there are road closures or restrictions along the route, this attribute will not be present, and you should call FindRoute to get a new route.
abnormalityMinutes
Unsignedbyte
The difference in minutes between the travel time for the returned route and the normal travel time expected for the time and day. See Notes for more information. If there are road closures along the route, this attribute will not be present.
averageSpeed
Unsignedbyte
The average speed on the route. If there are road closures along the route, this value will be 0.
trafficConsidered
Boolean
Whether or not traffic is used in calulating the route.
statusId
Unsignedbyte
The status ID for the request
totalDistance
Decimal
The length of the route, in miles for units=0 and kilometer for units=1.
summary
Array
Information about the roads used in the route.
Property
Type
Description
text
String
Information about the roads used in the route.
roads
Array
List of roads on the route
description
Array
A textual description of the route.
incidents
Array
Incident info (if any) on the route. See Response description on Incidents page
boundingBox
Array
Coordinates of the rectangular region of the route.
Property
Type
Description
corner1
Geojson point
Longitude and latitude in Geojson format
corner2
Geojson point
Longitude and latitude in Geojson format
points
Geojson linestrong
The points in the route in Geojson linestring format.
/?Action=GetRoute
GETTakes a previously defined route and returns route current data.
Parameters
= required
Name
Located In
Type
Description
action
Path
String
use getRoute
token
Path
String
A valid authorization token returned in response to a GetSecurityToken request.
routeId
Path
String
A valid route ID from which to return traffic and routing information.
DepartureTime
Path
Datetime
The time of arrival. Ignored if ArrivalTime is specified. DepartureTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ; for example 2009-04-04T13:42:41Z.
ArrivalTime
Path
Datetime
The time of arrival. Ignored if DepartureTime is specified. ArrivalTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ.
UseTraffic
Path
Boolean
If UseTraffic is True, the current traffic flow is used in calculating the route. The default is True (calculate route based on current traffic conditions). Ignored if RouteType is 1.
RouteType
Path
Integer
A value of 0 returns the fastest route; 1 returns the shortest route. The default is 0. If 1 is specified, UseTraffic is ignored.
CollapseManeuvers
Path
Boolean
A value of false does not collapse the list of maneuvers; true collapses minor maneuvers into one. The default is true.
Units
Path
Integer
Use 0 for English units, 1 for metric. The default is 0.
RouteOutputFields
Path
String
The route elements to output in the response XML. Multiple fields can be specified in a comma-delimited list. You can use either the entire field name, or just the first letter.
Value
Description
D,S,W,B,I,U (default)
Returns the Descriptions, Summary, Waypoints, BoundingBox, and Incidents fields.
All
Returns all fields.
D – Descriptions
The textual descriptions of the trip and route.
S – Summary
The route summary contains a high level summary of the major roads on the route.
W – Waypoints
The waypoints used to calculate the route.
B – BoundingBox
The geographical bounding box of the entire route.
P – Points
A list of points along the route, returned in latitude/longitude pairs.
I – Incidents
A list of any incidents occurring on the route.
U – RouteSpeedBucket
A list of colors along the route based on INRIX Speedbuckets to allow a route to be colored according to congestion
IncidentOutputFields
Path
String
The incident fields to output. Multiple fields can be specified in a comma-delimited list. The default is the primary incident element attributes, short and long description, TMCs and Parameterized description. This parameter is only used if Incidents are set to be returned in the RouteOutputFields.
Value
Description
All
This option returns all of the options available including new fields added in the future. Incident head, tail and last detour point are now available by specifying this option.
ID
The unique identifier of an incident.
Version
The version number of the incident report, incremented each time an incident report is updated.
Type
The type of the incident (Crashes and Hazards; Events; Construction; and Congestion Alerts, also known as Flow incidents)
Severity
The severity of the incident. This value can be in the range of 0-4, with 4 indicating the highest severity.
EventCode
The event code of the incident. These are standard Alert-C event codes.
LatLong
The latitude and longitude of the incident.
Impacting
Whether the incident impacts traffic flow. This field is set to “yes” if the appearance of the incident changes the traffic flow below a certain percentage from that which is normally expected for the given segment of road at that time, given the current conditions.
StartTime
The starting time of the incident.
EndTime
The ending time of the incident.
DelayImpact
Provide the delay in minutes versus typical conditions and versus free flow conditions.
Area
The points in a polygon that describes an incident that is returned, in GML format. For more information about GML format, see http://www.opengeospatial.org/standards/gml.
RDS
The Radio Data System data. See the RDS element for more information.
ShortDescription
Short textual description of the incident including language code.
FullDescription
Longer textual description of the incident including language code.
GeometryTolerance
Path
Integer
Reduces the number of latitude/longitude points returned when describing a route as requested by the Points value of the RouteOutputFields parameter. This value should be greater than or equal to 0 and is specified in yards for English units and meters for metric units. The default is 0, which means exact (no inaccuracy is tolerated), and results in the entire Points set being returned when points are requested in the output field. Higher values will reduce the number of points by eliminating points whose distance from each other is less than the specified tolerance. Based on the level of zoom used to draw the map, you can save bandwidth by reducing the size of the return payload. For example, if the map is zoomed to a 300-mile level, you may want to return fewer data points by specifying a larger value for GeometryTolerance. If the value for GeometryTolerance is larger than the length of the route, only the origin and destination points are returned.
Format
Path
String
The format of the response in either XML or JSON. Default is XML.
The root element of a collection of routes that share the same origin and destination.
Property
Type
Description
tripId
String
The id of the trip returned.
wayPoints
Array
Points that the first route of the trip is required to take; all routes use first and last waypoint.
Property
Type
Description
id
String
The id of the waypoint.
geometry
Geojson point
Longitude and lattitude of that waypoint
routes
Array
Route information, including travel times and maneuvers.
Property
Type
Description
uncongestedTravelTimeMinutes
Unsignedbyte
The travel time, given no traffic congestion.
routeQuality
Unsignedbyte
Quality of the route, typically scaled from 0 (most congested) to 3 (least congested).
id
String
The route ID.
hasClosures
Boolean
Whether or not there are road closures along the route. If true, then travel times will not be returned.
hasRestrictions
Boolean
Whether or not there are restrictions along the route, such as times when traffic is not allowed to flow in a particular direction. If true, then travel times will not be returned.
travelTimeMinutes
Unsignedbyte
The currently calculated travel time. If there are road closures or restrictions along the route, this attribute will not be present, and you should call FindRoute to get a new route.
abnormalityMinutes
Unsignedbyte
The difference in minutes between the travel time for the returned route and the normal travel time expected for the time and day. See Notes for more information. If there are road closures along the route, this attribute will not be present.
averageSpeed
Unsignedbyte
The average speed on the route. If there are road closures along the route, this value will be 0.
trafficConsidered
Boolean
Whether or not traffic is used in calulating the route.
statusId
Unsignedbyte
The status ID for the request
totalDistance
Decimal
The length of the route, in miles for units=0 and kilometer for units=1.
summary
Array
Information about the roads used in the route.
Property
Type
Description
text
String
Information about the roads used in the route.
roads
Array
List of roads on the route
description
Array
A textual description of the route.
incidents
Array
Incident info (if any) on the route. See Response description on Incidents page
boundingBox
Array
Coordinates of the rectangular region of the route.
Property
Type
Description
corner1
Geojson point
Longitude and latitude in Geojson format
corner2
Geojson point
Longitude and latitude in Geojson format
points
Geojson linestrong
The points in the route in Geojson linestring format.
/?Action=GetRouteTravelTimes
GETReturns travel times based on current or future traffic conditions for a previously defined route.
Parameters
= required
Name
Located In
Type
Description
action
Path
String
use getRouteTravelTimes
token
Path
String
A valid authorization token returned in response to a GetSecurityToken request.
routeId
Path
String
A valid route ID from which to return traffic and routing information.
DepartureTime
Path
Datetime
The time of departure. Ignored if ArrivalTime is specified. DepartureTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ; for example 2009-04-04T13:42:41Z.
ArrivalTime
Path
Datetime
The time of arrival. Ignored if DepartureTime is specified. ArrivalTime must be within nine months from the time of the API call, and must occur in the future. The date format must be in the form YYYY-MM-DDTHH:MM:SSZ.
TravelTimeCount
Path
Integer
The number of travel times you want to be returned for this route. Must be a value greater than 0, but less than or equal to 96.
TravelTimeInterval
Path
Integer
The time span between the travel times specified in TravelTimeCount. Must be a value greater than 0, but less than or equal to 1440 minutes.