Gathering useful data about businesses and events in an area can be difficult. There are a variety of APIs that include useful data, including the Google Places API. Another popular, and valuable API that offers similar information is provided by Yelp.

The Yelp API can be useful for web developers building apps on top of the Yelp platform, as well as data scientists looking to use the large location dataset. In this post, we'll explore some useful parts of the Yelp API. Our examples will be focused on javascript developers, but they are all common HTTP requests so the concepts should carry over to any language.

To get started, let's first look at the two API formats offered by Yelp.

The two main API formats

Yelp offers two main entry points into their data. Their REST API, Yelp Fusion and a newer GraphQL API. Both offer the same level of access, so it is up to you which you prefer to use. It's worth mentioning that the GraphQL version is considered "experimental". In our usage, we've found a few small quirks, such as localization, but otherwise it is full-featured. In this post, we'll show examples for calls to the REST API and queries to the GraphQL endpoint. If you want to use the GraphQL API, you'll need to join the Developer Beta program. This can be done from the "Manage App" page, as well as any of the links in the documentation for the GraphQL API.

The Fusion documentation offers a full list of endpoints, as well as the parameters that can be used.

The GraphQL API offers query examples for all of the available queries, and it also includes an interactive console (built on top of GraphiQL).

Yelp also offers a variety of private APIs. These include the Transactions, Advertising, and Knowledge APIs. To request access, you'll need to get in touch with Yelp directly (through the forms on each API's page).

Create an app and find your API key

To get started building with the Yelp API, you'll need an account with access. Do this by creating a Yelp account from the developer portal. You can also use your existing Yelp user account.

Select the Manage App section of the developer portal.

Fill in the required fields, save the new application, and you'll be provided with your Yelp API key and client ID. The client ID is no longer required. Make sure to keep your API key, as you'll need it shortly.

You can return to this page at any time to view your key, reset your API key, view usage, and make any changes to your application settings. This is also the page where you can join the developer beta to enable experimental features (like the GraphQL API).

How to connect to the Yelp API

For all of our examples, we'll be using Node.js and Axios. If you are following along, make sure to npm install axios into your project and require it at the top. You'll also need your API key from the previous section.

Authentication is done by sending an Authorization header with a value of Bearer YOUR_API_KEY. The rest API uses the URL of https://api.yelp.com/v3 followed by the endpoint you wish to request. All REST endpoints are read-only and accept GET requests.

The GraphQL API accepts the same header for authentication, and uses https://api.yelp.com/v3/graphql as its URL. It accepts POST requests and expects a payload of query { YOUR QUERY }.

For all of our examples, we'll use the following Node.js code.

For the REST API, calls will look like this:

const axios = require("axios")

let API_KEY = "YOUR_API_KEY"

// REST
let yelpREST = axios.create({
  baseURL: "https://api.yelp.com/v3/",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-type": "application/json",
  },
})

yelpREST(ENDPOINT, { params: { key: value } }).then(({ data }) => {
  // Do something with the data
})

For the GraphQL API, calls will look like this:

// GraphQL
let yelpGQL = axios.create({
  url: "https://api.yelp.com/v3/graphql",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-type": "application/json",
  },
  method: "POST",
})

yelpGQL({ data: JSON.stringify({ query: `{ YOUR QUERY }` }) }).then(
  ({ data }) => {
    // Do something with the data
  }
)

We'll show just the necessary parts to change from the above code. Feel free to use the library or language of your choice for making requests, as the concepts should carry over.

Things you can do

Now that you know how to connect to the Yelp API, let's look at some things you can do.

Finding business details

The best place to start is searching for businesses. You can find a full list of business related endpoints in the documentation. The most common will likely be /search.

To search for a business, you need to provide a search term and some location information. For REST calls, the endpoint will be businesses/search. It requires that you provide at least location data. This can be in the form of the latitude and longitude query string parameters, or a location string describing the location. For example, "New York" or "NW 23rd Ave, PDX". You can refine the results further by providing a term string. For our example, we'll look for coffee in Kyoto.

With the REST API, this becomes:

// Using the yelpREST helper we defined earlier
yelpREST("/businesses/search", {
  params: {
    location: "kyoto",
    term: "coffee",
    limit: 10,
  },
}).then(({ data }) => {
  let { businesses } = data
  businesses.forEach((b) => {
    console.log("Name: ", b.name)
  })
})

In GraphQL, the same API call uses the search query:

// Using the yelpGQL helper we defined earlier
yelpGQL({
  data: JSON.stringify({
    query: `{
    search(term: "coffee",
            location: "kyoto",
            limit: 10) {
        business {
            name
        }
    }
}`,
  }),
}).then(({ data }) => {
  // Double data: data is what Axios puts the response body in, but it's also what GraphQL returns
  let businesses = data.data.search.business
  businesses.forEach((b) => {
    console.log("Name: ", b.name)
  })
})

Note: In this example, at the time of this writing, you may notice that the GraphQL API doesn't always respond correctly to the locale parameter. The REST API defaults to "en_US", so your results from each may differ in language.

As a result, we get back 10 results for coffee in the Kyoto area. Some of the things you can do with the response from this endpoint are:

• Pull in photos, which provides the URLs of 3 photos per business.
• Adjust the price level in your request, and view the price level in the response.
• See snippets of reviews with the reviews field.
• Get the listed hours of the business.
• Capture the Yelp ID of a business (We'll need this for the next section).

View reviews

Another great option, especially if you're building anything related to location data, is to pull in reviews for businesses. Yelp provides up to 3 reviews per business, in "Yelp Sorted" order. Each contains details about the review, and a direct link to the individual review.

With the REST API, the Yelp ID of the business is part of the endpoint. For example:

// Our REST helper from earlier
yelpREST("/businesses/9QFiF_YBCKvWsUu50G_yxg/reviews").then(({ data }) => {
  console.log(data)
})

With GraphQL, the same request looks like this:

// Our GQL Helper
yelpGQL({
  data: JSON.stringify({
    query: `{
      reviews(business: "9QFiF_YBCKvWsUu50G_yxg") {
        total
        review {
          url
          id
          rating
          text
        }
      }
    }`,
  }),
}).then(({ data }) => {
  console.log(data)
})

You'll notice that the Yelp ID is used with the business argument in the reviews query.

Some interesting things you can use the reviews resource for are:

• Retrieve the total review count and use it to make assumptions on popularity
• Average the scores of the three resulting review to get an approximation as to the rating of the business.

Use Yelp's Autocomplete

With Yelp's autocomplete API, you can autocomplete a string of text to match category names, businesses, and term suggestions that fit the types of things users search for on Yelp.

Autocomplete works with the /autocomplete endpoint in the REST API. This is one resource that is only accessible from the REST API and not offered on the GraphQL API.

In the Fusion API, here's an example:

yelpREST("/autocomplete", {
  params: {
    location: "pdx",
    text: "stumpt",
  },
}).then(({ data }) => {
  console.log(data)
})

The results show terms like "Stumptown Coffee", but also "Stump Removal". The autocomplete API can be useful as a gateway toward more detailed queries, but as with all autocomplete be careful not to send too many requests in a short span of time.

Things you cannot do

With some really valuable data available, there are things you cannot do with the public APIs. The biggest is modifying data. If your customers are businesses that use Yelp, you can't post anything with Yelps's API. There may, however, be opportunities for functionality like this on the Yelp Platform though it currently is focused around transactions.

In general, you need to use the data in good faith. This means no saving it and serving it up on your own. Make sure to read the terms of use around the API and how to effectively use the Yelp brand.

Rate limits

If you're using the API heavily, you are bound to at some point hit rate limits. Both the Fusion API and the GraphQL API have distinct rate limits that can be found in the documentation. If you receive an HTTP status code of 429, you've hit a limit. All requests are sent with RateLimit-prefixed headers that tell you the daily limit and the remaining requests. You can also view these from the "Manage App" screen.

The good news is that if you do hit the limits, Yelp offers contact information for requesting a higher tier. It's worth looking into if you rely heavily on their data. Another great option is to build in fallback functionality or incremental backoff into your code.

Fusion VIP

For developers looking for a more integrated approach with higher limits, more data, and fewer restrictions on the responses you receive (more images!) you can request to be part of the Fusion VIP program. They don't list specific requirements, but this is essentially the "approved app" tier of the API.

Wrapping up

Yelp offers a wealth of data for free through their API. It's a great way to incorporate local results into your application, and add value to your existing functionality. Spend some time exploring their API documentation further to see what else you can achieve.

Are you building anything exciting with the Yelp API or looking to integrate it? Let us know @BearerSH. We're building a tool to make all your API integrations work better and act more reliably. If the API goes down, our agent can remediate the failed requests automatically. Having a problem debugging a call? Our logging system can help. Check out what we're building at Bearer today.