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:10000
Business and Professional Services:11000
Community and Government:12000
Dining and Drinking:13000
Events:14000
Health and Medicine:15000
Landmarks and Outdoors:16000
Retail:17000
Sports and Recreation:18000
Travel and Transportation:19000

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.

The general steps are:

Get the places service category URL.
Set the parameter for the request:
- filter (categories)
- categoryId (categories/categoryId)
Execute the request.

URL requests

Get category details for a category ID.

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

Parameters

Name In Type Required Default value Description

Name	In	Type	Default value	Description
`filter`	query	`string`		A text filter that will be used for searching categories. The text must be at least three characters and will be applied as a partial match. For example, using the filter "off" would return categories using the word "Office" as well as those using the word "Coffee".
`f`	query	`string`	`json`	The requested response format - either `json` or `pjson` (pretty json).
`token`	query	`string`		The authentication token with the `premium:user:places` privilege, used to access the Places service. The `token` parameter can be either an API Key or short-lived token. See ArcGIS security documentation for more information on authenticating with a token or API key. Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme: `Authorization: Bearer <YOUR_TOKEN>` `X-Esri-Authorization: Bearer <YOUR_TOKEN>`

filter

query

string

A text filter that will be used for searching categories.

The text must be at least three characters and will be applied as a partial match. For example, using the filter "off" would return categories using the word "Office" as well as those using the word "Coffee".

f

query

string

json

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

token

query

string

The authentication token with the premium:user:places privilege, used to access the Places service.

The token parameter can be either an API Key or short-lived token. See ArcGIS security documentation for more information on authenticating with a token or API key.

Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme:

Authorization: Bearer <YOUR_TOKEN>
X-Esri-Authorization: Bearer <YOUR_TOKEN>

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.

Reference the places service.
Set the token parameter to your access token.

Get a list of all categories.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS API for Python
Use dark colors for code blocksCopy
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { getCategories,searchCategories,getCategory } from "@esri/arcgis-rest-places";

const apiKey = "YOUR_API_KEY";

const authentication = ApiKeyManager.fromKey(apiKey);


getCategories({
  authentication
}).then((results)=>{
  console.log(JSON.stringify(results,null,2));
});

Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?token=<ACCESS_TOKEN>&f=pjson'

Run in Postman

Use dark colors for code blocks

Copy

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

{
  "categories": [
    {
      "categoryId": "10000",
      "fullLabel": [
        "Arts and Entertainment"
      ],
      "parents": []
    },
    {
      "categoryId": "10001",
      "fullLabel": [
        "Arts and Entertainment",
        "Amusement Park"
      ],
      "parents": [
        "10000"
      ]
    },
    {
      "categoryId": "10002",
      "fullLabel": [
        "Arts and Entertainment",
        "Aquarium"
      ],
      "parents": [
        "10000"
      ]
    }
    // More categories
  ]
}

See full category list

Search for a category by ID

In this example, you search for a category using an ID. The categoryId is 13033, 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

Reference the places service.
Define a category ID.
Set the token parameter to your access token.

Return the category name using its ID.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS API for Python
Use dark colors for code blocksCopy
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { getCategories,searchCategories,getCategory } from "@esri/arcgis-rest-places";

const apiKey = "YOUR_API_KEY";

const authentication = ApiKeyManager.fromKey(apiKey);


getCategory({
  categoryId: "13033",
  authentication
}).then((results)=>{
  console.log(results.fullLabel);
});
Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories/13033?token=<ACCESS_TOKEN>&f=pjson'

Run in Postman

Use dark colors for code blocksCopy
{
  "categoryId": "13033",
  "fullLabel": [
    "Dining and Drinking",
    "Cafes, Coffee, and Tea Houses",
    "Bubble Tea Shop"
  ],
  "parents": [
    "13032"
  ]
}

Tutorials

Find nearby places and details

Find points of interest near a location and get detailed information about them

Find places in a bounding box

Perform a text-based search to find places within a bounding box.

Services

Places service (Beta)

Find and get details about businesses, places, and other POI.

API support

	Category search	Nearby search	Boundary search	Place details
ArcGIS Maps SDK for JavaScript	¹
ArcGIS Maps SDK for .NET
ArcGIS Maps SDK for Kotlin
ArcGIS Maps SDK for Swift
ArcGIS Maps SDK for Java
ArcGIS Maps SDK for Qt
ArcGIS API for Python
ArcGIS REST JS
Esri Leaflet	²	²	²	²
MapLibre GL JS	²	²	²	²
OpenLayers	²	²	²	²
CesiumJS	²	²	²	²

Full supportPartial supportNo support

1. Access via ArcGIS REST JS
2. Access via ArcGIS REST JS.

Tools

Places category finder

Find and select categories to create a JSON array of IDs.

Mapping APIs and location services

Find place categories

Was this page helpful?

Was this page helpful?