In mdweisner/boardgameatlasR: Board Game Atlas API Wrapper

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(knitr)
library(dplyr)

library(boardgameatlasR)

Introduction

The boardgameatlasR package contains a function called search_bga(). search_bga() is an API wrapper for the API of https://www.boardgameatlas.com.

This vignette will cover a few of the basic usages of search_bga() and how to avoid some common mistakes.

Setup

Before you get started, you'll have to take the following steps:

• Register with https://www.boardgameatlas.com

• Create an "app" to get your client_id

• Add your client_id value to your R environment as "BOARDGAMEATLAS_PAT"

Adding your client_id to your R Environment

You can add the token with code like below:

usethis::edit_r_environ()

And then enter your BGA client_id in the following manner into your .Renviron file:

# Boardgame Atlas API Key
BOARDGAMEATLAS_PAT = "YOUR_CLIENT_ID"

Once you have done this, you'll have to restart R or your R session for the changes to take effect.

Arguments of search_bga()

limit & skip

An important thing to understand is that the BGA API is restricted to queries of no more than 100 objects per query. In order to get more than 100 games you have to use the skip feature to start where you left off. For instance, the first five games returned when ordered by popularity (at the time of writing this, 12/12/2019) are the following:

---

 id                 name             year_published

---

kPDxpJZ8PD Spirit Island 2016

RLlDWHh7hR Gloomhaven 2017

i5Oqu5VZgP Azul 2017

yqR4PtpO8X Scythe 2016

6FmFeux5xH Pandemic 2008

This could be queried with the following:

search_bga(limit = 5, skip = 0, order_by = "popularity")

The above code skips no games, returning the first object onward up to the limit, which in this case is 5 game objects. The default order_by value is popularity, which is based on the total number of times the game is mentioned at https://www.reddit.com/r/boardgames - a subreddit - a kind of forum - that is based on the discussion and recommendation of board games.

The 6th-10th games returned when ordered by popularity are as follows:

---

 id                 name             year_published

---

oGVgRSAKwX Carcassonne 2000

fDn9rQjH9O Terraforming Mars 2016

TAAifFP590 Root 2018

FCuXPSfhDR Concordia 2013

6VQXkkC5ql Dominion: Second Edition 2016

And the above could be queried with the following:

search_bga(limit = 5, skip = 5, order_by = "popularity")

You can see above it skips the first 5 games and returns an additional 5 games, the limit.

You can use this pattern to go beyond the 100 game limit of the API by requesting 100 games and then adjusting the skip value, like so:

games_1_to_100 <- search_bga(limit = 100, skip = 0, order_by = "popularity")
games_101_to_200 <- search_bga(limit = 100, skip = 100, order_by = "popularity")

You could then merge the datasets with code along the lines of the following:

games_1_to_200 <- cbind(games_1_to_100, games_101_to_200)

name

It's important to talk about what is probably the most logical way to search for a game, which is by its name. Name is relatively complicated in terms of this API, however.

• name, when used, will supposedly search for games based on the start of the string(s) provided to it. In practice, however, it seems to search for each word provided to it. For instance, name = "cata" returns a game called "Billy Biber." name = "catan", on the other hand, will turn up many games in the Catan family. We'll discuss the exact and fuzzy augmentations later.

Logical Arguments

The search_bga() function includes a number of logical arguments, including kickstarter, random, name_exact, name_fuzzy, ascending.

• kickstarter, if set to TRUE, will return active board game kickstarter campaigns. These have not yet completed their campaigns. Setting this to FALSE will avoid these in-development games. Kickstarter has been a popular platform for funding board games in recent years, so data regarding the games funded this way may be useful. This may change as the platform develops.

• random, if set to TRUE, will return random board games. Compared to the kickstarter argument this plays more nicely with other arguments. Behind the curtain, random behaves differently from all other boolean values, not requiring any coerscion from a traditional R logical boolean unlike the other values.

• name_exact & name_fuzzy both augment the name argument, but it's somewhat unclear how. For instance, while searching for search_bga(name = "Settlers of Catan") returned 23 games, including many games with that exact phrasing, search_bga(name = "Settlers of Catan", name_exact = TRUE) returned none, and search_bga(name = "Settlers of Catan", name_fuzzy = TRUE) returned only 9, most of which contained "Settlers of Catan" in the name.

• ascending, if FALSE, will return the top values - e.g. the "most popular" game if order_by is set to "popularity." Conversely, setting it to TRUE will draw from the bottom of the list, but how it is ordered with games with the same value is unclear.

Gameplay Statistics

• min_players & max_players

• min_playtime & max_playtime

• min_age & max_age

• min_year & max_year

Data

Textual Data

Monetary Data

Publisher Data

Physical Data

Reddit Data

Mechanics

Categories

Returned Data Basics

mdweisner/boardgameatlasR documentation built on July 10, 2020, 12:24 p.m.