---
agentTools:
projectIndex: https://docs.developer.yelp.com/llms.txt
---
# Category Details
This endpoint returns detailed information about the Yelp category specified by a Yelp category alias. The alias for each category can be found either by using the /v3/categories endpoint, or the category list.
> 📘
>
> This endpoint is part of Yelp Places API, visit [Yelp Places API](https://docs.developer.yelp.com/docs/fusion-intro) to learn more.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Categories",
"version": "1.0"
},
"servers": [
{
"url": "https://api.yelp.com"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.\n\nExample: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.\n\nYou can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).\n"
}
}
},
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v3/categories": {
"get": {
"summary": "All Categories",
"tags": [
"Categories"
],
"description": "This endpoint returns all Yelp business categories across all locales by default.\nInclude the \"locale\" parameter to filter to only those categories available for a particular locale, and translate/localize the names of those categories.\n",
"operationId": "v3_all_categories",
"parameters": [
{
"in": "query",
"required": false,
"description": "Specify the locale to filter the categories returned to only those available in that locale, and to translate the names of the categories appropriately.\nSee the list of supported locales. If not included, all categories across all locales will be returned and the category names will be in English.\n",
"name": "locale",
"schema": {
"type": "string",
"pattern": "^[a-z]{2,3}_[A-Z]{2}$"
}
}
],
"responses": {
"200": {
"description": "One or more categories were returned.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"categories"
],
"properties": {
"categories": {
"type": "array",
"description": "List of categories",
"items": {
"$ref": "#/paths/~1v3~1categories~1{alias}/get/responses/200/content/application~1json/schema/properties/category"
}
}
}
},
"examples": {
"Result": {
"value": {
"categories": [
{
"alias": "acaibowls",
"title": "Acai Bowls",
"parent_aliases": [
"food"
],
"country_whitelist": [],
"country_blacklist": [
"AR",
"CL"
]
},
{
"alias": "arts",
"title": "Arts & Entertainment",
"parent_aliases": [],
"country_whitelist": [],
"country_blacklist": []
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request. Message varies depending on failure scenario",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"description"
],
"properties": {
"code": {
"type": "string",
"description": "The error code."
},
"description": {
"type": "string",
"description": "The description of the error."
}
}
}
}
},
"examples": {
"Invalid Request": {
"value": {
"error": {
"code": "INVALID_REQUEST",
"description": "Invalid Request"
}
}
}
}
}
}
},
"401": {
"description": "The API key has either expired or doesn't have the required scopes to query this endpoint.\n\n| code | description |\n| ------------- | ------------- |\n| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |\n| TOKEN_INVALID | Invalid API key or authorization header. |\n",
"content": {
"application/json": {
"examples": {
"Unauthorized": {
"value": {
"error": {
"code": "UNAUTHORIZED_API_KEY",
"description": "The API key provided is not currently able to query this endpoint."
}
}
},
"Invalid Token": {
"value": {
"error": {
"code": "TOKEN_INVALID",
"description": "Invalid API key or authorization header."
}
}
}
},
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
}
}
}
},
"403": {
"description": "The API key provided is not currently able to query this endpoint.",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
},
"examples": {
"Authorization Error": {
"value": {
"error": {
"code": "AUTHORIZATION_ERROR",
"description": "Authorization Error"
}
}
}
}
}
}
},
"404": {
"description": "Resource Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
},
"examples": {
"Resource Not Found": {
"value": {
"error": {
"code": "NOT_FOUND",
"description": "Resource Not Found"
}
}
}
}
}
}
},
"413": {
"description": "The length of the request exceeded the maximum allowed",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
},
"examples": {
"Payload Too Large": {
"value": {
"error": {
"code": "PAYLOAD_TOO_LARGE",
"description": "Payload Too Large"
}
}
}
}
}
}
},
"429": {
"description": "You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.",
"content": {
"application/json": {
"examples": {
"Rate limited": {
"value": {
"error": {
"code": "TOO_MANY_REQUESTS_PER_SECOND",
"description": "You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries."
}
}
}
},
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"Internal Server Error": {
"value": {
"error": {
"code": "INTERNAL_ERROR",
"description": "Something went wrong internally, please try again later."
}
}
}
},
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1v3~1categories/get/responses/400/content/application~1json/schema"
},
"examples": {
"Service Unavailable": {
"value": {
"error": {
"code": "SERVICE_UNAVAILABLE",
"description": "Service Unavailable"
}
}
}
}
}
}
}
}
}
},
"/v3/categories/{alias}": {
"get": {
"summary": "Category Details",
"tags": [
"Categories"
],
"description": "This endpoint returns detailed information about the Yelp category specified by a Yelp category alias. The alias for each category can be found either by using the /v3/categories endpoint, or the category list.\n",
"operationId": "v3_categories",
"parameters": [
{
"name": "alias",
"in": "path",
"description": "Category Alias",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/paths/~1v3~1categories/get/parameters/0",
"in": "query",
"required": false
}
],
"responses": {
"200": {
"description": "A category was returned.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"category"
],
"properties": {
"category": {
"type": "object",
"required": [
"alias",
"title"
],
"properties": {
"alias": {
"type": "string",
"description": "Category alias"
},
"title": {
"type": "string",
"description": "Title of this category"
},
"parent_aliases": {
"type": "array",
"description": "List of aliases of parent categories",
"items": {
"type": "string"
}
},
"country_whitelist": {
"type": "array",
"description": "Countries for which this category is whitelisted",
"items": {
"type": "string"
}
},
"country_blacklist": {
"type": "array",
"description": "Countries for which this category is blacklisted",
"items": {
"type": "string"
}
}
}
}
}
},
"examples": {
"Result": {
"value": {
"category": {
"alias": "3dprinting",
"title": "3D Printing",
"parent_aliases": [
"localservices"
],
"country_whitelist": [],
"country_blacklist": []
}
}
}
}
}
}
},
"400": {
"$ref": "#/paths/~1v3~1categories/get/responses/400"
},
"401": {
"$ref": "#/paths/~1v3~1categories/get/responses/401"
},
"403": {
"description": "The API key provided is not currently able to query this endpoint.",
"$ref": "#/paths/~1v3~1categories/get/responses/403"
},
"404": {
"$ref": "#/paths/~1v3~1categories/get/responses/404"
},
"413": {
"$ref": "#/paths/~1v3~1categories/get/responses/413"
},
"429": {
"$ref": "#/paths/~1v3~1categories/get/responses/429"
},
"500": {
"$ref": "#/paths/~1v3~1categories/get/responses/500"
},
"503": {
"$ref": "#/paths/~1v3~1categories/get/responses/503"
}
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": false,
"samples-enabled": true
},
"_id": {
"buffer": {
"0": 99,
"1": 114,
"2": 63,
"3": 75,
"4": 242,
"5": 23,
"6": 100,
"7": 0,
"8": 59,
"9": 216,
"10": 186,
"11": 238
}
}
}
```