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

Geometry Filter

 

Service version: 2
Last edit: 2019.03.28

On this page

Purpose

The Geometry Filter endpoint becomes handy when a list of POIs is already available and needs to be filtered using a list of geometries.

  • It will return POIs that lie within any of the geometries.
  • The Geometry and POI lists can be sent via a POST or GET Request, POST is recommended for large datasets. For example:

GET poiList array (JSON)

[
  {
    "poi": {
      "name": "S Restaurant Toms"
    },
    "address": {
      "freeformAddress": "2880 Broadway, New York, NY 10025"
    },
    "position": {
      "lat": 40.80558,
      "lon": -73.96548
    }
  },
  {
    "poi": {
      "name": "Yasha Raman Corporation"
    },
    "address": {
      "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
    },
    "position": {
      "lat": 40.80076,
      "lon": -73.96556
    }
  }
]

GET geometryList array (JSON)

[
  {
    "type": "CIRCLE",
    "position": "40.80558, -73.96548",
    "radius": 100
  },
  {
    "type": "POLYGON",
    "vertices": [
      "37.7524152343544, -122.43576049804686",
      "37.70660472542312, -122.43301391601562",
      "37.712059855877314, -122.36434936523438",
      "37.75350561243041, -122.37396240234374"
    ]
  }
]

POST body (JSON) containing the poiList and geometryList arrays

{
  "poiList": [
    {
      "poi": {
        "name": "S Restaurant Tom's"
      },
      "address": {
        "freeformAddress": "2880 Broadway, New York, NY 10025"
      },
      "position": {
        "lat": 40.80558,
        "lon": -73.96548
      }
    },
    {
      "poi": {
        "name": "Yasha Raman Corporation"
      },
      "address": {
        "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
      },
      "position": {
        "lat": 40.80076,
        "lon": -73.96556
      }
    }
  ],
  "geometryList": [
    {
      "type": "CIRCLE",
      "position": "40.80558,-73.96548",
      "radius": 100
    },
    {
      "type": "POLYGON",
      "vertices": [
        "37.7524152343544,-122.43576049804686",
        "37.70660472542312,-122.43301391601562",
        "37.712059855877314,-122.36434936523438",
        "37.75350561243041,-122.37396240234374"
      ]
    }
  ]
}

▲ Return to top

Run this endpoint

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.

▲ Return to top

Request data

HTTPS Methods: GET or POST

URL format

GET https://<baseURL>/search/<versionNumber>/geometryFilter.<ext>?key=<Your_API_Key>&geometryList=<geometryList>&poiList=<poiList>

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.
Required parameters
Parameter Description
baseURL
string
Base URL for calling the API:
Value: api.tomtom.com
versionNumber
string
The service version number.
Value: The current value is 2.
ext
string
A valid response format:
Values: JSON, JSONP, JS, or XML
geometryList
array
List (JSON array) of geometries to filter by.

  • Available types are POLYGON and CIRCLE.
  • Format is as in the example above.
  • The Circle radius unit is in meters.

Value: List (JSON array) of geometries.

poiList
array
List (JSON array) of POIs to filter by.

  • Format is as in the example above.
  • The only required attribute of a POI is "position".
    "position" example: 37.553,-122.453
  • Everything else is optional and will be echoed back when passed in.

Value: List (JSON array) of POIs.

key
string
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parameters
Note: There are no optional parameters in this endpoint.

▲ Return to top

Response data

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 field section for more information.

When requesting JSON output the Response has the following structure:

{
  "summary": {
    "numResults": 1,
    "queryTime": 0
  },
  "results": []
}

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

{
  "poi": {
    "name": "Upper Crust Pizza & Pasta"
  },
  "address": {
    "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065"
  },
  "position": {
    "lat": "36.98844",
    "lon": "-121.97483"
  }
}

▲ 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.

Primary fields
Field Description
summary{}
object
Summary information about the search that was performed.
results[]
array
Result list, sorted in descending order by score.
summary{} object
Field Description
numResults
integer
Number of Results in the Response.
queryTime
integer
Time spent on resolving the query.
results[] array
Field Description
poi
object
Optional section. Only present if type = = POI.
address
object
Structured address for the Result.
position
object
Position of the Result.
Example: 37.553,-122.453
poi{} object
Field Description
name
string
Name of the POI.
address{} object
Field Description
freeformAddress
string
An address line formatted according to:

  • The formatting rules of the Result's country of origin.
  • In the case of countries, its full country name.
position{} object
Field Description
lat
float
Latitude. Example: 37.553
lon
float
Longitude. Example: -122.453

▲ Return to top

HTTP Response codes

The following data table contains Response codes signifying successful and failed Requests to an API server.

Code Meaning & possible causes
200 OK: The search successfully returned zero or more results.
400 Bad Request: One or more parameters were incorrectly specified.
403 Forbidden: Possible causes include,

  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
405 Method Not Allowed: The HTTP Request method (GET, POST, etc.) is not supported for this Request.
404/596 Not Found: The HTTP Request method (GET, POST, etc.) or path is incorrect.
5xx Server Error: The service was unable to process your Request. Contact support to resolve the issue.

▲ Return to top

Response headers

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

Header Description
Access-Control-Allow-Origin Ensures that clients implementing the CORS security model are able to access the response from this service.
Value: An asterisk "*" that signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its Response indicating which origin sites are allowed.
Content-Type Indicates the format of the response, as chosen by the client.
Format: type/subtype; charset=utf-8
Value: type/subtype is one of:

  • application/json
  • text/javascript
  • text/xml

▲ Return to Top