--- title: "Yelp AI API (Search & Chat)" method: POST path: "/ai/chat/v2" tags: ["Businesses"] --- # Yelp AI API (Search & Chat) `POST /ai/chat/v2` The Yelp AI API endpoint brings conversational intelligence to your applications, enabling users to ask natural language questions and receive real-time, contextually relevant answers powered by Yelp’s latest business data and reviews. **Yelp AI API Features** - **Next generation search & discovery** - Search with natural language, discover, and connect with contextually relevant businesses. - **Multi-turn conversations** - Support back-and-forth interactions and refine queries with follow-up questions. - **Direct business queries** - Ask targeted questions about businesses without needing to perform a prior search. - **Conversational restaurant reservations** - Explore availability and book a table at restaurants through natural language interactions. (Please note that this feature is available on request only. To enable reservations, please contact us.) - **Instant quotes for home services** - Simply describe the service you need (like β€œI need quotes for fixing a leaking faucet”), and Yelp AI API instantly connects you with top local pros, so you receive multiple quotes from the best professionals for your job. (Currently in beta and not yet publicly available.) πŸš€ **Try it now** - Test Yelp AI API for free in our **playground** and see real-time responses in action. πŸ› οΈ For a detailed, step-by-step guide on integrating this endpoint into your application, check out the **Getting Started with Yelp AI API guide**. ## Request body - object β€” This object captures the user’s request to the Fusion AI Chat endpoint. It includes the conversational query, optional user context for more relevant results, and an optional chat_id for session continuity. - `query` string, required β€” β€’ Natural language text for querying Yelp-specific information. β€’ Accepts any prompt related to Yelp businesses, such as β€œCan you find a Thai restaurant near me?” β€’ This should be plain text (no special formatting needed). - `chat_id` string β€” β€’ Uniquely identifies the current conversation (chat session). β€’ For the first request, set this to null or omit it; the API will respond with a new chat_id. β€’ Use the returned chat_id on subsequent requests to continue the same conversation. β€’ If omitted on subsequent requests, a new conversation is started. β€’ If an invalid chat_id is provided, the request will fail. - `user_context` object β€” Contains optional location data (latitude and longitude) that can help the AI tailor results to a user’s location. If not provided and a location-based query is asked, the system may prompt the user to specify a location. - `latitude` number, float β€” β€’ User’s approximate latitude. β€’ If provided, it helps return more location-specific results. β€’ Otherwise, the system may ask for location details if needed (e.g., for searches). - `longitude` number, float β€” β€’ User's approximate longitude. β€’ If provided, it helps return more location-specific results. β€’ Otherwise, the system may ask for location details if needed. - `request_context` object β€” Contains optional settings that control how the API processes the request. These settings affect the response format and content generation behavior. - `skip_text_generation` boolean β€” β€’ When set to true, skips LLM text generation and returns only structured data. β€’ The response will contain empty text and tags, but all structured data (businesses, entities, types) will still be returned. β€’ Useful for clients that only need structured data and want to reduce latency. ## Response `200` A successful response - object β€” Represents the AI Chat response returned by Yelp’s Fusion AI endpoint. It includes a conversational response, any structured data (entities) relevant to the query, and a chat_id for tracking the user session. - `chat_id` string, required β€” A unique Yelp-generated Chat ID that ties all requests to a specific conversation. β€’ This remains the same if the user provided a valid chat_id in the request. β€’ It is static throughout one session. - `response` object β€” Contains a contextually relevant response message for the user’s query: β€’ Might be one or multiple sentences. β€’ May include follow-up questions if needed (e.g. to request user’s location). - `text` string β€” The AI-generated textual response to the user’s query. For example, it may contain an answer, an additional prompt, or instructions to refine the query. - `tags` object[] β€” Additional metadata tags that provide context about the response. These tags can be used to enrich the response or display additional information. - `start` number β€” The start index of a particular style/information. e.g. highlight/business name/etc - `end` number β€” The end index of a particular style/information. e.g. highlight/business name/etc - `tag_type` string β€” The type of metadata tag. Valid values: β€’ highlight - indicates a highlighted text in the response. β€’ business - indicates the name of a business mentioned in the response. - `meta` object β€” Additional metadata that can provide more context about the tag. This can include information like business ID, category, or other relevant details. - `types` string[] β€” A list of response categories indicating the nature of the answer. Valid values: β€’ business_search β€’ business_question β€’ clarification β€’ unsupported β€’ confirmation - `entities` object[] β€” Structured data corresponding to the businesses or other entities referenced in the AI response. If the response does not reference specific businesses, this array may be empty. - `businesses` object[] β€” A list of Yelp business objects that the AI response refers to. The data may be partially or fully populated depending on the nature of the query. - `id` string, required - `name` string, required β€” Name of this business. - `alias` string β€” Unique Yelp alias of this business. Can contain unicode characters. Example: 'yelp-san-francisco'. Also see What's the difference between the Yelp business ID and business alias? - `url` string β€” URL for business page on Yelp. - `location` object, required - `address1` unknown - `address2` unknown - `address3` unknown - `city` unknown - `state` unknown - `zip_code` unknown - `country` unknown - `coordinates` object, required β€” Coordinates of this business. - `latitude` number β€” Latitude position on map. - `longitude` number β€” Longitude position on map. - `review_count` integer β€” Number of reviews for this business. - `price` string β€” Price level of the business. Value is one of *$*, *$$*, *$$$* or *$$$$*. - `rating` number, double β€” Rating for this business (value ranges from 1, 1.5, ... 4.5, 5). - `categories` object[], required β€” A list of Yelp Categories - `alias` string β€” Alias of a category, when searching for business in certain categories, use alias rather than the title. - `title` string β€” Title of a category for display purpose. - `attributes` object, required β€” Various features or facilities provided by the business. - `phone` string β€” Phone number of the business. - `summaries` object, required β€” AI-generated textual summaries for this business. These are not specific to the user’s query. - `short` string β€” A short, typically single-sentence summary. - `medium` string β€” A medium-length summary (2–3 sentences). - `long` string β€” A more detailed paragraph-length summary. - `contextual_info` object β€” Additional context relevant to the user’s specific query, if applicable. - `summary` string β€” A contextual summary relevant to the user’s query. May be null if not applicable. - `review_snippets` object[] β€” Automatically selected short excerpts from user reviews, based on the query. - `review_id` string, required - `comment` string, required - `rating` number, double, required - `timestamp` integer - `business_hours` object[] - `day_of_week` string, required - `business_hours` object[], required - `open_time` string, required - `close_time` string, required - `photos` object[] β€” A list of Yelp-hosted photo objects. - `original_url` string, required - `review_snippet` string β€” A single representative snippet from a review. - `accepts_reservations_through_yelp` boolean β€” Whether the business accepts reservations through Yelp - `reservation_availability` object β€” Contains reservation availability information for the business. This field is only present if the business accepts reservations through Yelp. - `openings` object[], required β€” List of available reservation slots. - `date` string, date, required β€” Date in YYYY-MM-DD format - `slots` object[], required β€” Available reservation slots for this date - … - `request_a_quote_survey` object β€” Request a Quote survey information when the user is in a quote request flow. This field will be populated when the AI determines the user wants to request quotes from businesses for services. - `job_display_name` string, required β€” Display name for the job type - `status` 'in_progress' | 'awaiting_user_info' | 'awaiting_confirmation' | 'awaiting_submit_to_nearby' | 'submitted' | 'failed', required β€” Status of the Request a Quote survey - `questions` object[], required β€” List of survey questions - `text` string, required β€” The question text - `available_choices` string[] β€” List of available choices for the question - `only_accepts_choices` boolean β€” Whether the question only accepts predefined choices - `is_multi_select` boolean β€” Whether multiple choices can be selected - `required` boolean β€” Whether the question is required - `user_response` string[] β€” User's response to the question - `user_info` object - `first_name` string - `last_name` string - `email` string - `phone` string - `zip_code` string - `requested_biz_ids` string[] β€” List of encrypted business IDs requested for quotes - `num_matched_businesses` integer β€” Number of businesses matched for this request - `submit_to_nearby_businesses` boolean β€” Whether to submit quote request to nearby businesses ## Other responses - `400` β€” Bad Request. Message varies depending on failure scenario - `401` β€” The API key has either expired or doesn't have the required scopes to query this endpoint. | code | description | | ------------- | ------------- | | UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. | | TOKEN_INVALID | Invalid API key or authorization header. | - `403` β€” unresolved $ref - `404` β€” Resource Not Found - `413` β€” The length of the request exceeded the maximum allowed - `429` β€” 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. - `500` β€” Internal Server Error - `503` β€” Service Unavailable --- [API](https://skmtc.net/yelp/apis/businesses.md) Β· [All operations](https://skmtc.net/yelp/apis/businesses/llms.txt) Β· [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yelp/businesses/revisions/d3f744f55ed7/schema)