Estrutura de resposta
No exemplo abaixo temos uma rota entre as cidades de Casa Branca-SP e Guaxupé-MG, evitando áreas urbanas, com os valores de pedágio para um caminhão de dois eixos, os postos de combustível ao longo da rota e os estados percorridos.
Requisição
Na requisição para a Trip API, além dos pontos (points) e do modo de cálculo (calculationMode), usaremos os seguintes parâmetros:
avoidanceTypes– Tipos de via ou área que devem ser evitadas na rota. InformaremosCITYpara evitar áreas urbanas;avoidanceBehavior– Comportamento aplicado às restrições deavoidanceTypes. Os valores possíveis sãoFAIL,RELAXEDeSTRONG. UsaremosSTRONG;toll– Parâmetros referentes à Toll API. Para saber todos os parâmetros suportados, consultar a lista de parâmetros da Toll API:vehicleType– Tipo de veículo. Usaremos"TRUCK_WITH_TWO_DOUBLE_AXLES";transponderOperators– Operadoras de pagamento automático desejadas. InformaremosCONECTCARpara obter os códigos de integração dessa operadora.
crossedBorders– Parâmetros para identificar as divisas cruzadas pela rota:level– Nível das divisas retornadas. UsaremosSTATEpara obter os estados percorridos;reverseGeocode– Define para quais pontos será retornado o endereço. UsaremosSTART_END_LEGSpara obter os endereços do início e do fim dos trechos.
place– Parâmetros para buscar locais ao longo da rota. Para saber todos os parâmetros suportados, consultar a lista de parâmetros da POIs API:categories– Categorias dos locais buscados. UsaremosPOSTOS_DE_COMBUSTIVEL;subCategories– Subcategorias dos locais buscados, por exemploPOSTO_FISCALeBALANCAS, da categoriaFISCALIZACAO. Parâmetro opcional, não utilizado neste exemplo;bufferRouteInMeters– Distância máxima, em metros, entre o local e a rota. Usaremos500;bufferStoppingPointsInMeters– Distância máxima, em metros, entre o local e os pontos de parada. Usaremos500;onlyMyPlaces– Quandotrue, retorna apenas os locais cadastrados pelo próprio cliente.
{
"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
}
}
Abaixo a rota visualizada no mapa:
Resposta
Alguns campos da resposta são retornados sempre, enquanto outros só aparecem quando o parâmetro correspondente é informado na requisição. Por exemplo, os campos de pedágio só são retornados se o objeto toll for informado.
Campos sempre retornados
id– Identificador único da rota calculada;clientId– Identificador do cliente que realizou a requisição;totalDistance– Distância total da rota, em metros;totalNominalDuration– Duração total nominal da rota, em segundos;averageSpeed– Velocidade média da rota, em km/h;legs– Array de objetos onde cada objeto representa um trecho da rota. Cada objeto contém os seguintes campos, sempre retornados:distance– Distância do trecho, em metros;nominalDuration– Duração nominal do trecho, em segundos;averageSpeed– Velocidade média do trecho, em km/h;points– Geometria do trecho. O formato depende do parâmetropointsModeda requisição. Para saber mais, consulte como alterar o tipo de retorno das coordenadas da rota.
source– Origem do mapa utilizado no cálculo da rota. Sempre retornará comoMAPLINK.createdAt– Data e hora de criação da rota, em formato timestamp;expiryIn– Data e hora de expiração da rota, em formato timestamp.
Campos retornados somente se o objeto toll for informado
tollCosts– Valor total dos pedágios em toda rota;legs[].tollCalculation– Objeto, retornado em cada trecho, com os valores e informações de pedágio do trecho correspondente:tolls– Array com os valores e informações de cada pedágio no trecho. Cada objeto retornado emtollsrepresenta um pedágio e irá conter as seguintes informações:id– Identificador único do pedágio;type– Tipo do pedágio. Os valores possíveis são:TOLL_BOOTH– Cabines de pedágios convencionais;MUNICIPAL_TOLL_BOOTH– Similar aoTOLL_BOOTH, servindo apenas para identificar que a praça de pedágio é municipal;TOLL_GANTRY– Corresponde aos pórticos convencionais;ENTRY_GANTRY– Corresponde aos pórticos de entrada, utilizados em rodovias com cobrança por segmento;EXIT_GANTRY– Corresponde aos pórticos de saída, utilizados em rodovias com cobrança por segmento.
name– Nome do pedágio;address– Endereço do pedágio;city– Cidade do pedágio;state– Objeto contendo o nome do estado (name) e sua sigla (code);country– País do pedágio;concession– Concessionária responsável pelo pedágio;direction– Sentido da via em que o pedágio é cobrado (por exemplo,NORTH,EASTouSOUTHEAST);coordinates– Coordenadas (latitude e longitude) do pedágio;price– Valor por pedágio;conditions– Array com valores diferenciados do pedágio conforme o tipo de cobrança. Retornado apenas nos pedágios que possuem esse tipo de valor:billingsType– Array com os tipos de cobrança aos quais o valor se aplica, por exemploTAG;value– Valor do pedágio para os tipos de cobrança informados.
currency– Tipo da moeda utilizada pelo pedágio. Os valores possíveis são:BRL– Real brasileiro;ARS– Peso argentino;CLP– Peso chileno;COP– Peso colombiano;MXN– Peso mexicano.
serviceTypes– Array com códigos para integração com sistemas de pagamento automático. Atualmente disponível apenas no Brasil. Além doANTTCODE, são retornados os códigos das operadoras informadas emtoll.transponderOperators(neste exemplo,CONECTCAR);serviceId– Código para a integração;name– Descrição do código do serviço.
active– Indica se o pedágio está ativo (true) ou não (false).
legTotalCost– Valor total de pedágios para o trecho;vehicleType– Tipo de veículo considerado para o trecho. Pode variar entre os trechos quandotoll.variableAxlesé informado;calculationDate– Data e hora considerados para o trecho, em formato timestamp. A data base é o valor detoll.calculationDate(ou o momento da requisição, se não informado), acrescida da duração nominal dos trechos anteriores. Por isso, em rotas com mais de um trecho, o valor aumenta a cada trecho;condition– Retornado apenas se o parâmetrotoll.conditionfor usado na requisição. Contém qualbillingTypeeperiodforam considerados para o trecho.
Campos retornados somente se crossedBorders.level for informado
crossedBorders– Array de objetos onde cada objeto representa uma divisa cruzada pela rota, de acordo com o nível informado emcrossedBorders.level(neste exemplo,STATE), na ordem em que foram percorridas:state– Sigla do estado;city– Nome da cidade. Retornado quandoleveléCITY;country– País da divisa.
Campos retornados somente se crossedBorders.reverseGeocode for informado
Esses campos são independentes de crossedBorders.level. Com START_END, são retornados startAddress e endAddress. Com START_END_LEGS, é retornado também legs[].firstPointAddress.
startAddress– Endereço do ponto de origem da rota. O objeto contém as seguintes informações:road– Logradouro;district– Bairro;zipCode– CEP;city– Cidade;state– Objeto contendo o nome do estado (name) e sua sigla (code);mainLocation– Coordenadas (latelon) do endereço encontrado;- Quando disponíveis para o endereço, também podem ser retornados
geometry(array de coordenadaslatelondo logradouro),leftZipCodeerightZipCode(CEP de cada lado da via),leftFirstNumber,leftLastNumber,rightFirstNumbererightLastNumber(numeração inicial e final de cada lado da via).
endAddress– Endereço do ponto de destino da rota, com a mesma estrutura do objetostartAddress;legs[].firstPointAddress– Endereço do primeiro ponto de cada trecho, com a mesma estrutura do objetostartAddress. Retornado somente comSTART_END_LEGS.
Campos retornados somente se o objeto place for informado
legs[].placeCalculation– Objeto, retornado em cada trecho, com os locais encontrados ao longo do trecho de acordo com os parâmetros deplace:total– Quantidade de locais encontrados no trecho;places– Array com os locais encontrados. Neste exemplo o array retorna vazio, pois nenhum local cadastrado atendeu aos critérios da busca. Quando há resultados, cada objeto contém:id– Identificador único do local;name– Nome do local;documentNumber– Número do documento do estabelecimento;category– Categoria do local, por exemploPOSTOS_DE_COMBUSTIVEL;subCategory– Subcategoria do local;address– Endereço do local:street– Logradouro;number– Número;city– Cidade;state– Sigla do estado;zipcode– CEP;point– Coordenadas (latitudeelongitude) do local.
phones– Array com os telefones do local;clientId– Identificador do cliente que cadastrou o local;active– Indica se o local está ativo (true) ou não (false).
Campos retornados somente se o objeto turnByTurn for informado
Ao utilizar o parâmetro turnByTurn, o rotograma da rota também é retornado na resposta. Esse parâmetro não foi utilizado neste exemplo. Para mais informações sobre os campos retornados, consulte o exemplo de rotograma detalhado da rota.
Campos retornados somente se o objeto freight for informado
routeFreightCost– Custo de frete da rota. Corresponde afreight.minimumFreightWithCostssomado atollCosts. Se o objetotollnão for informado, o valor de pedágio considerado é zero;freight– Objeto com o resultado do cálculo de frete:source– Norma utilizada como base do cálculo;results– Objeto com os valores calculados, organizado em níveis: tipo de operação (operationType), quantidade de eixos (axis) e tipo de carga (goodsType). Para cada combinação são retornadosvalue(valor do frete) eotherCosts(objeto com o valor de cada custo informado emfreight.otherCosts, indexado pelo respectivoname);minimumFreight– Valor mínimo do frete;minimumFreightWithCosts– Valor mínimo do frete somado aos outros custos informados.
O campo freight não faz parte da requisição deste exemplo. Abaixo, um exemplo de como esse campo é retornado quando o objeto correspondente é informado na requisição. O valor de routeFreightCost é apenas ilustrativo. Para saber mais, consultar a documentação da Freight API.
"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
}
Resposta completa
A resposta completa encontra-se abaixo, gerada a partir da requisição deste exemplo (com toll, crossedBorders e 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
}
