Category Search

If your search use case only requires POI (Points of Interest) results filtered by category, you may use the Category Search endpoint. This endpoint will only return POI results which are categorized as specified.

To view the list of available categories, see the following section. Click "...Show more" to expand/collapse the list and view its content.

You can easily run this and other endpoints.

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

HTTPS Method: GET

URL format

For ease of viewing and identification:

• Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
• See the following Request parameters section with the Required and Optional parameters tables for these values.

https://<baseURL>/search/<versionNumber>/categorySearch/<query>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&extendedPostalCodesFor=<extendedPostalCodesFor>][&categorySet=<categorySet>][&brandSet=<brandSet>][&connectorSet=<connectorSet>][&fuelSet=<fuelSet>][&view=<view>][&openingHours=<openingHours>][&timeZone=<timeZone>][&mapcodes=<mapcodes>]

curl command format

curl 'https://<baseURL>/search/<versionNumber>/categorySearch/<query>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&extendedPostalCodesFor=<extendedPostalCodesFor>][&categorySet=<categorySet>][&brandSet=<brandSet>][&connectorSet=<connectorSet>][&fuelSet=<fuelSet>][&view=<view>][&openingHours=<openingHours>][&timeZone=<timeZone>][&mapcodes=<mapcodes>]'

▲ Return to top

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.
• The order of request parameters is not important.

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:

{
  "summary": {
    "query": "pizza",
    "queryType": "NON_NEAR",
    "queryTime": 95,
    "numResults": 10,
    "offset": 0,
    "totalResults": 247458,
    "fuzzyLevel": 1,
    "geoBias": {
      "lat": 36.98844,
      "lon": -121.97483
    }
  },
  "results": []
}

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

{
  "type": "POI",
  "id": "g6JpZK84NDAwNjEwMDE4NjUxNDKhY6NVU0GhdqdVbmlmaWVk",
  "score": 5,
  "dist": 0,
  "info": "search:ta:840061001865142-US",
  "poi": {
    "name": "Upper Crust Pizza & Pasta",
    "phone": "+(1)-(831)-4762333",
    "url": "www.uppercrustsc.com/",
    "brands": [
      {
        "name": "Upper Crust"
      }
    ],
    "categorySet": [
      {
        "id": 7315015
      }
    ],
    "categories": [
      "pizza",
      "restaurant"
    ],
    "openingHours": {
      "mode": "NEXT_SEVEN_DAYS",
      "timeRanges": [
        {
          "startTime": {
            "date": "2019-02-05",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-05",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-06",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-06",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-07",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-07",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-08",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-08",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-09",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-09",
            "hour": 21,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-10",
            "hour": 7,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-10",
            "hour": 12,
            "minute": 0
          }
        },
        {
          "startTime": {
            "date": "2019-02-10",
            "hour": 14,
            "minute": 0
          },
          "endTime": {
            "date": "2019-02-10",
            "hour": 21,
            "minute": 0
          }
        }
      ]
    },
    "classifications": [
      {
        "code": "RESTAURANT",
        "names": [
          {
            "nameLocale": "en-US",
            "name": "pizza"
          },
          {
            "nameLocale": "en-US",
            "name": "restaurant"
          }
        ]
      }
    ],
    "timeZone": {
      "ianaId": "Europe/Andorra"
    }
  },
  "address": {
    "streetNumber": "2501",
    "streetName": "Soquel Dr",
    "municipalitySubdivision": "Santa Cruz, Live Oak",
    "municipality": "Santa Cruz, Live Oak",
    "countrySecondarySubdivision": "Santa Cruz",
    "countryTertiarySubdivision": "Santa Cruz",
    "countrySubdivision": "CA",
    "postalCode": "95065",
    "extendedPostalCode": "950652023",
    "countryCode": "US",
    "country": "United States Of America",
    "countryCodeISO3": "USA",
    "freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065",
    "countrySubdivisionName": "California",
    "localName": "Santa Cruz"
  },
  "position": {
    "lat": 36.98844,
    "lon": -121.97483
  },
  "mapcodes":[
    {
      "type":"Local",
      "fullMapcode":"US-CA FS.WRH3",
      "territory":"US-CA",
      "code":"FS.WRH3"
    },
    {
      "type":"International",
      "fullMapcode":"S4ZW4.990V"
    },
    {
      "type":"Alternative",
      "fullMapcode":"US-CA 4349.S8W",
      "territory":"US-CA",
      "code":"4349.S8W"
    },
    {
      "type":"Alternative",
      "fullMapcode":"US-CA JJCH.H9DF",
      "territory":"US-CA",
      "code":"JJCH.H9DF"
    },
    {
      "type":"Alternative",
      "fullMapcode":"USA JJCH.H9DF",
      "territory":"USA",
      "code":"JJCH.H9DF"
    }
  ],
  "viewport": {
    "topLeftPoint": {
      "lat": 36.98934,
      "lon": -121.97596
    },
    "btmRightPoint": {
      "lat": 36.98754,
      "lon": -121.9737
    }
  },
  "entryPoints": [
    {
      "type": "main",
      "position": {
        "lat": 36.98817,
        "lon": -121.97487
      }
    },
    {
      "type": "minor",
      "functions": ["FrontDoor"],
      "position": {
        "lat": 52.30987,
        "lon": 4.76093
      }
    }
  ],
  "dataSources": {
    "chargingAvailability": {
      "id": "442009000132285"
    },
    "geometry": {
      "id": "00004e4c-3100-3c00-0000-0000685e23c7"
    },
    "poiDetails": [
      {
         "id": "45d78933f964a520e1421fe3",
         "sourceName": "Foursquare"
      }
    ]
  }
}

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

▲ Return to top

HTTP Response codes

The following data table contains Response codes signifying successful and failed Requests to an API server.

▲ Return to top

Response headers

The following data 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. If the Tracking-ID header was specified, it is replicated in the Response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: An identifier for the Request.

Error Response

The error Response content type depends on the ext parameter.

Error Response example (JSON)

{
  "errorText":"Error parsing 'language': Language tag 'en-ES' not supported",
  "detailedError":{
    "code":"BadRequest",
    "message":"Error parsing 'language': Language tag 'en-ES' not supported",
    "target":"language"
    },
  "httpStatusCode":"400"
}

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errorText>Error parsing 'language': Language tag 'en-ES' not supported</errorText>
  <detailedError>
    <code>BadRequest</code>
    <message>Error parsing 'language': Language tag 'en-ES' not supported</message>
    <target>language</target>
  </detailedError>
  <httpStatusCode>400</httpStatusCode>
</response>

▲ Return to top

Error Response fields