In the following example, we have a route between the cities of Taubaté and Barra Mansa, where in addition to the best route we also want to check all the checkpoints and scales along the way.

To do this, we’re going to use the Trip API, plus the POIs API parameters. At points we define the stopping points and their coordinates. In the example there are only two points, the origin and destination.

The place parameter is the object that will contain all the POIs API parameters. We’ll define it as follows:

• categories – We will define the category FISCALIZACAO ;
• subCategories – We will define the subcategories BALANCAS e POSTO_FISCAL ;
• bufferRouteInMeters – 10-meter search radius while en route;
• bufferStoppingPointsInMeters – 20-meter search radius at stopping points.

As the checkpoints and scales are part of the service’s native base, there is no need to inform the parameter onlyMyPlaces.

The full request can be seen below:

{
    "points": [
        {
            "latitude": -23.03058114872101,
            "longitude": -45.54850460771741,
            "siteId": "Taubaté"
        },
        {
            "latitude": -22.535562949361026,
            "longitude": -44.19548915630202,
            "siteId": "Barra Mansa"
        }
    ],
    "place": {
        "categories": [
            "FISCALIZACAO"
        ],
        "subCategories": [
            "BALANCAS",
            "POSTO_FISCAL"
        ],
        "bufferRouteInMeters": 10,
        "bufferStoppingPointsInMeters": 20
    }
}

The reply will return all the information about the route. Among them, the most important in the example will be the array of objects called legs. Each object in legs represents a section of the route and will contain the data for that section only.

Inside each object contained in legs an object placeCalculation will be returned containing the following information:

• total – Integer containing the number of establishments found in the search;
• places – Array of objects, where each object represents an establishment. The following information will be returned:
  • id – Unique identifier of the establishment;
  • name – Name of establishment;
  • category – Category to which the establishment belongs;
  • subcategory – Subcategory to which the establishment belongs;
  • address – Object with address details:
    • street – String to enter the address;
    • number – String for the establishment number;
    • district – (Optional) String for the neighborhood;
    • city – String for city;
    • state – String for status;
    • zipcode – String for zip code;
    • point – Array with the coordinates of the establishment:
      • latitude – Latitude coordinate in decimal degrees;
      • longitude – Longitude coordinate in decimal degrees;
  • active – Boolean value indicating whether the establishment is active or not;
  • tags – Tags of the establishment, if any;
  • phones – Contact telephone numbers for the establishment, if available.

The full response can be found below:

{
    "id": "645b9c26bc072f0a972f3224",
    "clientId": "maplink",
    "totalDistance": 169159,
    "totalNominalDuration": 7988,
    "averageSpeed": 64.18,
    "legs": [
        {
            "distance": 169159,
            "nominalDuration": 7988,
            "averageSpeed": 64.18,
            "points": "ddqkCbe_uGo@YaGgJwUa_@iBiCeCgEsCeEWm@mAk@\\S?OI??m@kA??GGGAGBkF~E??",
            "placeCalculation": {
                "total": 2,
                "places": [
                    {
                        "id": "61b0c5960b666c4e05a1492f",
                        "name": "Posto Fiscal Estado do Rio de Janeiro",
                        "category": "FISCALIZACAO",
                        "subCategory": "POSTO_FISCAL",
                        "address": {
                            "street": "Rodovia Presidente Dutra",
                            "number": "KM 323+667",
                            "city": "Itatiaia",
                            "state": "RJ",
                            "point": {
                                "latitude": -22.50462288,
                                "longitude": -44.6116333
                            }
                        },
                        "active": true
                    },
                    {
                        "id": "61b0c57caeddba55769f812e",
                        "name": "Praça de Balança Queluz",
                        "category": "FISCALIZACAO",
                        "subCategory": "BALANCAS",
                        "address": {
                            "street": "Rodovia Presidente Dutra",
                            "number": "KM 000+827",
                            "city": "Queluz",
                            "state": "SP",
                            "point": {
                                "latitude": -22.5179217,
                                "longitude": -44.7067999
                            }
                        },
                        "active": true
                    }
                ]
            }
        }
    ]
}