Getting Started with Yelp Fusion AI
This guide will walk you through the steps needed to integrate the Yelp Fusion AI API into your application, leveraging best practices for a smooth developer experience. We will cover how to make your first API endpoint request, receive a response, and how to manage session state across subsequent requests.
Introduction
The Yelp Fusion AI API enables developers to build conversational experiences for local business discovery. Whether you're developing a chatbot, integrating into voice assistants or enhancing your app with smart local business recommendations, Fusion AI API provides flexible and power capabilities. The API takes in natural language inquiries and provides natural language responses along with structured data for additional context (e.g., location-based search results & business details).
Prerequisites
Before you start, ensure you have the following:
- A Yelp Fusion API account, and an API key for authentication. Refer to Fusion Authentication for further details.
- Basic knowledge of HTTP requests and JSON.
- A development environment (such as curl, Postman, or a client library in your preferred programming language) to send HTTP requests.
Making Your First API Request
Your first request does not need to include a chat_id
. You can simply send a payload similar to the one below. The API endpoint will handle the conversation state internally and return a chat_id
in the response, which you can use in subsequent calls for that user session.
Example Request (first request):
POST https://api.yelp.com/ai/chat/v2
Authorization: Bearer <Your API Key>
Content-Type: application/json
{
"query": "What's a good vegan pizza place near me?",
"user_context": {
"locale": "en_US",
"latitude": 40.7128,
"longitude": -74.0060
}
}
Explanation
- query: The user’s natural-language request or query.
- user_context: Optional but highly recommended context, such as the user’s locale and/or location coordinates.
A successful response includes the AI’s textual output and may also contain structured data relevant to the response. Below is an example showing a typical response with business recommendations:
{
"response": {
"text": "Here are some top-rated vegan pizza spots near you."
},
"types": [
"business_search"
],
"entities": [
{
"businesses": [
{
"id": "1hGpcZWGQ9vl_AbCdEfG",
"alias": "vegan-pizza-city",
"name": "Vegan Pizza City",
"url": "https://www.example.com/biz/vegan-pizza-city",
"location": {
"address1": "123 Greenway Ave",
"address2": "",
"address3": null,
"city": "New York",
"zip_code": "10001",
"state": "NY",
"country": "US",
"formatted_address": "123 Greenway Ave\nNew York, NY 10001\nUSA"
},
"coordinates": {
"latitude": 40.7128,
"longitude": -74.0060
},
"review_count": 256,
"price": "$$",
"rating": 4.7,
"categories": [
{
"alias": "vegan",
"title": "Vegan"
},
{
"alias": "pizza",
"title": "Pizza"
}
],
"attributes": {
"BusinessUrl": "https://www.veganpizzacity.com",
"AboutThisBizBioPhotoDict": null,
"AboutThisBizBusinessRecommendation": [],
"BusinessAddressAlternate": null,
"BusinessCategorySic": null,
"BusinessMovedFrom": null,
"BusinessNameAlternate": null,
"BusinessOpeningDate": null,
"BusinessTempClosed": null,
"GroupName": null,
"StoreCode": null,
"AboutThisBizBio": null,
"AboutThisBizBioFirstName": null,
"AboutThisBizBioLastName": null,
"AboutThisBizHistory": null,
"AboutThisBizRole": null,
"AboutThisBizSpecialties": "Vegan-friendly pizza with organic ingredients.",
"AboutThisBizYearEstablished": null,
"AcceptedCards": null,
"Alcohol": null,
"Ambience": null,
"BikeParking": null,
"BusinessAcceptsApplePay": null,
"BusinessDisplayUrl": null,
"BusinessMovedTo": null,
"BusinessParking": null,
"BYOB": null,
"BYOBCorkage": null,
"Caters": null,
"Corkage": null,
"DogsAllowed": null,
"DriveThru": null,
"FlowerDelivery": null,
"GenderNeutralRestrooms": null,
"GoodForKids": null,
"GoodForMeal": null,
"HappyHour": null,
"HasTV": null,
"MenuUrl": null,
"NationalProviderIdentifier": null,
"NoiseLevel": null,
"OngoingVigilanteEvent": null,
"OnlineReservations": null,
"Open24Hours": null,
"BusinessOpenToAll": null,
"PlatformDelivery": null,
"PokestopNearby": null,
"RestaurantsCounterService": null,
"RestaurantsDelivery": true,
"RestaurantsGoodForGroups": null,
"RestaurantsPriceRange": null,
"RestaurantsPriceRange2": null,
"RestaurantsReservations": false,
"RestaurantsTableService": null,
"RestaurantsTakeOut": true,
"WaitlistReservation": null,
"WheelchairAccessible": true,
"WiFi": null
},
"phone": "+12125551234",
"summaries": {
"short": "A top-rated vegan pizza spot in New York.",
"medium": "Vegan Pizza City offers a variety of plant-based pizzas with fresh, organic ingredients.",
"long": "Vegan Pizza City is a highly-rated pizzeria specializing in vegan-friendly options. Customers love the fresh ingredients, organic toppings, and delicious flavors. The restaurant offers both delivery and takeout services, making it a convenient choice for plant-based pizza lovers."
},
"contextual_info": {
"summary": "A popular vegan pizza spot known for its organic ingredients and delicious flavors. Customers appreciate the fresh toppings and excellent service.",
"review_snippets": [],
"business_hours": [
{
"day_of_week": "Monday",
"business_hours": [
{
"open_time": "2025-03-10 11:00:00",
"close_time": "2025-03-10 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Tuesday",
"business_hours": [
{
"open_time": "2025-03-11 11:00:00",
"close_time": "2025-03-11 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Wednesday",
"business_hours": [
{
"open_time": "2025-03-12 11:00:00",
"close_time": "2025-03-12 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Thursday",
"business_hours": [
{
"open_time": "2025-03-13 11:00:00",
"close_time": "2025-03-13 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Friday",
"business_hours": [
{
"open_time": "2025-03-14 11:00:00",
"close_time": "2025-03-15 00:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Saturday",
"business_hours": [
{
"open_time": "2025-03-15 11:00:00",
"close_time": "2025-03-16 00:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Sunday",
"business_hours": [
{
"open_time": "2025-03-16 12:00:00",
"close_time": "2025-03-16 21:00:00"
}
],
"special_hours_applied": false
}
],
"photos": [
{
"original_url": "https://s3-media0.fl.yelpcdn.com/bphoto/sample1/o.jpg"
},
{
"original_url": "https://s3-media0.fl.yelpcdn.com/bphoto/sample2/o.jpg"
}
],
"review_snippet": "The [[HIGHLIGHT]]vegan pizza[[ENDHIGHLIGHT]] here is amazing! Fresh ingredients and great flavors."
}
}
]
}
],
"chat_id": "qs_MyS18PQJms3p5xdeVpQ"
}
Important Fields
- response.text: The AI’s primary response in natural language.
- types: Contextual tags indicating the nature of the response (here,
"business_search"
). - entities: Structured data containing relevant entities. In the example, this includes an array of businesses.
- contextual_info.summary: A contextually relevant, AI-generated summary of the business based on the user's query.
- summaries: Provides different levels of detail about the business, including a short, medium, and long description. This allows developers to choose the appropriate level of detail depending on their use case, such as quick previews for chatbots or full descriptions for business profiles.
- review_snippet: A highlighted snippet from a user review.
- chat_id: The identifier for your conversation. Use this in further requests to continue the same conversation context.
Visit the Fusion AI API Reference page for detailed information on the fields returned by the API endpoint.
Example 2: Business Question and Response
After you complete your first request, the response’s chat_id
should be included in each subsequent request for that user's session. This helps the Fusion AI API maintain context and continuity across multiple queries.
Example Request (subsequent requests):
POST https://api.yelp.com/ai/chat/v2
Authorization: Bearer <Your API Key>
Content-Type: application/json
{
"query": "What are their opening hours?",
"chat_id": "qs_MyS18PQJms3p5xdeVpQ"
}
Providing the chat_id
into your requests ensures the AI knows you're continuing the same conversation. This way, the system can provide an informed response based on your prior interactions.
Example Response:
{
"response": {
"text": "Vegan Pizza City is open from 11:00 AM to 10:00 PM on weekdays and 11:00 AM to midnight on weekends."
},
"types": [
"business_question"
],
"entities": [
{
"businesses": [
{
"id": "1hGpcZWGQ9vl_AbCdEfG",
"alias": "vegan-pizza-city",
"name": "Vegan Pizza City",
"url": "https://www.example.com/biz/vegan-pizza-city ",
"location": {
"address1": "123 Greenway Ave",
"address2": "",
"address3": null,
"city": "New York",
"state": "NY",
"country": "US",
"zip_code": "10001",
"formatted_address": "123 Greenway Ave\nNew York, NY 10001\nUSA"
},
"coordinates": {
"latitude": 40.7128,
"longitude": -74.006
},
"review_count": 256,
"price": "$$",
"rating": 4.7,
"categories": [
{
"alias": "vegan",
"title": "Vegan"
},
{
"alias": "pizza",
"title": "Pizza"
}
],
"attributes": {
"BusinessUrl": "https://www.veganpizzacity.com ",
"AboutThisBizBioPhotoDict": null,
"AboutThisBizBusinessRecommendation": [],
"BusinessAddressAlternate": null,
"BusinessCategorySic": null,
"BusinessMovedFrom": null,
"BusinessNameAlternate": null,
"BusinessOpeningDate": null,
"BusinessTempClosed": null,
"GroupName": null,
"StoreCode": null,
"AboutThisBizBio": null,
"AboutThisBizBioFirstName": null,
"AboutThisBizBioLastName": null,
"AboutThisBizHistory": null,
"AboutThisBizRole": null,
"AboutThisBizSpecialties": "Vegan-friendly pizza with organic ingredients.",
"AboutThisBizYearEstablished": null,
"AcceptedCards": null,
"Alcohol": null,
"Ambience": null,
"BikeParking": null,
"BusinessAcceptsApplePay": null,
"BusinessDisplayUrl": null,
"BusinessMovedTo": null,
"BusinessParking": null,
"BYOB": null,
"BYOBCorkage": null,
"Caters": null,
"Corkage": null,
"DogsAllowed": null,
"DriveThru": null,
"FlowerDelivery": null,
"GenderNeutralRestrooms": null,
"GoodForKids": null,
"GoodForMeal": null,
"HappyHour": null,
"HasTV": null,
"MenuUrl": null,
"NationalProviderIdentifier": null,
"NoiseLevel": null,
"OngoingVigilanteEvent": null,
"OnlineReservations": null,
"Open24Hours": null,
"BusinessOpenToAll": null,
"PlatformDelivery": null,
"PokestopNearby": null,
"RestaurantsCounterService": null,
"RestaurantsDelivery": true,
"RestaurantsGoodForGroups": null,
"RestaurantsPriceRange": null,
"RestaurantsPriceRange2": null,
"RestaurantsReservations": false,
"RestaurantsTableService": null,
"RestaurantsTakeOut": true,
"WaitlistReservation": null,
"WheelchairAccessible": true,
"WiFi": null
},
"phone": "+12125551234",
"summaries": {
"short": "A top-rated vegan pizza spot in New York.",
"medium": "Vegan Pizza City offers a variety of plant-based pizzas with fresh, organic ingredients.",
"long": "Vegan Pizza City is a highly-rated pizzeria specializing in vegan-friendly options. Customers love the fresh ingredients, organic toppings, and delicious flavors. The restaurant offers both delivery and takeout services, making it a convenient choice for plant-based pizza lovers."
},
"contextual_info": {
"summary": "A popular vegan pizza spot known for its organic ingredients and delicious flavors. Customers appreciate the fresh toppings and excellent service.",
"review_snippets": [],
"business_hours": [
{
"day_of_week": "Monday",
"business_hours": [
{
"open_time": "2025-03-10 11:00:00",
"close_time": "2025-03-10 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Tuesday",
"business_hours": [
{
"open_time": "2025-03-11 11:00:00",
"close_time": "2025-03-11 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Wednesday",
"business_hours": [
{
"open_time": "2025-03-12 11:00:00",
"close_time": "2025-03-12 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Thursday",
"business_hours": [
{
"open_time": "2025-03-13 11:00:00",
"close_time": "2025-03-13 22:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Friday",
"business_hours": [
{
"open_time": "2025-03-14 11:00:00",
"close_time": "2025-03-15 00:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Saturday",
"business_hours": [
{
"open_time": "2025-03-15 11:00:00",
"close_time": "2025-03-16 00:00:00"
}
],
"special_hours_applied": false
},
{
"day_of_week": "Sunday",
"business_hours": [
{
"open_time": "2025-03-16 12:00:00",
"close_time": "2025-03-16 21:00:00"
}
],
"special_hours_applied": false
}
],
"photos": [
{
"original_url": "https://s3-media0.fl.yelpcdn.com/bphoto/sample1/o.jpg "
},
{
"original_url": "https://s3-media0.fl.yelpcdn.com/bphoto/sample2/o.jpg "
}
],
"review_snippet": "The [[HIGHLIGHT]]vegan pizza[[ENDHIGHLIGHT]] here is amazing! Fresh ingredients and great flavors."
}
}
]
}
],
"chat_id": "qs_MyS18PQJms3p5xdeVpQ"
}
Important Fields
- response.text: The natural language summary about Vegan Pizza City’s hours.
- types: Indicates that the response type is business_question.
- entities.businesses[].contextual_info.business_hours: Holds the detailed schedule (day_of_week, open_time, close_time).
- special_hours_applied: A boolean indicating whether any special hours (like holidays) are active.
- chat_id: Maintains continuity in the conversation across multiple queries.
Visit the Fusion AI API Reference page for detailed information on the fields returned by the API endpoint.
Next Steps
- Error Handling: Familiarize yourself with the API error codes to gracefully handle issues like invalid requests or rate limits. For comprehensive details on each potential error code, refer to the Fusion AI API Reference page.
- Explore Current Capabilities: Besides local business search & recommendations, the Fusion AI API supports additional capabilities. Refer to the Current Capabilities & Limitations section for more information.
- Explore Integration Recipes: Check our Integration Recipes to learn how to integrate the Fusion AI API in a framework of your choice.
- Explore Yelp's Agentic AI API: Check out our Agentic AI API documentation for more advanced AI capabilities that can help you build sophisticated conversational applications and agentic experiences with Yelp's local business data.
Questions or Feedback?
If you have any questions, run into issues, or would like to suggest improvements, please reach out through our Support page. We’re here to help!
That’s it! With these basics covered, you’re ready to build conversational experiences powered by Yelp's Fusion AI API. Happy building!
Updated 12 days ago