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:
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/{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=pjsonFind 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=pjsonGet categories in a preffered language
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?language=<LANGUAGE_CODE>&token=<ACCESS_TOKEN>&f=pjsonReturn place icons
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories?icon=<ICON_FORMAT>&token=<ACCESS_TOKEN>&f=pjsonParameters
| Name | In | Type | Required | Default value | Description |
|---|---|---|---|---|---|
| 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". | ||
| query | string | none | Determines whether icons are returned and the type of icon to use with a place or category.
Use this parameter to define the type of icon URL for a given place or category. Place icons are available in the following formats:
The SVG and CIM symbols default to 15 x 15 pixels but can be scaled smoothly for display in larger UI elements or to emphasize these features on a map. The PNG icons are provided as 48 x 48 pixels but for map display the recommended size is 16 x 16 pixels. The default is | ||
| query | string | en | Optional case-sensitive parameter to specify the preferred language to use for category names. This query parameter uses language codes to specify the preferred language. If not set, or if no translation is available, the default behavior is to return category names in English. The language codes use the CLDR (Common Locale Data Repository) format string that uses a two letter language code (e.g. "fr" for French) optionally followed by a two letter country code (e.g. "fr-CA" for French in Canada). If an unsupported language code is used, then the service will attempt
to fall-back to the closest available language. This is done by
stripping regional and extension subtags to find a known language code.
For example, French Canadian ( Should the fallback fail, then the service will return category names in
the default language Language codes:
| ||
| query | string | json | The requested response format - either | ||
| query | string | | The authentication token, created from an ArcGIS Location Platform account, with the The Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme:
|
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 { 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);
getCategories({
authentication
}).then((results)=>{
console.log(JSON.stringify(results,null,2));
});
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 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.
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);
getCategory({
categoryId: "13033",
authentication
}).then((results)=>{
console.log(results.fullLabel);
});
REST API
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories/13033?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 specifed, categories are returned in English.
Steps
- Reference the places service.
- Set the
languageparameter 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
filterparameter to the category you want in the language. - Set the
languageparameter 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>'