A Trip API permite que, além das coordenadas completas da rota, támbem seja retornado um rotograma completo da rota solicitada. O rotograma consiste em uma série de instruções textuais que detalham passo-a-passo a rota.

Hoje esse recurso está disponivel apenas para a Trip Síncrona.

Para utilizar esse recurso basta adicionar o parâmetro turnByTurn na requisição, indicando em qual idioma deseja receber as instruções.

• turnByTurn – Objeto onde serão especificadas as preferências relacionadas ao rotograma:
  • language – String que representa o idioma em que as instruções devem ser retornadas, seguindo a convenção pt_BR, es_ES, es_AR, en e assim por diante.

Exemplo de requisição

A requisição abaixo deve ser enviada para o endpoint da Trip Síncrona, com o método POST:

• https://api.maplink.global/trip/v2/calculations – POST

{
     "points": [
        {
            "siteId": "Point 1-Vila-Galvao",
            "latitude": -23.454521350080835,
            "longitude": -46.57105028629302
        },
        {
            "siteId": "Point 2-Aricanduva",
            "latitude": -23.52933420411184,
            "longitude": -46.55395656824112
        }
    ],
    "turnByTurn":{
        "language":"pt_BR"
    }
}

Exemplo de resposta

As informações referentes ao rotograma serão retornadas no array de objetos turnByTurn, onde cada objeto representa uma instrução, conforme detalhada abaixo:

• turnByTurn – Array de objetos, onde cada objeto representa uma instrução específica da rota com as seguintes informações:
  • text – String com a instrução em si. O idioma deve corresponder ao que foi informado no parâmetro language;
  • distance – Número inteiro que representa a distância total em que a instrução se aplica;
  • points – String contendo o subtrecho da instrução em questão. Os valores deverão ser retornados de acordo com o pointsMode informado na requisição (polyline, geohash, array ou object);
  • duration – Número inteiro que representa a duração total em segundos do trecho em que a instrução se aplica;
  • type – Enum que especifica qual sinal deve ser exibido. Os valores possíveis são: (Para compatibilidade futura, é importante que a aplicação seja capaz de manipular também sinais de instruções desconhecidos):
    • “LEFT_U_TURN” – Retorno à esquerda;
    • “KEEP_LEFT” – Manter à esquerda;
    • “LEAVE_ROUNDABOUT” – Sair da rotatória;
    • “TURN_SHARP_LEFT” – Curva acentuada à esquerda;
    • “TURN_LEFT” – Virar à esquerda;
    • “TURN_SLIGHT_LEFT” – Curva leve à esquerda;
    • “CONTINUE_ON_STREET” – Continuar na rua;
    • “TURN_SLIGHT_RIGHT” – Curva leve à direita;
    • “TURN_RIGHT” – Virar à direita;
    • “TURN_SHARP_RIGHT” – Curva acentuada à direita;
    • “LAST_POINT” – Instrução final antes do último ponto;
    • “VIA_POINT” – Instrução antes de um ponto de passagem;
    • “ROUNDABOUT” – Instrução antes de entrar em uma rotatória;
    • “KEEP_RIGHT” – Manter à direita;
    • “RIGHT_U_TURN” – Retorno à direita.
  • exitNumber – Número inteiro, retornado apenas quando type for igual a "ROUNDABOUT". Representa qual a saída a rota deve sair da rotatória. Por exemplo: 3 significa sair na terceira saída.

A resposta completa desse exemplo pode ser conferida abaixo:

{
    "id": "66eb20d4e6de0e4106ffa591",
    "clientId": "maplink",
    "totalDistance": 9161,
    "totalNominalDuration": 532,
    "averageSpeed": 55.80,
    "legs": [
        {
            "distance": 9160,
            "nominalDuration": 532,
            "averageSpeed": 55.8,
            "points": "x}cnCx{f{G`Df@lGd@xFTzl@ZlBDzBCr@G`AQd@MpAk@l@_@l@c@b@e@|@mAZm@xKgVtEoK`BgD|@wAjB_ClAsAxBwBnBkAt@]`Cs@fC]fFk@dBIb\\u@xK]fYcAjHIxFAbUd@jIZnBAfLo@dCO`Ns@vCMhLm@bEOnFHNBjAHtEn@Nl@JChDLz@J`AXrH|AtC|@fG~BtAp@fA\\h@JpBX~AFhA@xAE~AStAWnAc@xAs@l[cRxFuCt@c@vDsCdAeAp@e@nO{I",
            "turnByTurn": [
                {
                    "distance": 5567.24,
                    "type": "CONTINUE_ON_STREET",
                    "points": "x}cnCx{f{G`Df@lGd@xFTzl@ZlBDzBCr@G`AQd@MpAk@l@_@l@c@b@e@|@mAZm@xKgVtEoK`BgD|@wAjB_ClAsAxBwBnBkAt@]`Cs@fC]fFk@dBIb\\u@xK]fYcAjHIxFAbUd@jIZnBAfLo@",
                    "text": "Continue na Rodovia Fernão Dias",
                    "duration": 247433
                },
                {
                    "distance": 1082.322,
                    "type": "CONTINUE_ON_STREET",
                    "points": "fwlnCvsd{GdCO`Ns@vCMhLm@bEOnFHNBjAHtEn@",
                    "text": "Continue na Avenida Educador Paulo Freire e siga em direção a Penha",
                    "duration": 69998
                },
                {
                    "distance": 24.271,
                    "type": "TURN_RIGHT",
                    "points": "vsnnCnqd{GNl@",
                    "text": "Vire à direita",
                    "duration": 1471
                },
                {
                    "distance": 2486.666,
                    "type": "TURN_LEFT",
                    "points": "ftnnC|rd{GJChDLz@J`AXrH|AtC|@fG~BtAp@fA\\h@JpBX~AFhA@xAE~AStAWnAc@xAs@l[cRxFuCt@c@vDsCdAeAp@e@nO{I",
                    "text": "Vire à esquerda em direção à SP-010, BR-381",
                    "duration": 213110
                },
                {
                    "distance": 0.0,
                    "type": "LAST_POINT",
                    "points": "hqrnCdqc{G",
                    "text": "Destino alcançado!",
                    "duration": 0
                }
            ]
        }
    ],
    "source": "MAPLINK",
    "createdAt": 1726685396934,
    "expiryIn": 1727290196934
}