If you are on this page, we assume that:
You already have an access key;

Have knowledge on how to perform HTTP requests (for the RESTfull endpoints).

Know how to authenticate on our services.

"We work hard to let our APIs as easy and self-explanatory as possible. Our goal is that you do not even need to go beyond the examples below in order to understand the operation and consume our services. The examples below show some of the features of the Route API. The parameters and options are detailed over the page."

 

Simple route from 'São Paulo' to 'Rio de Janeiro'

Shortest route with selective API results (request only distance and duration information)

Request only toll information for a route avoiding traffic from SP to RJ

Calculate a route and two alternative routes from SP to RJ and return only the geometry (as GeoJSON)

So after these examples, you should be a little bit more familiar with the Route API. All the subsections bellow describes in detail what each request or response element is and its options.
Here is a summary of the functionalities behind each item:

  • One can inform up to 100 waypoints in a route, define a specific radius for each one (maximum distance to find a road around the informed coordinate) and even ask for waypoint order optimization (with a limit of 15 waypoints to optimize). Check the Waypoints section.
  • Routes can be calculated with a variety of types, such as driving, walking, etc. See the travel element options
  • Fine grained ajustments can be made to the route, such as avoid traffic, positive or negative prioritization to roads with tolls, bridges, etc. Check the Cost Adjustment options.
  • Estimated arrival or departure time can be obtained as well, check the Schedule options
  • Toll information or even road services, such as "Sem Parar" are also available through the Route API. See Tolls section for more details
  • Selective results let you customize the result of the API, for example, just to request for a simple field with the total distance of a route or even the complete route with legs, steps, geometry, etc. See the Result Specification for more.


Tip

The more specific the result element is, more efficient is the consumption of the service with shorter processing time and smaller responses. Always try to be the most specific you can. Check the session result specification to see the available options

Waypoints define the location that the route will start, end and pass by. You must provide at least two waypoints (which will be used as origin and destination). Otherwise noted in your contract, the maximum number of waypoints a route request can have is 100 waypoints. The 'index' attribute of the waypoints determins the position it will be in the route. It also allows multiple parameter configuration to be made to a single waypoint, such as set a specific ID for each waypoint or even a different radius. For example:

waypoint.0.latlng=-26.44,-45.84
(sets the location of the waypoint with index zero)

waypoint.0.id=Origin of the route
(sets the ID of the waypoint with index zero, this can be any string and may be used to identify this waypoint in the route result)

Attribute Name Type Range Default Description
waypoint.{index}.id string Waypoint identification. This may be used to identify this waypoint in the response
waypoint.{index}.latlng float,float Lat: -90 to 90, Lng: -180 to 180 Latitude and longitude of the stop point. Use dot "." as the decimal separator and comma "," as the separator of latitude and longitude. Ex: -25.000,-46.000
waypoint.{index}.radius int 200 Maximum search radius (in meter) to find a road around the informed coordinate. A high value for this field may substantially increase the processing time of the route calculation.
waypoint.optimizeorder boolean true/false false Optimize the order of the waypoints in order to produce shorter or faster routes. Note: optimization through the road network is done to routes with at most 10 waypoints. For routes with more waypoints, linear distance is used to optimize the waypoints order.

Route with multiple waypoints

The traffic parameter is used to set whether the route to be calculated will avoid traffic or if the result time for the calculated route will be considering the traffic.
Notice that the default time returned by the Route API is calculated using the average speed of the streets.

Attribute Name Type Range Default Description
traffic.avoid boolean true | false Avoid traffic
traffic.considerinresulttime boolean true | false Use the speed of the roads with current traffic to calculate the route duration

Calculate a route avoiding traffic

The travel parameter is used to set information such as the type of vehicle used and options for route calculation

Attribute Name Type Range Default Description
travel.by alphanumeric driving | walking driving Define whether the route will be calculated for a vehicle or a pedestrian
travel.mode alphanumeric fastest | shortest fastest Defines the mode (fastest or shortest) of the route. When using the default 'fastest' mode, the route tends to be through highways or large avenues with higher average speed while using the 'shortest' mode may result in routes which passes through small streets
travel.vehicle list of alphanumeric separated by comma Car
Motorcycle
CarWithThreeSimpleAxles
CarWithFourSimpleAxles
BusWithTwoDoubleAxles
BusWithThreeDoubleAxles
TruckWithTwoDoubleAxles
TruckWithThreeDoubleAxles
TruckWithFourDoubleAxles
TruckWithFiveDoubleAxles
TruckWithSixDoubleAxles
TruckWithSevenDoubleAxles
TruckWithEightDoubleAxles
TruckWithNineDoubleAxles
car/none The vehicle used in route. In the current version of the API, this parameter does not affect the route calculation. When travel.by is driving, the vehicle defaults to car, otherwise, the default is none. A list of values may be passed to retrieve toll information for more than one vehicle in the same request (toll prices for motorcycle, car and truck for exeample)

Shortest route example

Cost adjustment is an advanced purpose parameter which let you define specific weights, positive or negative, to some type of roads when calculating a route. A good example is to specify a positive value for roads with bridges so the routing algorithm will try to avoid them. Positive values means that the route will tend to avoid it, and negative values the opposite, try to pass through it. You can also set value as "avoid" and that will cause the route to absolutelly avoid the specified type. Note that the use of "avoid" may result in impossíble routes, so use it carefully.

Attribute Name Type Range Default Description
costadjustment.bridge alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 Cost adjustments for bridges
costadjustment.tunnel alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 cost adjustments for tunnel
costadjustment.ferryboat alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 cost adjustments for ferry boat
costadjustment.tollroad alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 cost adjustments for toll road
costadjustment.limitedaccess alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 Cost adjustment for routes with limited access
costadjustment.unpavedroad alphanumeric or range "avoid" or integer value between -100(pass through) to 100(avoid) 0 Cost adjustment for unpaved road

Route avoiding bridges

Request only the tolls for a route prioritizing (attempting to pass through) toll roads

The avoid parameter can be used as an alias for all the cost adjustments above and for some other types as well, a circle (coordinate and radius) for example. Be careful when using this parameter since it may let the destination of the route unreachable.

Attribute Name Type Range Default Description
avoid.circle.center float,float Lat: -90 to 90, Lng: -180 to 180 Circle center coordinated to be avoided (required avoid.circle.radius)
avoid.circle.radius int Circle radius to be avoided (required avoid.circle.center).
avoid.bridge boolean true | false false Avoid passing for bridge
avoid.tunnel boolean true | false false Avoid passing for tunnel
avoid.ferryboat boolean true | false false Avoid passing for ferry boat
avoid.tollroad boolean true | false false Avoid passing for toll road
avoid.limitedaccess boolean true | false false Avoid passing for routes with limited access
avoid.unpavedroad boolean true | false false Avoid passing for unpaved road

Avoid passing near a risk area using the circle parameter

The schedule parameter is used to inform the departure or arrival time. If one wants to know the arrival time of a route, the departure time is required in the request and vice-versa.
One can retrieve, for example, the arrival time informing the "summary.arrival-time" element in the result parameter.

Attribute Name Type Range Default Description
schedule.by alphanumeric departure | arrival Planning for departure / arrival
schedule.time datetime yyyy-mm-dd hh:mm:ss Date and time to be planned. The format must be exactly as described, year with four digit, dash month with two dash day with two digit, etc.

Retrieve the arrival time of a route, informing the departure time

POIs parameter is used for search and retrieve points of interest along the route given a POI category (multiple categories may be informed, separated by comma). You can also integrate your POIs (or stablishments) in our router and retrieve these informations along the routes, however, the POI API must be consumed as well to do this integration. Please contact us if you are interested.

Tolls and POIs are examples of advanced features and require aditional permissions. Make sure your license includes access to these informations.
Attribute Name Type Range Default Description
poi.category int list IDs of POIs categories (to return POI on the route is also required to inform result=summary.pois or steps.pois)
poi.radius int Radius to be used in the search for POIs along the route (in meters)

POIs in Route

The alternatives routes parameter is used for set maximum number of alternatives routes to be calculated. Notice that the informed number is the maximum number of alternative routes and it may happen that no alternative route is found, so please consider that the actual number of alternatives is between zero and the informed maximum number. Alternative routes do not support routes with intermediate waypoints, just origin and destination.

Attribute Name Type Range Default Description
maxalternatives int 1-3 0 Maximum number of alternative routes to be returned

Route with two alternatives

The geometry parameter is used to define the extent of the geometry to be returned or the geometry simplification. To specify the extent you must provide the minimum and maximum coordinates through the extent.southwest and extent.northeast parameters. Setting this parameters, only the strech of the route within it will be returned. Optionally you can specify the simplification of the route, which is given in degrees and means that, if two or more coordinates have the distance smaller than the specified value of the simplification, only one of them will be kept.

The geometry is returned as GeoJSON
Attribute Name Type Range Default Description
route-geometry.extent.southwest float,float Lat: -90 to 90, Lng: -180 to 180 Coordinates minimum for the extent of route geometry return
route-geometry.extent.northeast float,float Lat: -90 to 90, Lng: -180 to 180 Coordinates maximum for the extent of route geometry return
geometry.simplify float 0 value in degrees to be used in the simplification. Ex: if a value of "0.005" is passed, then if two or more coordinates have the distance smaller than 0.005, then only one coordinate of them will be kept.

Get the geometry of a route, setting the simplification and extent of the geometry

The language parameter is used to define the reading on the response data, like step.instruction.

Attribute Name Type Enum Default Description
language enum Portuguese, English English Define the language used to get the response

Define the language to get step.instructions in portuguese

You can select the specific element or group of elements you want in the response, to use it, check the groups and fields bellow and pass in the result query string element. Multiple values are accepted, just separate them with a comma.

Name Description
summary This is a group of result elements. It will cause the API to return the following fields: distance, duration, origin and destination address and mappedLocation.
summary.duration Total duration of route in seconds
summary.distance Total distance of route in meters
summary.departure-time Departure time (requires schedule with the arrival time in the request)
summary.arrival-time Arrival time (requires schedule with the departure time in the request)
summary.origin.location Origin coordinates (the coordinate informed in the request)
summary.destination.location Destination coordinates (the coordinate informed in the request)
summary.origin.address Origin address of route (this is the address of the mapped-location)
summary.destination.address Destination address (this is the address of the mapped-location)
summary.waypoints.address Address of the route waypoints (this is the address of the mapped-location)
summary.waypoints.location Coordinates of the route waypoints (this is the address of the mapped-location)
summary.pois POIs in route (requires poi.category)
summary.tolls Tolls in route
summary.waypoints.mapped-location Waypoints of the route (may refer the maximum distance informed parameter radius of waypoint)
route-geometry Get geometry of the route - GeoJSON MultiLineString
poi-route-geometry Get geometry of the POI in route - GeoJSON Point (required result=summary.pois or sumamry.tolls or steps.pois or steps.toll)
Legs
legs.duration Duration of leg in seconds
legs.distance Distance of route in meters
legs.origin.mapped-location Origin coordinates of leg (may refer the maximum distance informed parameter radius of waypoint)
legs.destination.mapped-location Destination coordinates of leg (may refer the maximum distance informed parameter radius of waypoint)
legs.origin-address Origin address of leg (relative to mapped-location)
legs.destination-address Destination address of leg (relative to mapped-location)
Steps
steps.instruction Instruction step (turn) - Instructions Available
steps.distance Distance step in meters
steps.duration Duration step in seconds
steps.angle Angle step
steps.location Coordinates step
steps.address Address step
step.geometry Geometry step
steps.pois POIs in step (required poi.category)
steps.toll Tolls in steps
steps.road-types Road type of the step - Road Types Available
Instructions Available
English Portuguese
Proceed Siga em Frente
Make a Left Hand Loop Pegue o Acesso à Esquerda
Make a U-Turn Faça o Retorno à Esquerda
Turn Hard Left Curva Acentuada à Esquerda
Turn Left Vire à Esquerda
Bear Left Vire Levemente à Esquerda
Continue Continue
Bear Right Vire Levemente à Direta
Turn Right Vire à Direita
Turn Hard Right Curva Acentuada à Direita
Make a Right U-Turn Faça o Retorno à Direita
Make a Right Hand Loop Pegue o Acesso à Direita
Merge Siga
Road Types Available
Abbreviation Description
P Paved
CP Precarious Conditions
ED Doubling Road
EP Paving Road
PD Double Road
T Unpaved Road
BA Ferry Boat

Errors are returned through HTTP Status Codes. There's also an unique identifier returned for errors other than input errors, which becomes handy if you want to open a ticket with our support. The codes returned by the service are:

  • 400 Bad Request - There is something wrong with its request, verify that the URL is correctly. Usually a more specific description of the error in the response body.
  • 401 Authentication failed - Check that informed the parameter applicationCode and signature was generated and concatenated to the request correctly.
  • 500 Internal Server Error - If you do not understand the message and status, please contact support informing request data.