Skip to content

Find place categories

What is a place category?

A place category is a structure that represents a group of places that are related. Each category contains a categoryId, fullLabel, and parents (IDs). You use categories to help refine the results returned from nearby search and bounding box search.

There are four levels of place categories. The Level 1 category names and IDs include the following:

  • Arts and Entertainment:4d4b7104d754a06370d81259
  • Business and Professional Services:4d4b7105d754a06375d81259
  • Community and Government:63be6904847c3692a84b9b9a
  • Dining and Drinking:63be6904847c3692a84b9bb5
  • Events:4d4b7105d754a06373d81259
  • Health and Medicine:63be6904847c3692a84b9bb9
  • Landmarks and Outdoors:4d4b7105d754a06377d81259
  • Retail:4d4b7105d754a06378d81259
  • Sports and Recreation:4f4528bc4b90abdf24c9de85
  • Travel and Transportation:4d4b7105d754a06379d81259

How to find categories

To search for categories you use the places service /categories and /categories/{categoryId} requests. /categories returns all categories or filters categories that match a string, whereas /categories/{categoryId} returns the details for a specific category ID.

To return place categories or icons in a preferred language, you use the language or icon parameters with either /categories or categories/{categoryId} requests.

The general steps are:

  1. Get the places service category URL.
  2. Set the parameter for the request:
    • filter (categories)
    • categoryId (categories/categoryId)
    • language (categories and categories/categoriesId)
    • icon (categories and categories/Id)
  3. Execute the request.

URL requests

Get category details for a category ID

Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories/<CATEGORY_ID>&token=<ACCESS_TOKEN>&f=pjson

Find categories by filtering by a text string

Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?filter=<TEXT>&token=<ACCESS_TOKEN>&f=pjson

Get categories in a preferred language

Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?language=<LANGUAGE_CODE>&token=<ACCESS_TOKEN>&f=pjson

Return place icons

Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?icon=<ICON_FORMAT>&token=<ACCESS_TOKEN>&f=pjson

Parameters

NameInTypeRequiredDefault valueDescription
filterquerystring

A text filter that will be used for searching categories.

iconquerystringnone

Determines whether icons are returned and the type of icon to use with a place or category.

languagequerystringen

Optional case-sensitive parameter to specify the preferred language to

fquerystringjson

The requested response format - either json or pjson (pretty json).

tokenquerystring

The authentication token, created from an ArcGIS Location Platform account, with the premium:user:places privilege, used to access the Places service.


Code examples

Get all categories

In this example, you use the getCategories operation to return all parent and child categories. You should use this endpoint to fetch the latest set of categories.

  1. Reference the places service.
  2. Set the token parameter to your access token.
Get a list of all categories.

APIs

ArcGIS API for PythonArcGIS API for PythonArcGIS REST JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
import requests

url = "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories"
params = {
    "f": "pjson",
    "token": "ACCESS_TOKEN"
}

response = requests.get(url, params=params)
print(response.text)

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?token=<ACCESS_TOKEN>&f=pjson'

Search for a category by ID

In this example, you search for a category using an ID. The categoryId is 52e81612bcbc57f1066b7a0c, which is the ID for bubble tea shops. The parent categories are cafes, coffee, and tea houses. These fall within the broad category of Dining and Drinking.

Steps

  1. Reference the places service.
  2. Define a category ID.
  3. Set the token parameter to your access token.
Return the category name using its ID.

APIs

ArcGIS API for PythonArcGIS API for PythonArcGIS REST JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
import requests

category_id = "52e81612bcbc57f1066b7a0c"
url = f"https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories/{category_id}"
params = {
    "f": "pjson",
    "token": "YOUR_API_TOKEN"
}

response = requests.get(url, params=params)
print(response.text)

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories/52e81612bcbc57f1066b7a0c?token=<ACCESS_TOKEN>&f=pjson'

Get place categories in Japanese

In this example, you use the language parameter to return all categories in Japanese. If no language is specified, categories are returned in English.

Return the category name using its ID.

Steps

  1. Reference the places service.
  2. Set the language parameter to a preferred language.
  3. Set the token parameter to your access token.

APIs

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { getCategories,searchCategories,getCategory } from "@esri/arcgis-rest-places";

const apiKey = "YOUR_ACCESS_TOKEN";

const authentication = ApiKeyManager.fromKey(apiKey);


arcgisRest.request("https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories",{
    httpMethod: "GET",
    params: {
      token: authentication,
      language: "ja"
    }
  }).then((results)=>{
    console.log(results)
  });

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?language=ja&token=<ACCESS_TOKEN>&f=pjson'

Filter categories by language

In this example, you search for a category in French to return its full label and category ID.

Return the category in French.

Steps

  1. Reference the places service.
  2. Set the filter parameter to the category you want in the language.
  3. Set the language parameter to the preferred language.
  4. Set the token parameter to your access token.

APIs

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { getCategories,searchCategories,getCategory } from "@esri/arcgis-rest-places";

const apiKey = "YOUR_ACCESS_TOKEN";

const authentication = ApiKeyManager.fromKey(apiKey);


arcgisRest.request("https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories",{
    httpMethod: "GET",
    params: {
      filter: "boulangerie",
      token: authentication,
      language: "fr"
    }
  }).then((results)=>{
    console.log(results)
  });

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?filter=boulangerie&language=fr&token=<ACCESS_TOKEN>'

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.