#' Search for events
#'
#' Use the Yelp event search API to find events near a given location and in
#' a given time range.
#' @param location A string describing the location.
#' @param latitude A number representing the latitude to search close to.
#' @param longitude A number representing the longitude to search close to.
#' @param radius_m A number giving the radius, in metres, of the search circle
#' around the specified location.
#' @param datetime_start A date-time object coercible to \code{POSIXct} representing
#' the earliest time for events.
#' @param datetime_end A date-time object coercible to \code{POSIXct} representing
#' the latest time for events.
#' @param is_free Logical. Set to \code{TRUE} to return only cost-free events,
#' \code{FALSE} to return only paid event, and \code{NA} for both.
#' @param categories A character vector of search categories to filter on,
#' or \code{NULL} to return everything. See \code{\link{SUPPORTED_CATEGORY_ALIASES}}
#' for allowed values.
#' @param locale A string naming the locale. See \code{\link{SUPPORTED_LOCALES}}
#' for allowed values.
#' @param limit An integer giving the maximum number of businesses to return.
#' Maximum 50.
#' @param offset An integer giving the number of businesses to skip before
#' returning. Allows you to return more than 50 businesses (split between
#' multiple searches).
#' @param sort_on Should the return values be sorted by \code{"popularity"} or
#' \code{"datetime_start"}?
#' @param sort_by Either \code{asc} for ascending order, or \code{desc} for
#' descending order.
#' @param access_token A string giving an access token to authenticate the API
#' call. See \code{\link{get_access_token}}.
#' @return A data frame with 28 columns. Each row corresponds to one event.
#' @examples
#' \donttest{
#' ## Marked as don't test because an access token is needed
#' events_in_houston <- event_search("houston")
#' if(interactive()) View(events_in_houston) else str(events_in_houston)
#' }
#' @importFrom purrr map_df
#' @export
event_search <- function(location = NULL, latitude = NULL, longitude = NULL,
radius_m = 40000, datetime_start = Sys.time(),
datetime_end = datetime_start + lubridate::ddays(7), is_free = NA,
categories = NULL, locale = get_yelp_locale(), limit = 50L, offset = 0L,
sort_on = c("popularity", "time_start"), sort_by = c("desc", "asc"),
access_token = Sys.getenv("YELP_ACCESS_TOKEN", NA)) {
# excluded_events arg not yet supported because the syntax isn't clear.
assert_has_access_token(access_token)
location <- parse_location(location)
check_latitude(latitude)
check_longitude(longitude)
radius_m <- parse_radius_m(radius_m)
start_date <- to_unix_time(datetime_start)
end_date <- to_unix_time(datetime_end)
locale <- parse_locale(locale)
check_limit(limit)
check_offset(offset)
sort_by <- match_arg(sort_by)
sort_on <- match_arg(sort_on)
categories <- parse_categories(categories)
is_free <- parse_is_free(is_free)
results <- call_yelp_api(
"events",
access_token,
locale = locale, offset = offset, limit = limit,
sort_by = sort_by, sort_on = sort_on,
start_date = start_date, end_date = end_date,
is_free = is_free, location = location,
latitude = NULL, longitude = NULL, radius = radius_m
)
map_df(results$events, event_to_df_row)
}
#' @importFrom tibble data_frame
event_to_df_row <- function(event) {
data_frame(
event_id = event$id,
name = event$name,
category = event$category,
description = event$description,
is_free = event$is_free,
cost = null2na(event$cost),
cost_max = null2na(event$cost_max),
business_id = null2empty(event$business_id),
event_site_url = event$event_site_url,
image_url = event$image_url,
tickets_url = null2empty(event$tickets_url),
interested_count = event$interested_count,
attending_count = event$attending_count,
# Ideally these times would be parsed, but they are local to the location
# and the time zone isn't provide in the API response.
time_start = null2empty(event$time_start),
time_end = null2empty(event$time_end),
is_canceled = event$is_canceled,
is_official = event$is_official,
latitude = event$latitude,
longitude = event$longitude,
address1 = event$location$address1,
address2 = null2empty(event$location$address2),
address3 = null2empty(event$location$address3),
city = null2empty(event$location$city),
zip_code = null2empty(event$location$zip_code),
state = null2empty(event$location$state),
country = null2empty(event$location$country),
display_address = toString(event$location$display_address),
cross_streets = null2empty(event$location$cross_streets)
)
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.