Along Route Search

The Along Route Search endpoint allows you to perform a fuzzy search for POIs along a specified route.

• This search is constrained by specifying a detour time-limiting measure.
• To send the route points you will use a POST request whose body will contain the route parameter in JSON format.
• The minimum number of route points is 2.

It is possible that the original route will be altered, and some of its points may be skipped.

• If the route that passes through the found point is faster than the original one, the detour time value is negative.
• POST requests require the Content-Type header to be set to "application/json".

Example POST body (JSON)

{
  "route": {
    "points": [
      {
        "lat": 37.7524152343544,
        "lon":-122.43576049804686
      },
      {
        "lat": 37.70660472542312,
        "lon":-122.43301391601562
      },
      {
        "lat": 37.712059855877314,
        "lon":-122.36434936523438
      },
      {
        "lat": 37.75350561243041,
        "lon":-122.37396240234374
      }
    ]
  }
}

You can easily run this and other endpoints.

1. Go to the TomTom API Explorer page.
2. Click an endpoint.
   1. Click Try it out.
   2. Enter/select all required parameter values and any optional parameter values.
   3. At the bottom of the form, click Execute.
3. Review the Response.

HTTPS Method: POST

URL format

For ease of viewing and identification:

• Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
• See the following Request parameters section with the Required and Optional parameters tables for these values.

https://<baseURL>/search/<versionNumber>/searchAlongRoute/<query>.<ext>?key=<Your_API_Key>[&limit=<limit>][&categorySet=<categorySet>][&brandSet=<brandSet>][&connectorSet=<connectorSet>][&view=<view>][&detourOffset=<detourOffset>][&sortBy=<sortBy>][&openingHours=<openingHours>][&spreadingMode=<spreadingMode>][&timeZone=<timeZone>][&mapcodes=<mapcodes>]

curl command format

curl -XPOST -H "Content-type: application/json" -d '{
  "route": {
    "points": [
      {
        "lat": 37.7524152343544,
        "lon":-122.43576049804686
      },
      {
        "lat": 37.70660472542312,
        "lon":-122.43301391601562
      },
      {
        "lat": 37.712059855877314,
        "lon":-122.36434936523438
      },
      {
        "lat": 37.75350561243041,
        "lon":-122.37396240234374
      }
    ]
  }
}' 'https://<baseURL>/search/<versionNumber>/searchAlongRoute/<query>.<ext>?key=<Your_API_Key>[&limit=<limit>][&categorySet=<categorySet>][&brandSet=<brandSet>][&connectorSet=<connectorSet>][&view=<view>][&detourOffset=<detourOffset>][&sortBy=<sortBy>][&openingHours=<openingHours>][&spreadingMode=<spreadingMode>][&timeZone=<timeZone>][&mapcodes=<mapcodes>]'

Request parameters

The following table describes the parameters that can be used in a Request.

• Required parameters must be used or the call will fail.
• Optional parameters, which are highlighted with [square brackets], may be used.
• If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
• The order of request parameters is not important.

Response body

For illustrative purposes the example below is neatly indented and includes all possible Response fields.

• Actual Responses are more compact and the fields present will vary based on the result type and the data available.
• See the following Response fields section for more information.

When requesting JSON output, the Response has the following structure:

{
  "summary": {
    "query": "pizza",
    "queryType": "NON_NEAR",
    "queryTime": 137,
    "numResults": 1,
    "offset": 0,
    "totalResults": 1,
    "fuzzyLevel": 1
  },
  "results": []
}

Each element of the results array is in the following format:

{
  "type": "POI",
  "id": "US/POI/p0/9033556",
  "score": 4.999,
  "dist": 32.32909635789851,
  "info": "search:ta:840061001865142-US",
  "poi": {
    "name": "Upper Crust Pizza & Pasta",
    "phone": "+(1)-(831)-4762333",
    "url": "www.uppercrustsc.com/",
    "brands": [
      {
        "name": "Upper Crust"
      }
    ],
    "categorySet": [
      {
        "id": 7315015
      }
    ],
    "categories": [
      "pizza",
      "restaurant"
    ],
    "openingHours": {
      "mode": "NEXT_SEVEN_DAYS",
      "timeRanges": [
        {
          "startTime": {
            "date": "2019-02-05",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-05",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-06",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-06",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-07",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-07",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-08",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-08",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-09",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-09",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-10",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-10",
            "hour": 12,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-10",
            "hour": 14,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-10",
            "hour": 21,
            "minute": 0
          }
        }
      ]
    },
    "classifications": [
      {
        "code": "RESTAURANT",
        "names": [
          {
            "nameLocale": "en-US",
            "name": "pizza"
          },
          {
            "nameLocale": "en-US",
            "name": "restaurant"
          }
        ]
      }
    ],
    "timeZone": {
      "ianaId": "Europe/Andorra"
    }
  },
  "address": {
    "streetNumber": "2501",
    "streetName": "Soquel Dr",
    "municipalitySubdivision": "Santa Cruz, Live Oak",
    "municipality": "Santa Cruz, Live Oak",
    "countrySecondarySubdivision": "Santa Cruz",
    "countryTertiarySubdivision": "Santa Cruz",
    "countrySubdivision": "CA",
    "postalCode": "95065",
    "extendedPostalCode": "950652023",
    "countryCode": "US",
    "country": "United States Of America",
    "countryCodeISO3": "USA",
    "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065",
    "countrySubdivisionName": "California",
    "localName": "Santa Cruz"
  },
  "position": {
    "lat": 36.98844,
    "lon": -121.97483
  },
  "mapcodes":[
    {
      "type":"Local",
      "fullMapcode":"US-CA FS.WRH3",
      "territory":"US-CA",
      "code":"FS.WRH3"
    },
    {
      "type":"International",
      "fullMapcode":"S4ZW4.990V"
    },
    {
      "type":"Alternative",
      "fullMapcode":"US-CA 4349.S8W",
      "territory":"US-CA",
      "code":"4349.S8W"
    },
    {
      "type":"Alternative",
      "fullMapcode":"US-CA JJCH.H9DF",
      "territory":"US-CA",
      "code":"JJCH.H9DF"
    },
    {
      "type":"Alternative",
      "fullMapcode":"USA JJCH.H9DF",
      "territory":"USA",
      "code":"JJCH.H9DF"
    }
  ],
  "viewport": {
    "topLeftPoint": {
      "lat": 36.98934,
      "lon": -121.97596
    },
    "btmRightPoint": {
      "lat": 36.98754,
      "lon": -121.9737
    }
  },
  "entryPoints": [
    {
      "type": "main",
      "position": {
        "lat": 36.98817,
        "lon": -121.97487
      }
    }
  ],
  "detourTime": 113,
  "detourDistance": 211,
  "detourOffset": 156,
  "dataSources": {
    "chargingAvailability": {
      "id": "442009000132285"
    },
    "geometry": {
      "id": "00004e4c-3100-3c00-0000-0000685e23c7"
    }
  }
}

▲ Return to top

Response fields

The following table describes all of the fields that can appear in a Response. Fields are listed by the Response section they belong to and in the order that they appear in the Response.

▲ Return to top

HTTP Response codes

▲ Return to top

Response headers

The following table contains Response headers sent back from an API server.

▲ Return to top

Error Response

The error Response content type depends on the ext parameter.

Error Response example (JSON)

{
  "errorText":"Error parsing 'language': Language tag 'en-ES' not supported",
  "detailedError":{
    "code":"BadRequest",
    "message":"Error parsing 'language': Language tag 'en-ES' not supported",
    "target":"language"
    },
  "httpStatusCode":"400"
}

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errorText>Error parsing 'language': Language tag 'en-ES' not supported</errorText>
  <detailedError>
    <code>BadRequest</code>
    <message>Error parsing 'language': Language tag 'en-ES' not supported</message>
    <target>language</target>
  </detailedError>
  <httpStatusCode>400</httpStatusCode>
</response>

▲ Return to top

Error Response fields