Getting Started with Yelp Fusion AI API

Welcome to the Yelp Fusion AI API! This guide will walk you through the steps needed to integrate the 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:

1. A Yelp Fusion API account, and an API key for authentication. Refer to Fusion Authentication for further details.
2. Basic knowledge of HTTP requests and JSON.
3. 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.

Receiving a Response

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",
            "city": "New York",
            "state": "NY",
            "country": "US",
            "zip_code": "10001"
          },
          "coordinates": {
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "review_count": 256,
          "rating": 4.7,
          "categories": [
            {
              "alias": "vegan",
              "title": "Vegan"
            },
            {
              "alias": "pizza",
              "title": "Pizza"
            }
          ]
        },
        {
          "id": "fDvGkIlo34J2mNopQrSt",
          "alias": "the-garden-slice",
          "name": "The Garden Slice",
          "url": "https://www.example.com/biz/the-garden-slice",
          "location": {
            "address1": "456 Plant Ln",
            "city": "New York",
            "state": "NY",
            "country": "US",
            "zip_code": "10002"
          },
          "coordinates": {
            "latitude": 40.7139,
            "longitude": -74.0030
          },
          "review_count": 342,
          "rating": 4.3,
          "categories": [
            {
              "alias": "vegan",
              "title": "Vegan"
            },
            {
              "alias": "pizza",
              "title": "Pizza"
            }
          ]
        }
      ]
    }
  ],
  "chat_id": "123"
}

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

Subsequent Requests with chat_id

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": "Do any of them offer gluten-free options?",
  "chat_id": "123"
}

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.

Next Steps

1. 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.
2. 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.
3. Explore Integration Recipes: Check our Integration Recipes to learn how to integrate the Fusion AI API in a framework of your choice.

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!