Place by ID
Purpose
The Place by Id service endpoint provides detailed information about the Place found by its identifier (entityId
). Currently, Place by Id supports all types by ids.
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.
https://{baseURL}/search/{versionNumber}/place.{ext}?entityId={Poi_id}&key={Your_API_Key}&language={one_of_the_supported_languages}&openingHours={openingHours}&timeZone={timeZone}&mapcodes={mapcodes}&relatedPois={relatedPois}&view={view}
https://api.tomtom.com/search/2/place.json?entityId=00004e4c-3100-3c00-0000-0000685e23c7&key={Your_API_Key}
curl 'https://api.tomtom.com/search/2/place.json?entityId=00004e4c-3100-3c00-0000-0000685e23c7&key={Your_API_Key}'
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.
Required parameters | Description |
---|---|
| Base URL for calling the API.
|
| Service version. |
| Endpoint name. |
| A valid response format. |
| A unique |
| An API Key valid for the requested service. |
Optional parameters | Description |
---|---|
| Language in which details about a specific POI should be returned. When
information about a specific POI is not available in the requested
language or the language is not specified, the NGT (neutral ground
truth) language is used. |
| List of opening hours for a POI (Points of Interest). |
| Used to indicate the mode in which the |
| Enables the return of a comma-separated mapcodes list. Can also filter
the response to only show selected mapcode types. See the mapcodes object in the response.
|
| An optional parameter that provides the possibility to return related Points Of Interest.
|
| Geopolitical View. The context used to resolve the handling of disputed
territories. Views include |
Request headers
Note: There are no required request headers in this endpoint.
Optional headers | Description |
---|---|
Enables response compression. |
Response data
Response body
For illustrative purposes the following example 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 documentation for more information. When requesting JSON output, the response has the following structure:
1{2 "summary": {3 "query": "n/a",4 "queryType": "NON_NEAR",5 "queryTime": 24,6 "numResults": 1,7 "offset": 0,8 "totalResults": 1,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": 5,5 "dist": 0,6 "info": "search:ta:840061001865142-US",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": ["pizza", "restaurant"],22 "openingHours": {23 "mode": "NEXT_SEVEN_DAYS",24 "timeRanges": [25 {26 "startTime": {27 "date": "2019-02-05",28 "hour": 7,29 "minute": 030 },31 "endTime": {32 "date": "2019-02-05",33 "hour": 21,34 "minute": 035 }36 },37 {38 "startTime": {39 "date": "2019-02-06",40 "hour": 7,41 "minute": 042 },43 "endTime": {44 "date": "2019-02-06",45 "hour": 21,46 "minute": 047 }48 },49 {50 "startTime": {51 "date": "2019-02-07",52 "hour": 7,53 "minute": 054 },55 "endTime": {56 "date": "2019-02-07",57 "hour": 21,58 "minute": 059 }60 },61 {62 "startTime": {63 "date": "2019-02-08",64 "hour": 7,65 "minute": 066 },67 "endTime": {68 "date": "2019-02-08",69 "hour": 21,70 "minute": 071 }72 },73 {74 "startTime": {75 "date": "2019-02-09",76 "hour": 7,77 "minute": 078 },79 "endTime": {80 "date": "2019-02-09",81 "hour": 21,82 "minute": 083 }84 },85 {86 "startTime": {87 "date": "2019-02-10",88 "hour": 7,89 "minute": 090 },91 "endTime": {92 "date": "2019-02-10",93 "hour": 12,94 "minute": 095 }96 },97 {98 "startTime": {99 "date": "2019-02-10",100 "hour": 14,101 "minute": 0102 },103 "endTime": {104 "date": "2019-02-10",105 "hour": 21,106 "minute": 0107 }108 }109 ]110 },111 "classifications": [112 {113 "code": "RESTAURANT",114 "names": [115 {116 "nameLocale": "en-US",117 "name": "pizza"118 },119 {120 "nameLocale": "en-US",121 "name": "restaurant"122 }123 ]124 }125 ],126 "timeZone": {127 "ianaId": "Europe/Andorra"128 }129 },130 "address": {131 "streetNumber": "2501",132 "streetName": "Soquel Dr",133 "municipalitySubdivision": "Santa Cruz, Live Oak",134 "municipality": "Santa Cruz, Live Oak",135 "countrySecondarySubdivision": "Santa Cruz",136 "countryTertiarySubdivision": "Santa Cruz",137 "countrySubdivision": "CA",138 "postalCode": "95065",139 "extendedPostalCode": "950652023",140 "countryCode": "US",141 "country": "United States Of America",142 "countryCodeISO3": "USA",143 "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065",144 "countrySubdivisionName": "California",145 "localName": "Santa Cruz"146 },147 "position": {148 "lat": 36.98844,149 "lon": -121.97483150 },151 "mapcodes": [152 {153 "type": "Local",154 "fullMapcode": "US-CA FS.WRH3",155 "territory": "US-CA",156 "code": "FS.WRH3"157 },158 {159 "type": "International",160 "fullMapcode": "S4ZW4.990V"161 },162 {163 "type": "Alternative",164 "fullMapcode": "US-CA 4349.S8W",165 "territory": "US-CA",166 "code": "4349.S8W"167 },168 {169 "type": "Alternative",170 "fullMapcode": "US-CA JJCH.H9DF",171 "territory": "US-CA",172 "code": "JJCH.H9DF"173 },174 {175 "type": "Alternative",176 "fullMapcode": "USA JJCH.H9DF",177 "territory": "USA",178 "code": "JJCH.H9DF"179 }180 ],181 "viewport": {182 "topLeftPoint": {183 "lat": 36.98934,184 "lon": -121.97596185 },186 "btmRightPoint": {187 "lat": 36.98754,188 "lon": -121.9737189 }190 },191 "entryPoints": [192 {193 "type": "main",194 "position": {195 "lat": 36.98817,196 "lon": -121.97487197 }198 }199 ],200 "chargingPark": {201 "connectors": [202 {203 "connectorType": "Tesla",204 "ratedPowerKW": 25,205 "voltageV": 400,206 "currentA": 62,207 "currentType": "DC"208 }209 ]210 },211 "dataSources": {212 "chargingAvailability": {213 "id": "442009000132285"214 },215 "geometry": {216 "id": "00004e4c-3100-3c00-0000-0000685e23c7"217 }218 }219}
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 | Description |
---|---|
| Summary information about the search that was performed. |
| Result list, sorted in descending order by score. |
summary object | |
Field | Description |
| Query as interpreted by the search engine. |
| Response type. Can be |
| Time spent on resolving the query. |
| Number of results in the response. |
| Starting offset of the returned results within the full result set. |
| Total number of results found. |
| Maximum fuzzy level required to provide results. |
results array | |
Field | Description |
| Type of result. One of: |
| A stable, unique id for the POI index, and a non-stable, unique id for the other indexes. Note: Stable id means that it does not change between data releases without changing the location, attribution, or classification. |
| Score of the result. A larger score means there is a probability that a result meeting the query criteria is higher. |
| Unit: meters. This is the distance to an object if |
| Information about the original data source of the result. |
| Optional section. Only present if
|
| Information about the Points of Interest in the result. Optional
section. Only present if |
| List of related Points Of Interest. |
| Structured address for the result. |
| Position of the result: LatLon. |
| List of |
| A viewport which can be used to display the result on a map. |
| Optional section. Only present if |
| List of entry points of the POI. |
| Address ranges on a street segment. Available only for results where the
result type is equal to "Address Range". |
| A list of |
| Optional section. Reference ids for use with the Additional Data service. |
| Optional section. List of fuel types served by the petrol station. |
| Optional section. List of vehicle types supported by the petrol station. |
poi object | |
Field | Description |
| Name of the POI. |
| Telephone number. |
| The list of POI brands. |
| Website URL. |
| The list of POI categories.
|
| The list of the most specific POI categories. |
| List of opening hours for a POI (Points of Interest). |
| The list of POI category classifications. |
| Time zone information for the POI. |
categorySet array | |
Field | Description |
| Category id. A full list of available categories is available under the POI Categories endpoint. |
brands array | |
Field | Description |
| Brand name. |
classifications array | |
Field | Description |
| Fixed top level category code. Supported Category Codes](/search-api/documentation/product-information/supported-category-codes) |
| List of category names with locale code information. Currently only the |
names array | |
Field | Description |
| Locale code of this category name. |
| Category name in given locale. |
relatedPois object | |
Field | Description |
| Relation type: |
| Pass this as |
address object | |
Field | Description |
| The building number on the street. |
| The street name. |
| Sub City |
| Sub Sub City |
| Neighbourhood |
| City / Town |
| County |
| Named Area |
countrySubdivision` | State or Province |
| Postal Code / Zip Code |
| An address component that represents the name for a postal code that is
related to a single administrative area, city, town, or other populated
place. Note: This field only appears for geographies having |
| Extended postal code (availability is dependent on region). |
| Country (Note: this is a two-letter code, not a country name.) |
| Country name |
| ISO alpha-3 country code |
| 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. For the USA, in the case of geographies with |
| The full name of the first level of a country's administrative
hierarchy. This field appears only in case |
|
|
| 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 |
| Types of mapcode.
|
| The full form of a mapcode ( |
| The
an address has little meaning unless the user also knows what state
it's in (just as, elsewhere, an address has little meaning if the
user doesn't know what country it's in). More information about
|
| The mapcode without the |
viewport object | |
Field | Description |
| Top-left corner of the rectangle. LatLon |
| Bottom-right corner of the rectangle. LatLon |
boundingBox object | |
Field | Description |
| Top-left position of the bounding box. LatLon |
| Bottom-right position of the bounding box. LatLon |
entryPoints array | |
Field | Description |
| The main entry point. One of: |
| If present, represents the type of access for the POI. Example: |
| Position of the entry point. LatLon |
addressRanges object | |
Field | Description |
| An address range on the left side of a street segment (assuming looking from the "from" end toward the "to" end). |
| An address range on the right side of a street segment (assuming looking from the "from" end toward the "to" end). |
| A beginning point of a street segment. LatLon |
| An end point of a street segment. LatLon |
chargingPark object | |
Field | Description |
| A list of connectors available in the Points Of Interest of an Electric Vehicle Station type. |
connectors array | |
Field | Description |
| Type of the connector available in Electric Vehicle Station. See: Supported Connector Types. |
| Rated power of the connector in kilowatts (kW). |
| Current value of the connector in amperes (A). |
| Current type of the connector. |
| Voltage of the connector in Volts (V). |
dataSources object | |
Field | Description |
| Information about the charging stations availability. Only present if |
| Information about the parking site availability. Only present if |
| Information about the fuel station prices. Only present if |
| Information about the geometric shape of the result. Only present if |
chargingAvailability object | |
Field | Description |
| Pass this as |
parkingAvailability object | |
Field | Description |
| Pass this as |
fuelPrice object | |
Field | Description |
| Pass this as |
geometry object | |
Field | Description |
| Pass this as |
| Name of an additional data provider. |
LatLon | |
Field | Description |
| Latitude. min/max: |
| Longitude. min/max: |
openingHours object | |
Field | Description |
| Mode used in the request. |
| List of time ranges for the next 7 days. |
timeRanges array | |
Field | Description |
| 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. |
| 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. |
startTime object, endTime object | |
Field | Description |
| Represents current day in calendar year in POI time zone. |
| Hours are in the 24 hour format in the local time of a POI; possible values are |
| Minutes are in the local time of a POI; possible values are |
timeZone object | |
Field | Description |
| 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 |
---|---|
| OK : The search successfully returned zero or more results. |
| Bad Request : One or more parameters were incorrectly specified. |
| Forbidden : Possible causes include:
|
| Method Not Allowed : The HTTP methods |
| Not Found : The HTTP request methods |
| 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 |
---|---|
Ensures that clients implementing the CORS security model are able to
access the response from this service. | |
Indicates the format of the response, as chosen by the client. | |
If requested by the client, the Search service applies gzip compression
to the responses with the Accept-Encoding header. |