Sorry, you need to enable JavaScript to visit this website.

Corridor Filter


This endpoint comes handy when a list of POIs are already available and they need to be filtered along a route. Corridor Filter can return the list of POIs that fall along the route, results will contain information regarding the distance/time from the route. You may use a Criteria object to specify the type of distance/time filter you wish to apply. A max of 25 POIs can be passed into the filter.

To send the criteria and poiList you can use a POST/GET request with the JSON as a string value for the criteria and poiList parameters, POST is recommended for large datasets e.g.: 

GET

?criteria={"measure":"distance", "measureValue":1000}&poiList=[{"type":"POI","id":1717181,"score":4.998,"info":"search:decarta:ta:840061003666675-US","poi":{"name":"ATM%20LEGENDS%20INC","categories":["cash%20dispenser"]},"address":{"streetNumber":"55","streetName":"S%202nd%20St","municipality":"San%20Jose","countrySecondarySubdivision":"Santa%20Clara","countryTertiarySubdivision":"San%20Jose","countrySubdivision":"ca","postalCode":"95113","countryCode":"US"},"position":{"lat":"37.33557","lon":"-121.88876"}},{"type":"POI","id":5109601,"score":4.997,"info":"search:decarta:ta:840061003641611-US","poi":{"name":"Tri%20Counties%20Bank","categories":["cash%20dispenser"]},"address":{"streetNumber":"85","streetName":"S%202nd%20St","municipality":"San%20Jose","countrySecondarySubdivision":"Santa%20Clara","countryTertiarySubdivision":"San%20Jose","countrySubdivision":"ca","postalCode":"95113","countryCode":"US"},"position":{"lat":"37.33515","lon":"-121.88845"}}]

POST

{"poiList":[{"type":"POI","id":1717181,"score":4.998,"info":"search:decarta:ta:840061003666675-US","poi":{"name":"ATM%20LEGENDS%20INC","categories":["cash%20dispenser"]},"address":{"streetNumber":"55","streetName":"S%202nd%20St","municipality":"San%20Jose","countrySecondarySubdivision":"Santa%20Clara","countryTertiarySubdivision":"San%20Jose","countrySubdivision":"ca","postalCode":"95113","countryCode":"US"},"position":{"lat":"37.33557","lon":"-121.88876"}},{"type":"POI","id":5109601,"score":4.997,"info":"search:decarta:ta:840061003641611-US","poi":{"name":"Tri%20Counties%20Bank","categories":["cash%20dispenser"]},"address":{"streetNumber":"85","streetName":"S%202nd%20St","municipality":"San%20Jose","countrySecondarySubdivision":"Santa%20Clara","countryTertiarySubdivision":"San%20Jose","countrySubdivision":"ca","postalCode":"95113","countryCode":"US"},"position":{"lat":"37.33515","lon":"-121.88845"}}],"criteria":{"measure":"distance","measureValue":10000}}

Request

Format

GET https://<baseURL>/search/<versionNumber>/corridorFilter/<routeID>.<ext>?key=<apiKey>&poiList=<poiList>[&criteria=<criteria>]

Parameters

The table below 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.

Parameter Description Req'd? Type / Values Default value Max value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 2. Yes 2
query Query string. Must be properly URL encoded. Yes String
routeID Hexadecimal RouteID. The search results will be computed along this route corridor. Yes String
ext Valid response formats are JSON, JSONP, JS or XML. Yes String
poiList List of pois for the corridor filter, as in the example above. 
The only required parameter to be passed in for the POI is the position, everything else is optional and will be echoed back when passed in.
Yes JSON Object
apiKey Your TomTom API key. Yes String
[criteria] Criteria for the corridor search, its structure is as follows (Defaults are marked with '*''):

{
    //Optional, measure and measure value go together if used.
    //Unit for distance/time measurement.
    //detourTime / detourDistance: 
    //In addition will return the time or distance and back to the actual route from the POI detour. 
    //Returns the time or distance back to the actual route from the POI detour. 
    
    measure: ["time",*"distance","euclideanDistance", "detourTime", "detourDistance"],

    //Provide a value in meters/minutes
    measureValue: 10
}
No JSON Object

Response

Format

Response will be a json object, with the following structure:

{
  summary: {
    query: "pizza", //query as interpreted by the search engine
    queryType: "NON_NEAR", //response type. * see response types below
    queryTime: 51,
    numResults: 10,
    totalResults: 35 //total number of results in set.
  },
  results: [] //array of results
}

Where each element of the results array is in the format:

{
  type: "POI",      //type of result. May be: POI, Street, Geography, Point Address
    poi: {          //optional section. Only present if type == POI
      name: "Upper Crust Pizza",
      phone: "+(1)-(831)-4762333",
      categories: [ //Array of categories
        "restaurant",
        "pizza"
      ]
    },
    address: {  //Structured Address for the result
      streetNumber: "2501",
      streetName: "Soquel Dr",
      municipalitySubdivision: "Santa Cruz",
      countrySecondarySubdivision: "Santa Cruz",
      countryTertiarySubdivision: "Santa Cruz",
      countrySubdivision: "CA",
      postalCode: "95065",
      countryCode: "US"
    },
    position: { //position of the result
      lat: "36.9882",
      lon: "-121.97481"
  },
  time: {
    alongRoute: {
        value: 4,
        uom: "S"
    }
    offRoute: {
        value: 11,
        uom: "S"
    }
  }
}
 
 

You are here