The Complete Guide to the Yelp API

Part of the Spectral API Security Series

Yelp.com is one of the most influential crowdsourcing sites for businesses. The company is worth just over one billion dollars and thrives in the business of local search, ratings, reviews, and online food delivery. We’re in an age where data crowns you a king, and with an estimated 192 million user generated reviews, Yelp is certainly a ruler.

Yelp’s API offers its database of information for developers to integrate into custom apps in unique and creative ways. This can result in an enhanced experience for end users and the businesses it impacts.

But before we get right into how to use Yelp’s API, let’s take a step back and answer some important questions.

What is an API?

An API is an interface between two different systems. It’s like a bridge that allows the client and host to exchange data. Actions performed by an API to a dataset are categorized as create, read, update, and delete – more commonly known as CRUD. The information pushed or pulled from the source often comes in either an XML or JSON format. In the case of Yelp Fusion API, data is returned in JSON.

One of the main advantages of an API is that it allows authorized or open access to specific data, allowing the data owner to keep their system separate from 3rd party components. This creates a decoupling effect where the 3rd party isn’t required to natively integrate into the host’s systems. Data exposure is also limited by the host, allowing for seamless versioning and support.

This is basically what an API is for app development is in a nutshell. So what can you do with Yelp’s API?

Yelp API – step by step

Yelp’s API, also known as Yelp Fusion, is broken into three distinct categories of data types – business, events, and categories. Each associated API returns a response body based on the given parameters.

To use Yelp’s API, you will need to create a new app through the developers portal. This will give you authentication keys that will grant you access to data through Yelp Fusion.

Once completed, you’ll get given a client ID and API Key. Although the API is free to access, there is a cap on daily API calls. 5000 calls is a decent amount to experiment and build you apps with, but if you want to scale it, you’ll need to apply for Yelp Fusion VIP.

If you need a new API key, you can fresh it by scrolling down on the same page to the Refresh My API Key option. This can be handy if you accidentally compromised or misplaced your Yelp API key.

Yelp Fusion API request parameters

All of Yelp Fusion API endpoints start with https://api.yelp.com/v3 , followed by the search type path, and finally the parameters.

For example, the business search has /businesses/search as the path, followed by a ? and a series of parameters that you can search with such as term, location, latitude, longitude, radius, categories, locale, limit, offset, sort_by, price, open_now, open_at, and attributes.

To add multiple parameters to your GET request, use & in between the parameters.

For example, to search up a business in New York, your request URL may look something like this:

https://api.yelp.com/v3/businesses/search?location=NYC

The data returned is in JSON format and can easily be parsed into your apps. You can also be more specific and see which bars in New York are currently open.

https://api.yelp.com/v3/businesses/search?location=NYC&categories=bars&open_now=true

To create a pagination effect, you can use a combination of limit and offset. limit deals with how many results are returned in any single GET request, while offset returns your search results from a particular point. 

By default, the first 20 businesses are returned based on the given GET query. However, for your app, you want 40 businesses displayed on a page. The next page will show the next 40 businesses.

Building your GET query can look something like this for page 2: https://api.yelp.com/v3/businesses/search?location=NYC&categories=bars&open_now=true$limit=40&offset=40

And for page 3: https://api.yelp.com/v3/businesses/search?location=NYC&categories=bars&open_now=true$limit=40&offset=80

To use your auth credentials, you need to add an Authorization and value to your header. You also need to add Bearer in front of your API key for it to work.

For example, you end header details should look something like this:

GET /v3/businesses/search?location=NYC&categories=bars&open_now=true HTTP/1.1
Host: api.yelp.com
Authorization: Bearer <API key here>
Cache-Control: no-cache

If you’re using Postman to test your connection, your Authorization header should look something like this:

Common errors with Yelp Fusion API and how to fix them

If you get the following error it means that your authorization headers are not included in the headers.

 {
    "error": {
        "code": "VALIDATION_ERROR",
        "description": "Authorization is a required parameter.",
        "field": "Authorization",
        "instance": null
    }
 }

The following error indicates that you neglected to add the keyword Bearer as part of your Authorization value. Alternatively, your API key is incorrect.  For Yelp Fusion API to return results, the formatting for Authorization needs to be Bearer <your API key here>.

  {
    "error": {
        "code": "VALIDATION_ERROR",
        "description": "'somekeyhere' does not match '^(?i)Bearer [A-Za-z0-9\\\\-\\\\_]{128}$'",
        "field": "Authorization",
        "instance": "somekeyhere"
    }
 }

If you get "code": "VALIDATION_ERROR", it means that your parameters may be incorrect. 

For example, the search API https://api.yelp.com/v3/businesses/search cannot be queried without at least one search parameter. It needs at least location, latitude or longitude.

GraphQL with Yelp API

GraphQL with Yelp API is still in Beta development and you’ll need to join ‘Yelp Developer Beta Program’ in order to enable the feature. 

You can do this by navigating to your Manage App area, and under the ‘API Usage’ statistics, there is an option to join the beta program.

With GraphQL, you have a  daily points limit of 250000. You can use the same authentication credentials for both GraphQL and default Yelp Fusion API.

Yelp Fusion REST API vs Yelp GraphQL

The major difference between GraphQL and Yelp’s REST API is that the latter is highly structured. That means that it may require a certain level of API layering and sequencing to get to the data you want. 

With GraphQL, the number of queries you need may be less. The volume of data returned for GraphQL is also more tailored to what you want. In contrast, Yelp Fusion REST API will return a structured set of data that may include things you don’t need for your app.

The advantage of using GraphQL is the ability to control and refine data transfer rates to your needs. However, it’s also good to take note that GraphQL is still in beta mode, meaning that stability and reliability may not be production-ready.

Keeping in secure

While it’s easy to integrate your auth key in through your front end, it’s better from a security standpoint to implement it on the server rather than on the client. This is because your auth key becomes exposed to the world and this can easily be uplifted for abuse. Unauthorized usage of your auth key can result in your account getting maxed out unnecessarily.

One way around this is to create an intermediary layer where your frontend sends your backend the details it needs and your backend constructs the GET query required.

Yelping it out

Yelp Fusion API is easy to work with once you get into the flow of it. The structure is standardized and follows the general GET query flow for data requests. You can find more about all the different endpoints and parameters available in the official Yelp API documentation.