Geometry Search
Purpose
The Geometry Search endpoint allows you to perform a free form search inside a single geometry or many of them.
- The search results that fall inside the geometry/geometries will be returned.
- The service returns
POI
results by default. For other result types, theidxSet
parameter should be used. - To send the geometry you will use a
POST
orGET
request with the JSON as a string value for thegeometryList
parameter. POST
is recommended for all datasets.POST
requests require theContent-Type
header to be set toapplication/json
.GET
can only be used for small datasets.
Run this endpoint
You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.
Options
Option 1. Use a POST
request for all geometry datasets.
Submit the data as a JSON file to the API database using a POST
request.
Note: the geometryList
data array
is included in the POST
body.
1{2 "geometryList": [3 {4 "type":"POLYGON",5 "vertices": [6 "37.7524152343544,-122.43576049804686",7 "37.70660472542312,-122.43301391601562",8 "37.712059855877314,-122.36434936523438",9 "37.75350561243041,-122.37396240234374"10 ]11 },12 {13 "type":"CIRCLE",14 "position":"37.71205,-121.36434",15 "radius":600016 },17 {18 "type":"CIRCLE",19 "position":"37.31205,-121.36434",20 "radius":100021 }22 ]23}
Option 2. Use a GET
request only for small datasets.
Retreive the data from the API database using a GET
request with the geometryList
parameter value set as an array
.
1?geometryList=[2 {3 "type":"POLYGON",4 "vertices":[5 "37.7524152343544,-122.43576049804686",6 "37.70660472542312,-122.43301391601562",7 "37.712059855877314,-122.36434936523438",8 "37.75350561243041,-122.37396240234374"9 ]10 },11 {12 "type":"CIRCLE",13 "position":"37.71205,-121.36434",14 "radius":600015 },16 {17 "type":"CIRCLE",18 "position":"37.31205,-121.36434",19 "radius":100020 }21]
Request data
HTTPS Method: GET
For ease of viewing and identification:
- 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.
URL format
https://{baseURL}/search/{versionNumber}/geometrySearch/{query}.{ext}?key={Your_API_Key}&geometryList={geometryList}&limit={limit}&language={language}&idxSet={idxSet}&extendedPostalCodesFor={extendedPostalCodesFor}&categorySet={categorySet}&brandSet={brandSet}&connectorSet={connectorSet}&fuelSet={fuelSet}&view={view}&openingHours={openingHours}&timeZone={timeZone}&mapcodes={mapcodes}&relatedPois={relatedPois}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}&entityTypeSet={entityTypeSet}
curl command format
curl 'https://{baseURL}/search/{versionNumber}/geometrySearch/{query}.{ext}?key={Your_API_Key}&geometryList={geometryList}&limit={limit}&language={language}&idxSet={idxSet}&extendedPostalCodesFor={extendedPostalCodesFor}&categorySet={categorySet}&brandSet={brandSet}&connectorSet={connectorSet}&fuelSet={fuelSet}&view={view}&openingHours={openingHours}&timeZone={timeZone}&mapcodes={mapcodes}&relatedPois={relatedPois}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}&entityTypeSet={entityTypeSet}'
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.
- 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.
Required parameters | Description |
---|---|
baseURL string | Base URL for calling the API. Values:
|
versionNumber string | The service version. Value: The current value is 2 . |
query string | The query string. It must be properly URL-encoded. Value: A properly URL-encoded query string. |
ext string | A valid response format: Values: json , jsonp , js , or xml |
key string | An API Key valid for the requested service. Value: Your valid API Key . |
geometryList object | List of geometries to search in (JSON). Available types are:
GET Example vertices list/array of geometries - JSON
|
Optional parameters | Description |
---|---|
limit integer | The maximum number of responses that will be returned. Default value: 10 Maximum value: 100 |
language string | Language in which search results should be returned.
|
extendedPostalCodesFor string | Indexes for which extended postal codes should be included in the results.
Usage examples:
extendedPostalCode property of an address. Availability is region-dependent. |
idxSet string | The idxSet parameter allows for fine tuning Search by specifying which indexes to utilize for the search. The pre-defined indexes are:
Usage examples:
|
categorySet string | A comma-separated list of categories which could be used to restrict the result to the Points Of Interest of specific categories. The list of categories can be discovered using the POI Categories endpoint. Value: A comma-separated list of category identifiers (in any order).
Usage examples:
|
brandSet string | A comma-separated list of brand names which could be used to restrict the result to Points Of Interest of specific brands. Value: A comma-separated list of brand names (in any order).
Usage examples:
|
connectorSet string | A comma-separated list of connector types which could be used to restrict the result to the Points Of Interest of type Electric Vehicle Station supporting specific connector types. See the list of Supported Connector Types. Value: A comma-separated list of connector types (in any order).
Usage examples:
|
minPowerKW double | An optional parameter which could be used to restrict the result to the Points Of Interest of type Electric Vehicle Station supporting at least one connector with a specific minimal value of power in kilowatts (closed interval - with that value). Value: A double value representing the power rate in kilowatts. Usage example:
|
maxPowerKW double | An optional parameter which could be used to restrict the result to the Points Of Interest of type Electric Vehicle Station supporting at least one connector with a specific maximum value of power in kilowatts (closed interval - with that value). Value: A double value representing the power rate in kilowatts. Usage example:
|
fuelSet string | A comma-separated list of fuel types which could be used to restrict the result to the Points Of Interest of specific fuels.
Value: A comma-separated list of fuel type identifiers (in any order).
Available values:
Usage examples:
|
view string | Geopolitical View.
|
openingHours string | List of opening hours for a POI (Points of Interest). Value: nextSevenDays
Usage example: openingHours=nextSevenDays |
timeZone string | Used to indicate the mode in which the timeZone object should be returned. Values: iana . Mode shows the IANA ID which allows the user to determine the current time zone for the POI.Usage example: timeZone=iana |
mapcodes string | Enables the return of a comma-separated mapcodes list.
. Values: One or more of: Local , International , Alternative
Usage examples:
|
relatedPois string | An optional parameter that provides the possibility to return related Points Of Interest. Default value: off Values: off , child , parent , all Points Of Interest can be related to each other when one is physically part of another.
Usage examples:
|
entityTypeSet string | A comma-separated list of entity types which can be used to restrict the result to a specific entity type. Parameter should be used with the idxSet parameter set to the Geography value. Value: A comma-separated list of of entity types. Item order in the list does not matter. Values are case sensitive. Available values:
Usage examples:
|
Request headers
Optional headers | Description |
---|---|
Accept-Encoding | Enables response compression. Value: gzip |
Tracking-ID | Specifies an identifier for the request.
Value: An identifier for the request. |
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 documentation for more information.
When requesting JSON output, the response has the following structure:
1{2 "summary": {3 "query": "pizza",4 "queryType": "NON_NEAR",5 "queryTime": 82,6 "numResults": 10,7 "offset": 0,8 "totalResults": 479,9 "fuzzyLevel": 110 },11 "results": []12}
Each element of the results
array is in the following format:
Results array elements format - JSON
1{2 "type": "POI",3 "id": "g6JpZK84NDAwNjEwMDE4NjUxNDKhY6NVU0GhdqdVbmlmaWVk",4 "score": 4,5 "info": "search:ta:840061001865142-US",6 "entityType": "Municipality",7 "poi": {8 "name": "Upper Crust Pizza & Pasta",9 "phone": "+(1)-(831)-4762333",10 "url": "www.uppercrustsc.com/",11 "brands": [12 {13 "name": "Upper Crust"14 }15 ],16 "categorySet": [17 {18 "id": 731501519 }20 ],21 "categories": [22 "pizza",23 "restaurant"24 ],25 "openingHours": {26 "mode": "nextSevenDays",27 "timeRanges": [28 {29 "startTime": {30 "date": "2019-02-05",31 "hour": 7,32 "minute": 033 },34 "endTime": {35 "date": "2019-02-05",36 "hour": 21,37 "minute": 038 }39 },40 {41 "startTime": {42 "date": "2019-02-06",43 "hour": 7,44 "minute": 045 },46 "endTime": {47 "date": "2019-02-06",48 "hour": 21,49 "minute": 050 }51 },52 {53 "startTime": {54 "date": "2019-02-07",55 "hour": 7,56 "minute": 057 },58 "endTime": {59 "date": "2019-02-07",60 "hour": 21,61 "minute": 062 }63 },64 {65 "startTime": {66 "date": "2019-02-08",67 "hour": 7,68 "minute": 069 },70 "endTime": {71 "date": "2019-02-08",72 "hour": 21,73 "minute": 074 }75 },76 {77 "startTime": {78 "date": "2019-02-09",79 "hour": 7,80 "minute": 081 },82 "endTime": {83 "date": "2019-02-09",84 "hour": 21,85 "minute": 086 }87 },88 {89 "startTime": {90 "date": "2019-02-10",91 "hour": 7,92 "minute": 093 },94 "endTime": {95 "date": "2019-02-10",96 "hour": 12,97 "minute": 098 }99 },100 {101 "startTime": {102 "date": "2019-02-10",103 "hour": 14,104 "minute": 0105 },106 "endTime": {107 "date": "2019-02-10",108 "hour": 21,109 "minute": 0110 }111 }112 ]113 },114 "classifications": [115 {116 "code": "RESTAURANT",117 "names": [118 {119 "nameLocale": "en-US",120 "name": "pizza"121 },122 {123 "nameLocale": "en-US",124 "name": "restaurant"125 }126 ]127 }128 ],129 "timeZone": {130 "ianaId": "Europe/Andorra"131 }132 },133"relatedPois":[134 {135 "relationType": "child",136 "id": "g6JpZK83ODQwMDkwMDAwMjUxMTWhY6NBUkWhdqdVbmlmaWVk"137 },138 {139 "relationType": "child",140 "id": "u234HsadasKHZK81MjgwMDkwMDQyNDY3jashfsaASDHkjhdA"141 }142 ],143 "address": {144 "streetNumber": "2501",145 "streetName": "Soquel Dr",146 "municipalitySubdivision": "Santa Cruz, Live Oak",147 "municipality": "Santa Cruz, Live Oak",148 "countrySecondarySubdivision": "Santa Cruz",149 "countryTertiarySubdivision": "Santa Cruz",150 "countrySubdivision": "CA",151 "postalCode": "95065",152 "extendedPostalCode": "950652023",153 "countryCode": "US",154 "country": "United States Of America",155 "countryCodeISO3": "USA",156 "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065",157 "countrySubdivisionName": "California",158 "localName": "Santa Cruz"159 },160 "position": {161 "lat": 36.98844,162 "lon": -121.97483163 },164 "mapcodes":[165 {166 "type":"Local",167 "fullMapcode":"US-CA FS.WRH3",168 "territory":"US-CA",169 "code":"FS.WRH3"170 },171 {172 "type":"International",173 "fullMapcode":"S4ZW4.990V"174 },175 {176 "type":"Alternative",177 "fullMapcode":"US-CA 4349.S8W",178 "territory":"US-CA",179 "code":"4349.S8W"180 },181 {182 "type":"Alternative",183 "fullMapcode":"US-CA JJCH.H9DF",184 "territory":"US-CA",185 "code":"JJCH.H9DF"186 },187 {188 "type":"Alternative",189 "fullMapcode":"USA JJCH.H9DF",190 "territory":"USA",191 "code":"JJCH.H9DF"192 }193 ],194 "viewport": {195 "topLeftPoint": {196 "lat": 36.98934,197 "lon": -121.97596198 },199 "btmRightPoint": {200 "lat": 36.98754,201 "lon": -121.9737202 }203 },204 "entryPoints": [205 {206 "type": "main",207 "position": {208 "lat": 36.98817,209 "lon": -121.97487210 }211 },212 {213 "type": "minor",214 "functions": ["FrontDoor"],215 "position": {216 "lat": 52.30987,217 "lon": 4.76093218 }219 }220 ],221 "addressRanges": {222 "rangeLeft": "1 - 3",223 "rangeRight": "2 - 12",224 "from": {225 "lat": 51.16561,226 "lon": 19.48489227 },228 "to": {229 "lat": 51.16545,230 "lon": 19.4863231 }232 },233 "chargingPark": {234 "connectors": [235 {236 "connectorType": "IEC62196Type2CCS",237 "ratedPowerKW": 22.2,238 "currentA": 32,239 "currentType": "AC3",240 "voltageV": 380241 },242 {243 "connectorType": "Tesla",244 "ratedPowerKW": 43.2,245 "currentA": 16,246 "currentType": "AC3",247 "voltageV": 480248 }249 ]250 },251 "dataSources": {252 "chargingAvailability": {253 "id": "442009000132285"254 },255 "parkingAvailability": {256 "id": "00000000-0005-36de-0009-20d4467654e2"257 },258 "fuelPrice": {259 "id": "1:cf81fe50-6218-11ea-a677-d05099d5f839"260 },261 "geometry": {262 "id": "00004e4c-3100-3c00-0000-0000685e23c7"263 }264 }265}
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. summary object |
results array | Result list, sorted in descending order by score. results array |
summary object | |
Field | Description |
query string | Query as interpreted by the search engine. |
queryType string | Response type. Can be NEARBY or NON_NEAR . |
queryTime integer | Time spent on resolving the query. |
numResults integer | Number of results in the response. |
offset integer | Starting offset of the returned results within the full result set. |
totalResults integer | Total number of results found. |
fuzzyLevel integer | Maximum fuzzy level required to provide results. |
geoBias object | Position used to bias the results. LatLon |
results array | |
Field | Description |
type string | Type of result. Values: One of: POI , Street , Geography , Point Address , Address Range , Cross Street |
id string | A stable unique id for the POI index, and a non-stable unique id for the other indexes. Note: stable id means that it doesn't change between data releases without changing the location, attribution or classification. |
score double | Score of the result. A larger score means there is a probability that a result meeting the query criteria is higher. |
dist double | Unit: meters. This is the distance to an object if geoBias was provided. |
info string | Information about the original data source of the result. |
entityType string | Optional section. Only present if type == Geography .Values: One of:
|
poi object | Information about the Points of Interest in the result. Optional section. Only present if type == POI . poi object |
relatedPois object | List of related Points Of Interest. relatedPois object |
address object | Structured address for the result. address object |
position object | Position of the result: LatLon |
mapcodes array | List of mapcode objects mapcodes object |
viewport object | A viewport which can be used to display the result on a map. viewport object |
entrypoints array | List of entry points of the POI. entryPoints array |
addressRanges object | Address ranges on a street segment. Available only for results where the result type is equal to "Address Range". addressRanges object |
chargingPark object | A list of chargingPark objects. Present only when the Points of Interest are of the Electric Vehicle Station type. chargingPark object |
dataSources object | Optional section. Reference ids for use with the Additional Data service. dataSources object |
poi object | |
Field | Description |
name string | Name of the POI . |
phone string | Telephone number. |
brands array | The list of POI brands. brands array |
url string | Website URL. |
categories array Deprecated | The list of POI categories. Supported Category Codes.
|
categorySet array | The list of the most specific POI categories. categorySet array |
openingHours object | List of opening hours for a POI (Points of Interest). openingHours object |
classifications array | The list of POI category classifications. classifications array |
timeZone object | Time zone information for the POI . timeZone object |
categorySet array | |
Field | Description |
id number | Category id. Full list of available categories is available under the POI Categories endpoint. |
brands array | |
Field | Description |
name string | Brand name. |
classifications array | |
Field | Description |
code string | Fixed top level category code. Supported Category Codes |
names array | List of category names with locale code information. Currently only the en-US locale is returned. names array |
names array | |
Field | Description |
nameLocale string | Locale code of this category name. |
name string | Category name in given locale. |
relatedPois object | |
Field | Description |
relationType string | Relation type: child , parent |
id string | Pass this as entityId to the Place by ID service to fetch additional data for the Point Of Interest. |
address object | |
Field | Description |
streetNumber string | The building number on the street. |
streetName string | The street name. |
municipalitySubdivision string | Sub / Super City. |
municipality string | City / Town. |
countrySecondarySubdivision string | County. |
countryTertiarySubdivision string | Named Area. |
countrySubdivision string | State or Province. |
postalCode string | Postal Code / Zip Code. |
postalName string | An address component which represents the name for a postal code that is related to a single administrative area, city, town, or other populated place. Note:
|
extendedPostalCode string | Extended postal code (availability dependent on region). |
countryCode string | Country. Note: this is a two-letter code, not a country name. |
country string | Country name. |
countryCodeISO3 string | ISO alpha-3 country code. |
freeformAddress string | An address line formatted according to:
|
countrySubdivisionName string | The full name of the first level of a country's administrative hierarchy.
|
countrySubdivisionCode string | countrySubdivisionCode prefixed by countryCode (countryCode-countrySubdivisionCode ) and the hyphen forms the ISO 3166-2 code.
|
localName string | An address component which represents the name of a geographic area or locality that groups a number of addressable objects for addressing purposes, without being an administrative unit. |
mapcodes object | |
Field | Description |
type string | Type of mapcode.Local
International
Alternative
|
fullMapcode string | The full form of a mapcode (territory + code ).
|
territory string | The territory element of the mapcode.
|
code string | The mapcode without the territory element.
|
viewport object | |
Field | Description |
topLeftPoint object | Top-left corner of the rectangle: LatLon |
btmRightPoint object | Bottom-right corner of the rectangle: LatLon |
entryPoints array | |
Field | Description |
type string | The main entry point. One of: main , minor |
functions array | If present, represents the type of access for the POI . Example: FrontDoor |
position object | Position of the entry point: LatLon |
addressRanges object | |
Field | Description |
rangeLeft string | An address range on the left side of a street segment (assuming looking from the "from" end toward the "to" end). |
rangeRight string | An address range on the right side of a street segment (assuming looking from the "from" end toward the "to" end). |
from object | A beginning point of a street segment. LatLon |
to object | An end point of a street segment. LatLon |
chargingPark object | |
Field | Description |
connectors array | A list of connectors available in the Points Of Interest of an Electric Vehicle Station type. connectors array |
connectors array | |
Field | Description |
connectorType string | Type of the connector available in Electric Vehicle Station. See the: List of supported connector types. |
ratedPowerKW double | Rated power of the connector in kilowatts (kW). |
currentA integer | Current value of the connector in amperes (A). |
currentType string | Current type of the connector. |
voltageV integer | Voltage of the connector in Volts (V). |
dataSources object | |
Field | Description |
chargingAvailability object | Information about the charging stations availability. Only present if type == POI . chargingAvailability object |
parkingAvailability object | Information about the parking site availability. Only present if type == POI . parkingAvailability object |
fuelPrice object | Information about the fuel station prices. Only present if type == POI . fuelPrice object |
geometry object | Information about the geometric shape of the result. Only present if type == Geography or POI . geometry object |
chargingAvailability object | |
Field | Description |
id string | Pass this as chargingAvailability to the EV Charging Stations Availability service to fetch charging availability information for this result. |
parkingAvailability object | |
Field | Description |
id string | Pass this as parkingAvailability to the Parking Availability service to fetch parking availability information for this result. |
fuelPrice object | |
Field | Description |
id string | Pass this as fuelPrice to the Fuel Prices service to fetch fuel price information for this result. |
geometry object | |
Field | Description |
id string | Pass this as geometryId to the Additional Data service to fetch geometry information for this result. |
Field | Description |
sourceName string | Name of an additional data provider. |
LatLon | |
Field | Description |
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 |
openingHours object | |
Field | Description |
mode string | Mode used in the request. |
timeRanges array | List of time ranges for the next 7 days. timeRanges array |
timeRanges array | |
Field | Description |
startTime object | The point in the next 7 days range when a given POI is being opened, or the beginning of the range if it was opened before the range, inclusive. startTime object |
endTime object | The point in the next 7 days range when a given POI is being opened, or the beginning of the range if it was opened before the range, exclusive endTime object |
startTime object | |
Field | Description |
date string | Represents the current day in the calendar year in the POI time zone. |
hour integer | Hours are in the 24 hour format in the local time of a POI ; possible values are 0 - 23 . |
minute integer | Minutes are in the local time of a POI ; possible values are 0 - 59 . |
endTime object | |
Field | Description |
date string | Represents current day in calendar year in POI time zone. |
hour integer | Hours are in the 24 hour format in the local time of a POI ; possible values are 0 - 23 . |
minute integer | Minutes are in the local time of a POI ; possible values are 0 - 59 . |
timeZone object | |
Field | Description |
ianaId string | ID from the IANA Time Zone Database. |
Response codes
The following 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 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. |
429 | Too Many Requests: The API Key is over QPS (Queries per second). |
5xx | Server Error: The service was unable to process your request. Contact support to resolve the issue. |
Response headers
The following 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 Values: type/subtype is one of application/json , text/javascript , 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 |
Tracking-ID | An identifier for the request.
identifier for the request. |
Error response
The error response content type depends on the ext
parameter.
1{2 "errorText":"Error parsing 'language': Language tag 'en-ES' not supported",3 "detailedError":{4 "code":"BadRequest",5 "message":"Error parsing 'language': Language tag 'en-ES' not supported",6 "target":"language"7 },8 "httpStatusCode":"400"9}
1<?xml version="1.0" encoding="UTF-8"?>2<response>3 <errorText>Error parsing 'language': Language tag 'en-ES' not supported</errorText>4 <detailedError>5 <code>BadRequest</code>6 <message>Error parsing 'language': Language tag 'en-ES' not supported</message>7 <target>language</target>8 </detailedError>9 <httpStatusCode>400</httpStatusCode>10</response>
Error response fields
Primary fields | Description |
---|---|
errorText string | A human-readable description of the error. |
detailedError object | Detailed information about the error. detailedError object |
httpStatusCode integer | Response codes signifying failed requests to an API server. |
detailedError object | |
Field | Description |
code string | One of a server-defined set of error codes. |
message string | A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users. |
target string | Optional. Target of the particular error. Value: The name of the request parameter causing the error. |
Additional information
Indexes abbreviation values
In some cases, list of indexes can be passed as a parameter to query, which should be listed with their abbreviations, available values are:
- Geo = Geographies - areas on map which represent administrative divison of a land ie. country, state, city.
- PAD = Point Addresses - points on map where specific address with street name and number can be found in index, ie. Soquel Dr 2501.
- Addr = Address ranges - for some streets there are address points that are interpolated from the beginning and end of the street, those points are represented as address ranges.
- Str = Streets - representation of streets on the map.
- XStr = Cross Streets (intersections) - representations of junctions; places where two streets intersect.
- POI = Points of Interest - points on map that are worth attention and may be interesting.