Geometry Filter

Service version: 2
Last edit: 2022.12.13

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)
1[
2 {
3 "poi": {
4 "name": "S Restaurant Toms"
5 },
6 "address": {
7 "freeformAddress": "2880 Broadway, New York, NY 10025"
8 },
9 "position": {
10 "lat": 40.80558,
11 "lon": -73.96548
12 }
13 },
14 {
15 "poi": {
16 "name": "Yasha Raman Corporation"
17 },
18 "address": {
19 "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
20 },
21 "position": {
22 "lat": 40.80076,
23 "lon": -73.96556
24 }
25 }
26]
get
geometryList array (JSON)
1[
2 {
3 "type": "CIRCLE",
4 "position": "40.80558, -73.96548",
5 "radius": 100
6 },
7 {
8 "type": "POLYGON",
9 "vertices": [
10 "37.7524152343544, -122.43576049804686",
11 "37.70660472542312, -122.43301391601562",
12 "37.712059855877314, -122.36434936523438",
13 "37.75350561243041, -122.37396240234374"
14 ]
15 }
16]
post
POST body (JSON) containing the poiList and geometryList arrays
1{
2 "poiList": [
3 {
4 "poi": {
5 "name": "S Restaurant Tom's"
6 },
7 "address": {
8 "freeformAddress": "2880 Broadway, New York, NY 10025"
9 },
10 "position": {
11 "lat": 40.80558,
12 "lon": -73.96548
13 }
14 },
15 {
16 "poi": {
17 "name": "Yasha Raman Corporation"
18 },
19 "address": {
20 "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
21 },
22 "position": {
23 "lat": 40.80076,
24 "lon": -73.96556
25 }
26 }
27 ],
28 "geometryList": [
29 {
30 "type": "CIRCLE",
31 "position": "40.80558,-73.96548",
32 "radius": 100
33 },
34 {
35 "type": "POLYGON",
36 "vertices": [
37 "37.7524152343544,-122.43576049804686",
38 "37.70660472542312,-122.43301391601562",
39 "37.712059855877314,-122.36434936523438",
40 "37.75350561243041,-122.37396240234374"
41 ]
42 }
43 ]
44}

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS Methods: GET or POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
get
GET URL request format
https://{baseURL}/search/{versionNumber}/geometryFilter.{ext}?key={Your_API_Key}&geometryList={geometryList}&poiList={poiList}
get
GET URL request example
1https://api.tomtom.com/search/2/geometryFilter.json?key={Your_API_Key}&geometryList=[
2 {
3 "type": "CIRCLE",
4 "position": "40.80558, -73.96548",
5 "radius": 100
6 },
7 {
8 "type": "POLYGON",
9 "vertices": [
10 "37.7524152343544, -122.43576049804686",
11 "37.70660472542312, -122.43301391601562",
12 "37.712059855877314, -122.36434936523438",
13 "37.75350561243041, -122.37396240234374"
14 ]
15 }
16]
17&poiList=[
18 {
19 "poi": {
20 "name": "S Restaurant Toms"
21 },
22 "address": {
23 "freeformAddress": "2880 Broadway, New York, NY 10025"
24 },
25 "position": {
26 "lat": 40.80558,
27 "lon": -73.96548
28 }
29 },
30 {
31 "poi": {
32 "name": "Yasha Raman Corporation"
33 },
34 "address": {
35 "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
36 },
37 "position": {
38 "lat": 40.80076,
39 "lon": -73.96556
40 }
41 }
42]
get
GET curl command request format
1curl 'https://api.tomtom.com/search/2/geometryFilter.json?key={Your_API_Key}&geometryList=[
2 {
3 "type": "CIRCLE",
4 "position": "40.80558, -73.96548",
5 "radius": 100
6 },
7 {
8 "type": "POLYGON",
9 "vertices": [
10 "37.7524152343544, -122.43576049804686",
11 "37.70660472542312, -122.43301391601562",
12 "37.712059855877314, -122.36434936523438",
13 "37.75350561243041, -122.37396240234374"
14 ]
15 }
16]
17&poiList=[
18 {
19 "poi": {
20 "name": "S Restaurant Toms"
21 },
22 "address": {
23 "freeformAddress": "2880 Broadway, New York, NY 10025"
24 },
25 "position": {
26 "lat": 40.80558,
27 "lon": -73.96548
28 }
29 },
30 {
31 "poi": {
32 "name": "Yasha Raman Corporation"
33 },
34 "address": {
35 "freeformAddress": "940 Amsterdam Ave, New York, NY 10025"
36 },
37 "position": {
38 "lat": 40.80076,
39 "lon": -73.96556
40 }
41 }
42]'

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 may be used.

Note: There are no optional parameters in this endpoint.

Required parametersDescription

baseURL
string

Base URL for calling the API.
Values:

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 above xample. 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 above example. The only required attribute of a POI is position. Everything else is optional and will be echoed back when passed in.
Value: List (JSON array) of POIs. position example: 37.553,-122.453

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

Request headers

Optional headersDescription

Accept-Encoding

Enables response compression.
Value: gzip

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 fields section for more information. When requesting JSON output the response has the following structure:

Response body structure - JSON
1{
2 "summary": {
3 "numResults": 1,
4 "queryTime": 0
5 },
6 "results": []
7}

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

results array elements format - JSON
1{
2 "poi": {
3 "name": "Upper Crust Pizza & Pasta"
4 },
5 "address": {
6 "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065"
7 },
8 "position": {
9 "lat": "36.98844",
10 "lon": "-121.97483"
11 }
12}

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
FieldDescription

summary
object

Summary information about the search that was performed.

results
array

Result list, sorted in descending order by score.
summary object
FieldDescription

numResults
integer

Number of results in the response.

queryTime
integer

Time spent on resolving the query.
results array
FieldDescription

poi
object

Information about the Points of Interest in the result. This is an optional section, and is only present if type == POI.
poi object

address
object

Structured address for the result.

position
object

Position of the result:
LatLon

poi object
FieldDescription

name
string

Name of the POI.
address object
FieldDescription

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.

LatLon
FieldDescription

lat
float

Latitude. min/max: -90 to +90
Reference: Latitude, Longitude, and Coordinate System Grids

lon
float

Longitude. min/max: -180 to +180
Reference: Latitude, Longitude, and Coordinate System Grids

Response codes

The following data table contains response codes signifying successful and failed requests to an API server.

CodeMeaning & 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 HTTPS request method ( GET , POST , etc.) is not supported for this request.

404/596

Not Found : The HTTPS 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.

Response headers

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

HeaderDescription

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 , or text/xml.

Content-Encoding

If requested by the client, the Search service applies gzip compression to the responses with the Accept-Encoding header.
Value: gzip