Response Structure
The following example shows a route between the cities of Casa Branca-SP and Guaxupé-MG, avoiding urban areas, with toll values for a two-axle truck, the gas stations along the route, and the states it crosses.
Request
In the Trip API request, in addition to the points (points) and the calculation mode (calculationMode), we will use the following parameters:
avoidanceTypes– Types of roads or areas to be avoided on the route. We will useCITYto avoid urban areas;avoidanceBehavior– Behavior applied to theavoidanceTypesrestrictions. The possible values areFAIL,RELAXEDandSTRONG. We will useSTRONG;toll– Parameters related to the Toll API. To see all supported parameters, check the list of Toll API parameters:vehicleType– Vehicle type. We will use"TRUCK_WITH_TWO_DOUBLE_AXLES";transponderOperators– Desired automatic payment operators. We will useCONECTCARto obtain this operator’s integration codes.
crossedBorders– Parameters to identify the borders crossed by the route:level– Level of the returned borders. We will useSTATEto obtain the states crossed;reverseGeocode– Defines for which points the address will be returned. We will useSTART_END_LEGSto obtain the addresses of the start and end of the legs.
place– Parameters to search for places along the route. To see all supported parameters, check the list of POIs API parameters:categories– Categories of the places searched. We will usePOSTOS_DE_COMBUSTIVEL;subCategories– Subcategories of the places searched, for examplePOSTO_FISCALandBALANCAS, from theFISCALIZACAOcategory. Optional parameter, not used in this example;bufferRouteInMeters– Maximum distance, in meters, between the place and the route. We will use500;bufferStoppingPointsInMeters– Maximum distance, in meters, between the place and the stopping points. We will use500;onlyMyPlaces– Whentrue, returns only the places registered by the client itself.
{
"points": [
{
"siteId": "Point 1-Casa Branca",
"latitude": -21.780449,
"longitude": -47.079822
},
{
"siteId": "Point 2-Guaxupe",
"latitude": -21.312320,
"longitude": -46.717873
}
],
"calculationMode": "THE_FASTEST",
"avoidanceTypes": [
"CITY"
],
"avoidanceBehavior": "STRONG",
"toll": {
"vehicleType": "TRUCK_WITH_TWO_DOUBLE_AXLES",
"transponderOperators": [
"CONECTCAR"
]
},
"crossedBorders": {
"level": "STATE",
"reverseGeocode": "START_END_LEGS"
},
"place": {
"categories": [
"POSTOS_DE_COMBUSTIVEL"
],
"bufferRouteInMeters": 500,
"bufferStoppingPointsInMeters": 500,
"onlyMyPlaces": true
}
}
Below, the route displayed on the map:
Response
Some response fields are always returned, while others only appear when the corresponding parameter is sent in the request. For example, toll fields are only returned if the toll object is sent.
Fields always returned
id– Unique identifier of the calculated route;clientId– Identifier of the client that made the request;totalDistance– Total distance of the route, in meters;totalNominalDuration– Total nominal duration of the route, in seconds;averageSpeed– Average speed of the route, in km/h;legs– Array of objects where each object represents a leg of the route. Each object contains the following fields, which are always returned:distance– Distance of the leg, in meters;nominalDuration– Nominal duration of the leg, in seconds;averageSpeed– Average speed of the leg, in km/h;points– Geometry of the leg. The format depends on thepointsModeparameter of the request. To learn more, see how to change the return type of the route coordinates.
source– Origin of the map used to calculate the route. It will always be returned asMAPLINK.createdAt– Date and time the route was created, in timestamp format;expiryIn– Date and time the route expires, in timestamp format.
Fields returned only if the toll object is sent
tollCosts– Total toll cost for the entire route;legs[].tollCalculation– Object, returned in each leg, with the toll values and information for that leg:tolls– Array with the values and information of each toll on the leg. Each object returned intollsrepresents a toll and will contain the following information:id– Unique identifier of the toll;type– Toll type. The possible values are:TOLL_BOOTH– Conventional toll booths;MUNICIPAL_TOLL_BOOTH– Similar toTOLL_BOOTH, it only identifies that the toll booth is municipal;TOLL_GANTRY– Corresponds to conventional gantries;ENTRY_GANTRY– Corresponds to entry gantries, used on roads with segment-based billing;EXIT_GANTRY– Corresponds to exit gantries, used on roads with segment-based billing.
name– Name of the toll;address– Address of the toll;city– City of the toll;state– Object containing the state name (name) and its abbreviation (code);country– Country of the toll;concession– Concessionaire responsible for the toll;direction– Direction of the road in which the toll is charged (for example,NORTH,EASTorSOUTHEAST);coordinates– Coordinates (latitude and longitude) of the toll;price– Price per toll;conditions– Array with differentiated toll values according to the billing type. Returned only for tolls that have this type of value:billingsType– Array with the billing types to which the value applies, for exampleTAG;value– Toll value for the informed billing types.
currency– Currency used by the toll. The possible values are:BRL– Brazilian real;ARS– Argentine peso;CLP– Chilean peso;COP– Colombian peso;MXN– Mexican peso.
serviceTypes– Array with codes for integration with automatic payment systems. Currently available only in Brazil. In addition toANTTCODE, the codes of the operators informed intoll.transponderOperatorsare returned (in this example,CONECTCAR);serviceId– Code for the integration;name– Description of the service code.
active– Indicates whether the toll is active (true) or not (false).
legTotalCost– Total toll cost for the leg;vehicleType– Vehicle type considered for the leg. It may vary between legs whentoll.variableAxlesis sent;calculationDate– Date and time considered for the leg, in timestamp format. The base date is the value oftoll.calculationDate(or the request time, if not sent), plus the nominal duration of the previous legs. Therefore, on routes with more than one leg, the value increases with each leg;condition– Returned only if thetoll.conditionparameter is used in the request. Contains whichbillingTypeandperiodwere considered for the leg.
Fields returned only if crossedBorders.level is sent
crossedBorders– Array of objects where each object represents a border crossed by the route, according to the level informed incrossedBorders.level(in this example,STATE), in the order in which they were crossed:state– State abbreviation;city– City name. Returned whenlevelisCITY;country– Country of the border.
Fields returned only if crossedBorders.reverseGeocode is sent
These fields are independent of crossedBorders.level. With START_END, startAddress and endAddress are returned. With START_END_LEGS, legs[].firstPointAddress is also returned.
startAddress– Address of the route’s origin point. The object contains the following information:road– Street;district– Neighborhood;zipCode– Postal code;city– City;state– Object containing the state name (name) and its abbreviation (code);mainLocation– Coordinates (latandlon) of the address found;- When available for the address,
geometry(array oflatandloncoordinates of the road),leftZipCodeandrightZipCode(postal code of each side of the road),leftFirstNumber,leftLastNumber,rightFirstNumberandrightLastNumber(first and last numbering of each side of the road) may also be returned.
endAddress– Address of the route’s destination point, with the same structure as thestartAddressobject;legs[].firstPointAddress– Address of the first point of each leg, with the same structure as thestartAddressobject. Returned only withSTART_END_LEGS.
Fields returned only if the place object is sent
legs[].placeCalculation– Object, returned in each leg, with the places found along the leg according to theplaceparameters:total– Number of places found on the leg;places– Array with the places found. In this example the array is returned empty, since no registered place met the search criteria. When there are results, each object contains:id– Unique identifier of the place;name– Name of the place;documentNumber– Document number of the establishment;category– Category of the place, for examplePOSTOS_DE_COMBUSTIVEL;subCategory– Subcategory of the place;address– Address of the place:street– Street;number– Number;city– City;state– State abbreviation;zipcode– Postal code;point– Coordinates (latitudeandlongitude) of the place.
phones– Array with the phone numbers of the place;clientId– Identifier of the client that registered the place;active– Indicates whether the place is active (true) or not (false).
Fields returned only if the turnByTurn object is sent
When the turnByTurn parameter is used, the route’s turn-by-turn directions are also returned in the response. This parameter was not used in this example. For more information about the returned fields, see the detailed route directions example.
Fields returned only if the freight object is sent
routeFreightCost– Freight cost of the route. It corresponds tofreight.minimumFreightWithCostsplustollCosts. If thetollobject is not sent, the toll value considered is zero;freight– Object with the freight calculation result:source– Regulation used as the basis for the calculation;results– Object with the calculated values, organized in levels: operation type (operationType), number of axles (axis) and cargo type (goodsType). For each combination,value(freight value) andotherCosts(object with the value of each cost informed infreight.otherCosts, indexed by its respectivename) are returned;minimumFreight– Minimum freight value;minimumFreightWithCosts– Minimum freight value plus the other costs informed.
The freight field is not part of this example’s request. Below is an example of how this field is returned when the corresponding object is sent in the request. The routeFreightCost value is illustrative only. To learn more, see the Freight API documentation.
"routeFreightCost": 36970.73,
"freight": {
"source": "PORTARIA Nº 169, DE 18 DE MARÇO DE 2022",
"results": {
"D": {
"4": {
"GRANEL_SOLIDO": {
"value": 36970.73,
"otherCosts": {
"ICMS": 1848.54,
"Lucro": 7394.15,
"TaxaFixa": 500
}
}
}
}
},
"minimumFreight": 36970.73,
"minimumFreightWithCosts": 46713.42
}
Full response
The full response is shown below, generated from this example’s request (with toll, crossedBorders and place):
{
"id": "6aeb78781e5d6641c3a5d586",
"clientId": "maplink",
"totalDistance": 86857,
"totalNominalDuration": 4363,
"averageSpeed": 56.75,
"tollCosts": 16.20,
"legs": [
{
"distance": 86856,
"nominalDuration": 4363,
"averageSpeed": 56.75,
"points": "j_}cCdgj~GmEgEv@eAgEgBSAYQuAuASy@IgA?[PuAh@oA`@s@h@k@rFmFN_@FY}AaAmAi@{@_@cHeEuUqLkIaE_DcBgFgCKOGOWKAICIEGD[COCU?O@MDOFOP[fDaF~BcDDK?O[uACk@?KCKIIKCK?GBEBGL?L@HDH@BUVSLMLsA|BIRGRCVAt@ETIVu@bBeAxAeAnA_A`AmAdAwB~AyA|@gAj@yB|@iA`@mCt@gBZ{BTaF`@aOdAeF\\inAzI{m@nEkQlA}D`@_Db@eBXkCj@_Dv@eDbAqSpHchB`q@wFvBcBh@eBb@eB\\kBViBNkBHkBBkBAkBKiBOiBYcB_@{A_@aA[mAc@_Aa@yAw@{A}@sAcAwCeCoGiFaDqCoK_JoAiAs}@mv@eGkFyE{DoV}SacAa{@uAmAiFmEqAaAgAq@y@g@gB_AwB_AoBq@qAa@}@UcCc@y@MmGs@oOyAkFi@gJy@mJ}@iFc@eQeBuGm@mCYuFg@mJu@aK_AcFk@aD[YEwD]_F]e_BeOqEa@gKeAoHo@wMuAiDYmBSsLcAy|BgTkHq@aWcCyGm@iZuCqIw@eHs@uFg@q_@sD}NsAoMoAuJ{@}AO_bAeJuC[o_@mD}s@{GcJy@mk@mFqYsCoBMkDc@eBKq@Gy@KwFaAmDq@}EsAaCw@ePwGeGiCiQmH_KcEuEoBsDaBaC_AsP_HeEiByF{B_Bm@wCoA_JqDgCkAqEoBoMcFuB_AyAo@qAe@mEkB}@c@uCkAsDuAqA[gAOw@Eq@Cs@?q@Du@Hc@HqA\\k@Ry@^_K~FsD|B}DzBmG`EwFfDcDrBiEdCwEtCmJvFaC|AsC~AwDbC{PhKoJtFcCzAm@\\[Ls@Rc@Ho@Ja@De@Dw@As@E]E}G_AyDa@uDg@qSkCgPwBeH{@kBSwG}@uEm@_C]eEi@w@Og@Ko@Sq@UgBq@qBaAc@WoCiBs@i@o@k@cPkOaEqDyAmAsDcDyb@k`@yDqDcBwAgIsHuEaE}IcIeDuCkAqAcHsGeFsEcCsBmIyHcCuBqAmAiAcAiByA{@u@qHwFaBmAoM}JiLsImO}Kgp@{f@mHqFcEaDeFqDeF_EuFeEuAqA{CkDeAuAgAaBmAyBkAmCq@qBiCiJgBqHi@mB_@cAe@qA_CqEq@cAgA}A}BuCm@o@e@c@yBeBm@a@iAaAW]MYSg@O[g@e@YOyBaBuCmBoCoBsAu@]W[OiAQi@KYKoAo@eJmGsA{@_CiBqBcBq@q@yAgB_B}BqFyGmDqEsCuD{ByCgH_J}ImLwBaCcA{@oBqAsBgAgDaAwAUqC]{BM}@Ey\\eBqDOoKk@qOu@yAKqAOaDo@yBg@cBk@u@YeEgBeD_BeF_Ce@WaJgEsSoJoI}DiBu@kBm@oBg@qBa@uBWoBUsBKoy@}@yo@g@}BGaf@g@qCIiE[aC_@eCg@}CaAkBs@sEmBaOwGeAg@cFyBcD{AoH_Di@OyQ_IiAm@w@k@a@c@g@i@QYm@oA]eAQu@K{@Gw@?]BcBNgB`BcNzAmNxAqM`AiIZcCn@sG~AmNfBgOXoCnB}PfBmPTwA`@oBXkA`@oAb@kA\\}@`AyBj@iAhBuC`D}EfEqFvDoF~HoKfA}A`BiCdBiD`J{TxD_Kv@oBd@{AVcARiALeAFkA@aAAgACiAKmAS{AqA{HeAqFSoAKoAEeACgABmAJeANgAr@sCl@gBxEaLf@uATw@Rs@Nu@Hu@Du@B{@?w@G{@Iu@a@gB_@cAoAoCgGiMWg@eIwP_@eAYw@WeAK{@IiACy@WuMa@_IGw@Io@Ou@Uo@Wi@_@k@e@i@k@e@g@[s@WwBi@qOeDw@Qg@Qi@Ui@[_@]UWo@}@Ue@g@mAyCwHm@wA[o@e@{@o@aA_@m@{B{C]_@wAmAgAeAcB}Ay@y@u@qAo@aB{AoEwDoKk@oBg@aC]sBiFka@}AoMo@wDQq@Uo@[q@g@u@k@y@}EeGa@o@Ym@M]Om@MiACe@?kAJmAFc@Ns@\\oA|AwG\\gBB_@Bk@?{@Ci@Ie@Kg@So@Yw@uAuC_@s@Wo@i@yAMi@Mm@O_AW_CKuAsAuUsAqXU{DMkBQeDMgBS{BOuAOgAUeAU_A[mAm@kBiAwCiEsJe@kAOi@_@_BOs@Ms@Io@OiBEu@Aq@AaA@w@FcBNeBNsAXaBxAuFnBcHX_Ap@iCp@aCh@yBhFsRhFwRXq@Ti@Te@t@qBPk@h@uBPg@ZiBVgBJi@BUbCgJpDiNrFkSvAwFJq@Jy@PaCBy@@uBCgAGaAIcAMgAe@}Ba@}A[}@yB_FwNcZg@uA_@sAWsA]gCMgBCmB?iABcAvBgQXeCRoBd@uF|F_v@LgC@wAAyAEqAMmBSkBWkBWuAe@qB[gA_@cAGSu@eBo@oAyHeNkAuCq@_Be@aAw@sACg@BUHMJGPCzD]vHm@dIq@dCUfHi@`@C^EVEz@Yl@GfDOh@?x@@fBFd@Dd@HbCz@XDV@xC@fEGfACd@Cf@Ij@Op@WrAu@pIeFf@Op@QDE@G@ICGtDmF~DqF`B_CzBuCNOHENCPEtC[SmB_@sEH}DCuACe@IkAM}@Eg@IYm@}ADEDEBE?G?GAGCEEEEAGAE?G@EBI?u@]s@w@o@w@qBmCgDcFc@u@q@cFOyAe@qDIs@oAu@gBy@?EEGA?EEe@m@w@w@dBoDOI",
"firstPointAddress": {
"road": "RUA SÃO PAULO",
"district": "Centro",
"zipCode": "13700049",
"city": "CASA BRANCA",
"state": {
"code": "SP",
"name": "SÃO PAULO"
},
"mainLocation": {
"lat": -21.780329800344585,
"lon": -47.07950794999991
}
},
"placeCalculation": {
"total": 0,
"places": []
},
"tollCalculation": {
"tolls": [
{
"id": "177",
"type": "TOLL_BOOTH",
"name": "Pedágio - Mococa",
"address": "SP-340 - Rodovia Professor Boanerges Nogueira de Lima - Km 254+7",
"city": "Casa Branca",
"state": {
"name": "São Paulo",
"code": "SP"
},
"country": "Brasil",
"currency": "BRL",
"concession": "Rota Mogiana",
"direction": "NORTH",
"coordinates": {
"latitude": -21.6408129,
"longitude": -47.0477845
},
"serviceTypes": [
{
"serviceId": "35353402546900103",
"name": "ANTTCODE"
},
{
"serviceId": "101140011",
"name": "Conectcar"
}
],
"price": 16.20,
"active": true
}
],
"legTotalCost": 16.20,
"vehicleType": "TRUCK_WITH_TWO_DOUBLE_AXLES",
"calculationDate": 1793816696871
},
"arrivalSiteId": "Point 2-Guaxupe",
"departureSiteId": "Point 1-Casa Branca"
}
],
"crossedBorders": [
{
"state": "SP",
"country": "BRASIL"
},
{
"state": "MG",
"country": "BRASIL"
}
],
"startAddress": {
"road": "RUA SÃO PAULO",
"district": "Centro",
"zipCode": "13700049",
"city": "CASA BRANCA",
"state": {
"code": "SP",
"name": "SÃO PAULO"
},
"mainLocation": {
"lat": -21.780329800344585,
"lon": -47.07950794999991
}
},
"endAddress": {
"road": "RUA JOSÉ OLEGÁRIO DA SILVEIRA",
"district": "PARQUE DO LAGO",
"zipCode": "37831024",
"city": "GUAXUPÉ",
"state": {
"code": "MG",
"name": "MINAS GERAIS"
},
"mainLocation": {
"lat": -21.312143750217658,
"lon": -46.7183685
}
},
"source": "MAPLINK",
"createdAt": 1793816696967,
"expiryIn": 1794421496626
}
