POI Categories
Public Preview Notice
Important notes:
- This TomTom Orbis Maps Search API document collection is in Public Preview. Go to the Public Preview - what is it? page to see what this means.
- This API is powered by TomTom Orbis Maps.
- See the TomTom Orbis Maps documentation for more information.
Purpose
The POI Categories service endpoint provides a full list of POI categories and subcategories together with their translations and synonyms.
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 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.
Important note: Either apiVersion
parameter or TomTom-Api-Version
header needs to be present.
https://{baseURL}/maps/orbis/places/poiCategories.{ext}?key={Your_API_Key}&apiVersion={apiVersion}&language={one_of_the_supported_languages}
https://api.tomtom.com/maps/orbis/places/poiCategories.json?key={Your_API_Key}&apiVersion=1
curl 'https://api.tomtom.com/maps/orbis/places/poiCategories.json?key={Your_API_Key}&apiVersion=1'
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.
|
| Endpoint name. |
| A valid response format. |
| An API Key valid for the requested service. |
Optional parameters | Description |
---|---|
| Service version. |
| Language in which the category tree should be returned. When a category
in a requested language is not available, the default language is used
(English). |
Request headers
Optional header | Description |
---|---|
TomTom-Api-Version | Service version. |
Enables response compression. |
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 format in the request URL ext
parameter, the response has the following structure.
1{2 "poiCategories": [3 {4 "id": 7320,5 "name": "Sports Center",6 "childCategoryIds": [7 7320002,8 7320003,9 7320004,10 7320006,11 732000512 ],13 "synonyms": [14 "Fitness Center",15 "Fitness Centre",16 "Fitness Club",17 "Gym",18 "Gymnasium",19 "Health Club",20 "Indoor Sports",21 "Indoors Sports",22 "Sports Centre",23 "Wellness Club"24 ]25 },26 {27 "id": 7374,28 "name": "Stadium",29 "childCategoryIds": [30 7374002,31 7374009,32 7374012,33 7374003,34 7374010,35 7374005,36 7374008,37 7374011,38 7374006,39 7374014,40 7374013,41 7374007,42 737400443 ],44 "synonyms": [45 "Arena",46 "Gymnasium",47 "Indoor Arena",48 "Sports Field",49 "Sports Ground",50 "Sports Stadium",51 "Sportsfield",52 "Sportsground",53 "Velodrome"54 ]55 },56 . . .57 ]58}
When requesting XML output format in the request URL ext
parameter, the response has the following structure.
1<?xml version='1.0' encoding='UTF-8'?>2<response>3 <poiCategories>4 <poiCategory>5 <id>7320</id>6 <name>Sports Center</name>7 <childCategoryIds>8 <childCategoryId>7320002</childCategoryId>9 <childCategoryId>7320003</childCategoryId>10 <childCategoryId>7320005</childCategoryId>11 </childCategoryIds>12 <synonyms>13 <synonym>Gym</synonym>14 <synonym>Health Club</synonym>15 <synonym>Indoors Sports</synonym>16 <synonym>Sports Centre</synonym>17 <synonym>Wellness Club</synonym>18 </synonyms>19 </poiCategory>20 <poiCategory>21 <id>7374</id>22 <name>Stadium</name>23 <childCategoryIds>24 <childCategoryId>7374002</childCategoryId>25 <childCategoryId>7374009</childCategoryId>26 <childCategoryId>7374012</childCategoryId>27 <childCategoryId>7374003</childCategoryId>28 <childCategoryId>7374010</childCategoryId>29 <childCategoryId>7374005</childCategoryId>30 <childCategoryId>7374008</childCategoryId>31 <childCategoryId>7374011</childCategoryId>32 <childCategoryId>7374006</childCategoryId>33 <childCategoryId>7374014</childCategoryId>34 <childCategoryId>7374013</childCategoryId>35 <childCategoryId>7374007</childCategoryId>36 <childCategoryId>7374004</childCategoryId>37 </childCategoryIds>38 <synonyms>39 <synonym>Arena</synonym>40 <synonym>Gymnasium</synonym>41 <synonym>Indoor Arena</synonym>42 <synonym>Sports Field</synonym>43 <synonym>Sports Ground</synonym>44 <synonym>Sports Stadium</synonym>45 <synonym>Sportsfield</synonym>46 <synonym>Sportsground</synonym>47 <synonym>Velodrome</synonym>48 </synonyms>49 </poiCategory>50 ...51 </poiCategories>52</response>
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.
poiCategories array | |
---|---|
Field | Description |
| Category Tree result list. |
poiCategory object | |
Field | Description |
| Unique ID for the category. |
| Name of the category. |
| List of subcategories ids. |
| List of alternative names of the category. |
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 a result. |
| Bad Request : One or more parameters were incorrectly specified. |
| Forbidden : Possible causes include,
|
| Method Not Allowed : The HTTP request method |
| Not Found : The HTTP request method |
| Too Many Requests : The API Key is over QPS (Queries per second). |
| 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. |