Return the name and category ID of all categories, or categories which satisfy a filter.
A category describes a type of place, such as "movie theater" or "zoo". The places service has over 1,000 categories (or types) of place. The categories fall into ten general groups: Arts and Entertainment, Business and Professional Services, Community and Government, Dining and Drinking, Events, Health and Medicine, Landmarks and Outdoors, Retail, Sports and Recreation, and Travel and Transportation.
The categories are organized into a hierarchical system where a general category contains many more detailed variations on the parent category. For example: "Travel and Transportation" (Level 1), "Transport Hub" (Level 2), "Airport" (Level 3) and "Airport Terminal" (Level 4). The hierarchy has up to 5 levels of categories.
The table below shows the top-level of categories, along with a selection of level two categories.
The /categories endpoint fetches the latest set of place categories.
The request returns all categories including their label and
category. You should use this endpoint to fetch the latest set of
categories when your app starts up. Each category contains an unique ID
that you can use to perform a near-point or within-extent search.
You can also reduce the list to a subset of categories using the
filter parameter. For example, searching for "coffee" would return
categories including:
-
"Coffee Shop"
-
"Coffee Roaster"
-
"Turkish Coffeehouse"
| Category Label | Category ID | Level 2 |
|---|---|---|
| Arts and Entertainment | 10000 | Amusement Park (10001), Art Gallery (10004), Casino (10008), Exhibit (10016), Movie Theater (10024), Museum (10027), Stadium (10051), Water Park (10055), Zoo (10056), ... |
| Business and Professional Services | 11000 | Construction (11028), Convention Center (11029), Food and Beverage Service (11056), Health and Beauty Service (11061), Industrial Estate (11106), Office (11124), ... |
| Community and Government | 12000 | Education (12009), Organization (12082), Government Building (12064), Community Center (12004), Library (12080), Utility Company (12115), ... |
| Dining and Drinking | 13000 | Bakery (13002), Bar (13003), Cafe, Coffee, and Tea House (13032), Restaurant (13065, ... |
| Event | 14000 | Conference (14001), Convention (14002), Entertainment Event (14003), Marketplace (14009), ... |
| Health and Medicine | 15000 | Dentist (15007), Emergency Service (15008), Hospital (15014), Medical Center (15016), Optometrist (15024), Physician (15027), Veterinarian (15054), ... |
| Landmarks and Outdoors | 16000 | Beach (16003), Structure (16007), Campground (16008), Harbor or Marina (16018), Historic and Protected Site (16020), Monument (16026), Nature Preserve (16028), Park (16032), ... |
| Retail | 17000 | Arts and Crafts Store (17003), Bookstore (17018), Convenience Store (17029), Department Store (17033) |
| Sports and Recreation | 18000 | Athletic Field (18001), Baseball (18002), Basketball (18006), Football (18013), Golf (18016), Gym and Studio (18021), ... |
| Travel and Transportation | 19000 | Bike Rental (19002), Cruise (19005), Electric Vehicle Charging Station (19006), Fuel Station (19007), Lodging (19009), Transport Hub (19030), ... |
Note: Category details are subject to change as new types of places are introduced.
Note: Query parameters are case-sensitive.
Query parameters
| Name | Type | Required | Default value | Description |
|---|---|---|---|---|
| | A text filter that will be used for searching categories. | ||
| | Determines whether icons are returned and the type of icon to use with a place or category. | ||
| | Optional case-sensitive parameter to specify the preferred language to | ||
| | The requested response format - either | ||
| | The authentication token, created from an ArcGIS Location Platform account, with the |
filter
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".
icon
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:
svgcim(Cartographic Information Model)png48 x 48 pixels
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 none (no icon URL will be returned).
- Default
- none
Enumerated values
language
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 (fr-) is unsupported so this falls back
to French fr.
Should the fallback fail, then the service will return category names in
the default language en for English.
Language codes:
- English, default US -
en - French -
fr - German -
de - Japanese -
ja - Portuguese, default Brazil -
pt - Spanish -
es
- Default
- en
Enumerated values
f
The requested response format - either json or pjson (pretty json).
- Default
- json
Enumerated values
token
The authentication token, created from an ArcGIS Location Platform account, with the premium 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 >
Examples
Request
# You can also use wget
curl -X GET https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/categories \
-H 'Accept: application/json'Response
200 Response
{
"categories": [
{
"categoryId": "17119",
"fullLabel": [
[
"Retail",
"Sporting Goods Retail",
"Bicycle Store"
]
],
"parents": [
[
"17117"
]
],
"icon": {
"url": "https://static.arcgis.com/icons/places/Default_Shop_or_Service_15.svg"
}
}
]
}| Status | Meaning | Description | Schema |
|---|---|---|---|
| Details of categories that a | Inline | |
| Invalid query parameters. | ||
| Authentication Error. The API key or token is missing, invalid or expired. | ||
| The required parameter 'token' is valid but does not have permission to access the service. | ||
| Unknown | An error occurred on the server. |
Response details
Status Code 200
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| none | Provides details about a category or type of place. Categories are hierarchical so that you can filter places based on specific categories such as "Provençal Restaurant", or with more generic types such as "Restaurant". A category such as "Provençal Restaurant" includes the details of its more generic parent, such as "French Restaurant". | ||
| none | A unique identifying string for a category. This matches the | ||
| | none | The full list of labels that describe the category, including its more generic parent categories. | |
| | none | The list of parent category Ids for this category. | |
| none | Details of an icon, suitable for depicting this place. To fetch icon details use the | ||
| | none | Url for an icon for this place or category in either |