/categories

Click to copy

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 categoryId. 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 LabelCategory IDLevel 2
Arts and Entertainment10000Amusement Park (10001), Art Gallery (10004), Casino (10008), Exhibit (10016), Movie Theater (10024), Museum (10027), Stadium (10051), Water Park (10055), Zoo (10056), ...
Business and Professional Services11000Construction (11028), Convention Center (11029), Food and Beverage Service (11056), Health and Beauty Service (11061), Industrial Estate (11106), Office (11124), ...
Community and Government12000Education (12009), Organization (12082), Government Building (12064), Community Center (12004), Library (12080), Utility Company (12115), ...
Dining and Drinking13000Bakery (13002), Bar (13003), Cafe, Coffee, and Tea House (13032), Restaurant (13065, ...
Event14000Conference (14001), Convention (14002), Entertainment Event (14003), Marketplace (14009), ...
Health and Medicine15000Dentist (15007), Emergency Service (15008), Hospital (15014), Medical Center (15016), Optometrist (15024), Physician (15027), Veterinarian (15054), ...
Landmarks and Outdoors16000Beach (16003), Structure (16007), Campground (16008), Harbor or Marina (16018), Historic and Protected Site (16020), Monument (16026), Nature Preserve (16028), Park (16032), ...
Retail17000Arts and Crafts Store (17003), Bookstore (17018), Convenience Store (17029), Department Store (17033)
Sports and Recreation18000Athletic Field (18001), Baseball (18002), Basketball (18006), Football (18013), Golf (18016), Gym and Studio (18021), ...
Travel and Transportation19000Bike 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

NameTypeRequiredDefault valueDescription

string

A text filter that will be used for searching categories.

string

none

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

string

en

Optional case-sensitive parameter to specify the preferred language to

string

json

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

string

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

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.

example icon

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 none (no icon URL will be returned).

Default
none
Enumerated values
none
Click to copy
svg
Click to copy
png
Click to copy
cim
Click to copy

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-CA) 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
en
Click to copy
es
Click to copy
de
Click to copy
fr
Click to copy
ja
Click to copy
pt
Click to copy

f

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

Default
json
Enumerated values
json
Click to copy
pjson
Click to copy

token

The authentication token, created from an ArcGIS Location Platform account, 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>

Examples

Request

Use dark colors for code blocksCopy
1
2
3
# 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

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
{
  "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"
      }
    }
  ]
}
StatusMeaningDescriptionSchema

200

OK

Details of categories that a Place can belong to.

Inline

400

Bad Request

Invalid query parameters.

Error

401

Unauthorized

Authentication Error. The API key or token is missing, invalid or expired.

Error

403

Forbidden

The required parameter 'token' is valid but does not have permission to access the service.

Error

5XX

Unknown

An error occurred on the server.

Error

Response details

Status Code 200

NameTypeRequiredRestrictionsDescription

categories

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".

categoryId

none

A unique identifying string for a category.

This matches the categoryId of a place's category property.

fullLabel

[string]

none

The full list of labels that describe the category, including its more generic parent categories.

parents

[string]

none

The list of parent category Ids for this category.

icon

none

Details of an icon, suitable for depicting this place.

To fetch icon details use the icon query parameter.

url

string(url)

none

Url for an icon for this place or category in either svg, cim or png format.

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