README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```



# The `bggscraper` project

<!-- badges: start -->
<!-- badges: end -->

`bggscraper` is a bundle of scripts that provide the functionality to scrape all
sorts of (publicly accessible) data from the [Board Game
Geek](boardgamegeek.com) website. It depends heavily on the [BGG XML
API2](https://boardgamegeek.com/wiki/page/BGG_XML_API2) library.

`bggscraper` was previously an R package, that could be installed and used.
However, I decided against making it a package because I found myself wasting
quite a lot of time doing package development as opposed to writing the scraping
code itself. Perhaps, when I am done writing all the code for scraping the BGG
website, I will convert it back to an R package again; however, this remains to
be seen.

Using this library, you may scrape the following info (among others):

* list of [top 5000 board games](https://boardgamegeek.com/search/boardgame?advsearch=1&q=&sort=rank) as per the rankings on BGG.
* details on board games and board game expansions (i.e., categories, mechanics, designers, etc.)
* BGG users' games collections, including what they own as well as what they hope to play or buy in the future.
* info on users themselves.
* list of games that are hot nowadays.
* information on plays of a certain game for one or more users.
* geeklists, forum lists, forums, threads or guilds pertaining to a certain board game id.



## How to Use

In order to use the `bggscraper` functionality, you will need to acquire a 
**BGG application token** first. Instructions can be found at 
[this link](https://boardgamegeek.com/using_the_xml_api) under the heading: 
*Application Tokens*.

Note that once you apply for a BGG application token, it may take a week or two 
till they provide you with one. Until then, you may check 
[your applications page](https://boardgamegeek.com/applications) regularly 
to check whether you have received it yet.

Once you have acquired a BGG application token, you may add it in the script
called `load_bgg_token.R` and you're good to go! To test, you may run the
`examples.R` script to ensure everything is working fine.

Enjoy!



## Examples

This is an example that shows how to retrieve information on a particular user's (board game) collection:

```{r, echo=TRUE}
source('common_funcs.R')

# get a user's game collection
user <- 'alizat'
collection_items <- collection(user)
collection_items_owned <- collection_items %>% filter(owned == "1")

# display names of that user's games
print(collection_items_owned$item_name)

# get supplementary details of the first 10 games
games_details <- thing(collection_items_owned$item_id[1:10])

# observe details of the first games
glimpse(games_details[1,])
```

This is an example that shows to retrieve the current top 10 board games ids as per [BGG's rankings](a)

```{r, echo=TRUE}
source('common_funcs.R')

# top 10 ranked games on BGG
top_10_games_ids <- top_k_games_ids(k = 10)

# get details for each item in user's collection
games_details <- thing(top_10_games_ids)
games_details %>% 
    select(name, year_published, designer, rating_avg) %>% 
    mutate(designer = map_chr(designer, paste, collapse = ', ')) %>% 
    print()
```

<!-- You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this. You could also use GitHub Actions to re-render `README.Rmd` every time you push. An example workflow can be found here: <https://github.com/r-lib/actions/tree/v1/examples>. -->

<!-- You can also embed plots, for example: -->
<!-- ```{r pressure, echo = FALSE} -->
<!-- plot(pressure) -->
<!-- ``` -->
<!-- In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN. -->