In richierocks/yelp: Interface to the Yelp Fusion API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)

for(pkg in c("yelp", "magrittr", "dplyr", "ggmap", "tidytext")) {
  suppressPackageStartupMessages(library(pkg, quiet = TRUE, character.only = TRUE))
}

ggmap::register_google(Sys.getenv("GOOGLE_MAPS_API_KEY"), "standard")

yelp

This R package provides access to the Yelp Fusion API, version 3.

Installation and setup

To use this package, you must install it and get an access token for the API.

Package installation

To install the package, you first need remotes installed.

install.packages("remotes")

remotes::install_github("richierocks/yelp")

Getting the client ID and client secret

To gain access to the API, you have to register with Yelp, log in, and create your own app. This takes 5 to 10 minutes of pointing and clicking. It's reasonably self-explanatory, and there are more details on the API Authentication page.

Once you have registered, make a note of your client ID and client secret.

Getting and storing an access token

You use the client ID and client secret to get an access token.

access_token <- get_access_token(client_id, client_secret)

This access token can be passed into individual calls to the API, or you can store it so the package will automatically find it. store_access_token(access_token) will store it for the R session, or you can use your operating system tools to set a YELP_ACCESS_TOKEN environment variable to store it permanently.

Join the Developer Beta program

Some features such as business match and event search require you to sign up for the Yelp Developer Beta program. You can do this from the Manage App page.

Set your locale

By default, the package assumes that you are in the USA, and uses the locale en_US. You can override this for the session using set_yelp_locale(), or permanently by setting an environment variable named YELP_LOCALE.

Usage

To search for businesses close to a specific location, call business_search() with a string giving a search term and either a string describing a location or numbers giving latitude and longitude. The return value is a tibble (since it has a nicer print method for wider data frames) with one business per row.

library(yelp)
library(dplyr)
salons_in_la <- business_search("beauty salon", "los angeles")
glimpse(salons_in_la)

The results include the longitude and latitude of each business, so you can use ggmap to plot their locations.

library(ggmap)
library(magrittr)
la <- salons_in_la %$%
  c(median(longitude), median(latitude))
la_map <- get_map(la, zoom = 11)
(map_plot_of_salons_in_la <- ggmap(la_map) + 
  geom_point(aes(longitude, latitude), data = salons_in_la)
)

You can use standard dplyr tools to filter for businesses that are interesting to you.

five_stars_and_cheap <- salons_in_la %>% 
  filter(rating == 5, price == "$")

business_lookup() gives you more detailed information about businesses, including opening hours. It costs 1 API call per business, so do your filtering before you call it.

five_stars_and_cheap_details <- business_lookup(five_stars_and_cheap)
glimpse(five_stars_and_cheap_details)
five_stars_and_cheap_details$opening_hours

You can also use reviews() to get reviews of the businesses. Again, it costs 1 API call per business. Also, you are limited to 3 reviews per business, and the text of each is truncated. This is an API limitation, not a problem with this R package.

five_stars_and_cheap_reviews <- reviews(five_stars_and_cheap)
glimpse(five_stars_and_cheap_reviews)

In theory, these can be used with the tidytext package to perform a sentiment analysis, though the limited amount of text is a problem.

library(tidytext)
(five_stars_and_cheap_sentiments <- five_stars_and_cheap_reviews %>% 
  select(business_id, review_id, rating, text) %>% 
  unnest_tokens(word, text) %>% 
  anti_join(get_stopwords(), by = "word") %>% 
  inner_join(get_sentiments("bing"))
)

Yelp also provide information on events. Call event_search() to see them.

events_in_la <- event_search("los angeles")
glimpse(events_in_la)

There are some other functions with more niche usage.

autocomplete() takes a search term, and returns some related search terms that Yelp understands.
business_match() provides a more targetted search for a business, when you know its name and rough address.
event_lookup() returns details for a specific event given its Yelp ID.
featured_event() returns the Yelp-curated featured event for a location.
food_delivery_search() lets you find businesses that will deliver food to a given location.
categories() provides more information on the search category aliases.
phone_search() lets you search for a business by phone number.