In NoahZinsmeister/Rbnb: Experimental Front End for the Airbnb API

Introduction

Rbnb is an experimental front end for the (unofficial) Airbnb API. In addition to pulling detailed data on Airbnb listings based on arbitrary user-defined locations, Rbnb also provides a variety of visual summaries of these listings.

Use cases include, but are not limited to:

Prospective Airbnb guests and hosts who want to get a sense of the Airbnb market in their target location.
Current Airbnb hosts who wish to see how the price of their existing listing compares to similiar listings in their area.
Researchers interesting in analyzing granual microdata on short-term rental markets.

The authors are grateful to The Official Unofficial Airbnb API Docs for documenting much of the Airbnb API.

Installation

Before we get started, let's install Rbnb

library(devtools)
devtools::install_github("NoahZinsmeister/Rbnb")

Searching by Location

The first thing you may want to do after installing Rbnb is to try searching for listings in your current zip code. For example, one of the authors lives in 10019, a zip that includes Hell's Kitchen and midtown Manhattan. Let's pull listings data for this area.

library(Rbnb)

location = "10019"
content = Rbnb::searchLocation(location, verbose=FALSE)

Note: if you are unable to access the internet or the Airbnb API specifically, we've included a static pull of the 10019 data (zip10019.rda) that you can load in like so (in this example we'll be using the static pull):

data("zip10019", package="Rbnb")
content = zip10019
rm(zip10019)

And here's what we have!

str(content, max.level = 1)

As you can see, searchLocation returns a list with three elements: -passed.location -metadata -results

Let's take a closer look at these last two elements.

Metadata

Airbnb spits out some interesting metadata when given a location.

str(content$metadata, max.level = 1)

In our example, Airbnb provided metadata on r content$metadata$num.listings listings for your search term 'r as.character(content$passed.location)'. Your search term was recognized as a r content$metadata$geography$result.type, specifically a r content$metadata$geography$precision, which Airbnb resolved to the following location: r content$metadata$geography$city, r content$metadata$geography$state, r content$metadata$geography$country. We can even pull up the center of our search area on Google Maps.

The facets contain various distributional statistics, e.g.:

library(knitr)
kable(content$metadata$facets$bedrooms[1:5,])

We can use describeMetadata for a better look at some of these facets. For example, we can look at the distribution of bathrooms:

Rbnb::describeMetadata(content, facet = "bathrooms")

Or the room types:

Rbnb::describeMetadata(content, facet = "room.type")

If we only want to take a look at this metadata without going through the (sometimes lengthy) process of downloading individual listings, we can run the following:

Rbnb::searchLocation(location, metadata.only=TRUE, verbose=FALSE)

Results

Here's a look at the actual dataframe (tibble) we've pulled.

knitr::kable(content$results$data[1:5,c("name", "bedrooms", "neighborhood", "primary.host.first.name")])

This dataframe contains r content$metadata$num.listings listings related to your search term 'r as.character(content$passed.location)'.

We can use describeResults to plot the distribution of prices across room types.

Rbnb::describeResults(content)

And if we want to plot the location of listings on a map, we can use showMap.

Rbnb::showMap(content)

Listing Details

In addition to pulling many listings for a given location, the Airbnb API allows you to pull detailed information for a particular listing. This more detailed information includes information such as the amenities offered by the listing (like wireless internet and air conditioning), the cancellation policy, and the description provided the host.

To allow users to access this data, we provide the functions addDetails and listingDetails. addDetails is meant to be used with searchLocations, and, as the name implies, it adds the detailed information to a dataset of listings like the content$results$data.

detailsAdded <- Rbnb::addDetails(contents$results$data)

listingDetails is more flexible, in that it allows you to pull a dataset of detailed listing information simply using a character vector of listing IDs.

Note that listing IDs can be found in the ID column of content$results$data. They can also be found in the URLs of Airbnb listings. For example, consider the listing URl https://www.airbnb.com/rooms/12170773. Here, the listing ID is 12170773.

The line below would pull listing details for the first 20 listing IDs in content$results$data.

detailsAdded <- Rbnb::addDetails(contents$results$data[,1:20]$id)

Below we can see an example of detailed listing data. It's the result of adding details to the first 20 observations of the static content$results$data. The dataset, with 193 variables, is quite wide. 33 of these variables are indicators for various amenities.

data(detailsAdded,package="Rbnb")
knitr::kable(detailsAdded[1:5,c("name","neighborhood","amenity.Wireless.Internet")])
dim(detailsAdded)
sum(grepl("^amenity.",names(detailsAdded)))

Price Prediction

Let's say we're looking at an existing Airbnb listing and are curious as to how its price compares with that of comparable listings in the same area. The function predictPrice will take in a particular listing ID and build a detailed dataset of nearby listings as a training dataset to predict a price based on listing characteristics. This will tell you whether a particular listing is under- or overvalued given its features. The prediction method is gradient boosting using the package xgboost. Advanced users can specify some of the parameters used for prediction!

The function will return a list containing the listing ID of interest, the current price, a predicted price, the training dataset used, and the data for the listing of interest.

One item to note is that pulling listing details can be quite time consuming. For this reason, there is a parameter in pricePrediction called maxSample that allows you to limit the number of nearby listings for which details are pulled in. Below is a sample call to predictPrice.

price.prediction <- Rbnb::predictPrice(listingID="12170773",maxSample=500)

Here is predictPrice using static data instead of the API. Since no data is being pulled, maxSample is omitted. Note also your ability to pass xgboost parameters.

data("trainData", package="Rbnb")
data("listing.detail", package="Rbnb")

price.prediction <- Rbnb::predictPrice("12170773",
                    listing.detail = listing.detail, trainData = trainData,
                    # xgboost parameters for advanced users
                    nfold=10,  
                    nrounds=1000,
                    early_stopping_rounds=50,
                    max_depth=4,
                    eta=0.05)

str(price.prediction,max.level = 1)