What is a place category?
A place category is a structure that represents a group of places that are related. Each category contains a category
, full
, 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/{category
requests. /categories
returns all categories or filters categories that match a string, whereas /categories/{category
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/{category
requests.
The general steps are:
- Get the places service category URL.
- Set the parameter for the request:
filter
(categories)category
(categories/categoryId)Id language
(categories and categories/categoriesId)icon
(categories and categories/Id)
- Execute the request.
URL requests
Get category details for a category ID
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
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
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?language=<LANGUAGE_CODE>&token=<ACCESS_TOKEN>&f=pjson
Return place icons
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?icon=<ICON_FORMAT>&token=<ACCESS_TOKEN>&f=pjson
Parameters
Name | In | Type | Required | Default value | Description |
---|---|---|---|---|---|
filter | query | string |
| A text filter that will be used for searching categories. | |
icon | query | string | none | Determines whether icons are returned and the type of icon to use with a place or category. | |
language | query | string | en | Optional case-sensitive parameter to specify the preferred language to | |
f | query | string | json | The requested response format - either | |
token | query | string |
| The authentication token, created from an ArcGIS Location Platform account, with the |
Code examples
Get all categories
In this example, you use the get
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.
APIs
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
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 category
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
- Reference the places service.
- Define a category ID.
- Set the token parameter to your access token.
APIs
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
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.
Steps
- Reference the places service.
- Set the
language
parameter to a preferred language. - Set the token parameter to your access token.
APIs
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
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.
Steps
- Reference the places service.
- Set the
filter
parameter to the category you want in the language. - Set the
language
parameter to the preferred language. - Set the token parameter to your access token.
APIs
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
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?filter=boulangerie&language=fr&token=<ACCESS_TOKEN>'