The Trip API can return, in addition to the complete route coordinates, a complete route diagram of the requested route. The rotogram consists of a series of textual instructions that detail the route step-by-step.

This feature is currently only available for Synchronous Trip.

To use this feature, simply add the turnByTurn parameter to the request, indicating the language in which you want to receive the instructions.

• turnByTurn – Object where preferences related to the rotogram will be specified:
  • language – String representing the language in which the instructions should be returned, following the convention en, pt_BR, es_ES, es_AR and so on.

Request example

The request below must be sent to the Synchronous Trip endpoint, with the POST method:

• 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":"en"
    }
}

Response example

The information regarding the rotogram will be returned in the turnByTurn object array, where each object represents an instruction, as detailed below:

• turnByTurn – Array of objects, where each object represents a specific route instruction with the following information:
  • text – String with the instruction itself. The language must match what was informed in the parameter language;
  • distance – Integer representing the total distance over which the instruction applies;
  • points – String containing the subsection of the instruction in question. The values ​​should be returned according to the pointsMode informed in the request. (polyline, geohash, array or object);
  • duration – Integer representing the total duration in seconds of the segment to which the instruction applies;
  • type – Enum that specifies which signal should be displayed. Possible values ​​are: (For future compatibility, it is important that the application is also able to handle signals from unknown instructions):
    • “LEFT_U_TURN” – Left U-turn;
    • “KEEP_LEFT” – Keep left;
    • “LEAVE_ROUNDABOUT” – Leave roundabout;
    • “TURN_SHARP_LEFT” – Sharp left turn;
    • “TURN_LEFT” – Turn left;
    • “TURN_SLIGHT_LEFT” – Slight left turn;
    • “CONTINUE_ON_STREET” – Continue on street;
    • “TURN_SLIGHT_RIGHT” – Slight right turn;
    • “TURN_RIGHT” – Turn right;
    • “TURN_SHARP_RIGHT” – Sharp right turn;
    • “LAST_POINT” – Final instruction before last point;
    • “VIA_POINT” – Instruction before a waypoint;;
    • “ROUNDABOUT” – Instruction before entering a roundabout;;
    • “KEEP_RIGHT” – Keep right;
    • “RIGHT_U_TURN” – Right U-turn.
  • exitNumber – Integer, returned only when type is equal to "ROUNDABOUT". Represents which exit the route should take from the roundabout. For example: 3 means exit at the third exit.

The full response to this example can be seen below:

{
    "id": "66f16a1a66cb3034cc5b4f0e",
    "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 onto Rodovia Fernão Dias",
                    "duration": 247433
                },
                {
                    "distance": 1082.322,
                    "type": "CONTINUE_ON_STREET",
                    "points": "fwlnCvsd{GdCO`Ns@vCMhLm@bEOnFHNBjAHtEn@",
                    "text": "Continue onto Avenida Educador Paulo Freire and drive toward Penha",
                    "duration": 69998
                },
                {
                    "distance": 24.271,
                    "type": "TURN_RIGHT",
                    "points": "vsnnCnqd{GNl@",
                    "text": "Turn right",
                    "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": "Turn left toward SP-010, BR-381",
                    "duration": 213110
                },
                {
                    "distance": 0.0,
                    "type": "LAST_POINT",
                    "points": "hqrnCdqc{G",
                    "text": "Arrive at destination",
                    "duration": 0
                }
            ]
        }
    ],
    "source": "MAPLINK",
    "createdAt": 1727097370629,
    "expiryIn": 1727702170629
}