POI Categories

Service version: 2
Last edit: 2019.04.04

Purpose

The POI Categories service endpoint provides a full list of POI categories and subcategories together with their translations and synonyms.

▲ Return to top

Run this endpoint

You can easily run this and other endpoints.

Go to the TomTom API Explorer page.
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.
Review the Response.

▲ Return to top

Request data

HTTPS Method: GET

URL format

https://<baseURL>/search/<versionNumber>/poiCategories.<ext>?key=<Your_API_Key>&[language=<one_of_the_supported_languages>]

curl command format

curl 'https://<baseURL>/search/<versionNumber>/poiCategories.<ext>?key=<Your_API_Key>&[language=<one_of_the_supported_languages>]'

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	Service version. Value: The current value is `2`.
`poiCategories` string	Endpoint name. Value: `poiCategories`
`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`.
Optional headers
Header	Description
`[Accept-Encoding]` string	Enables response compression. Value: `gzip`
Optional parameters
`[language]` string	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). Value: One of the TomTom supported IETF language tags except NGT and NGT-Latn.

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

When requesting JSON (json) output format in the Request URL (ext parameter), the Response has the following structure:

{
  "poiCategories": [
    {
      "id": 7320,
      "name": "Sports Center",
      "childCategoryIds": [
        7320002,
        7320003,
        7320004,
        7320006,
        7320005
      ],
      "synonyms": [
        "Fitness Center",
        "Fitness Centre",
        "Fitness Club",
        "Gym",
        "Gymnasium",
        "Health Club",
        "Indoor Sports",
        "Indoors Sports",
        "Sports Centre",
        "Wellness Club"
      ]
    },
    {
      "id": 7374,
      "name": "Stadium",
      "childCategoryIds": [
        7374002,
        7374009,
        7374012,
        7374003,
        7374010,
        7374005,
        7374008,
        7374011,
        7374006,
        7374014,
        7374013,
        7374007,
        7374004
      ],
      "synonyms": [
        "Arena",
        "Gymnasium",
        "Indoor Arena",
        "Sports Field",
        "Sports Ground",
        "Sports Stadium",
        "Sportsfield",
        "Sportsground",
        "Velodrome"
      ]
    },
    . . .
  ]
}

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

poiCategories[ ] array
Field	Description
`poiCategory` object	Category Tree result list.
poiCategory{ } object
Field	Description
`id` long	Unique ID for the category.
`name` string	Name of the category.
`childCategoryIds` array	List of subcategories ids.
`synonyms` array	List of alternative names of the category.

▲ Return to top

HTTP 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 a result.
`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) is not supported for this Request.
`404/596`	Not Found: The HTTP Request method (GET) 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.

▲ Return to top

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` Value: `type/subtype` is one of: `application/json` `application/javascript` `application/xml`
`Content-Encoding`	If requested by the client, the Search service applies gzip compression to the Responses with the Accept-Encoding header. Value: `gzip`

▲ Return to Top

POI Categories

On this page

Purpose

Run this endpoint

Request data

HTTPS Method: GET

URL format

curl command format

Request parameters

Response data

Response body

Response fields

HTTP Response codes

Response headers

You are here