How to use the Yelp API
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 theprice
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.