README.Rmd

---
output: github_document
---

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

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  cache = TRUE
)
library(kaggler)
options(width = 100)
options(tibble.print_min = 5)
options(tibble.print_max = 5)
```
# kaggler <img src="man/figures/logo.png" width="160px" align="right" />

> 🏁 An R client for accessing [Kaggle](https://www.kaggle.com)'s API

## Installation

You can install the dev version of **{kaggler}** from [CRAN](https://github.com/mkearney/kaggler) with:

```{r, eval = FALSE}
## install kaggler package from github
devtools::install_packages("mkearney/kaggler")
```

## API authorization

<span>1.</span> Go to [https://www.kaggle.com/](kaggle.com) and sign in

<span>2.</span> Click `Account` or navigate to `https://www.kaggle.com/{username}/account`

<span>3.</span> Scroll down to the `API` section and click `Create New API Token` (which should cause you to download a `kaggle.json` file with your username and API key)

<p style='align:center'><img src='tools/readme/kag.png' /></p>

<span>4.</span> There are a few different ways to store your credentials

   + Save/move the `kaggle.json` file as `~/.kaggle/kaggle.json`
   + Save/move the `kaggle.json` file to your current working directory
   + Enter your `username` and `key` and use the `kgl_auth()` function like in the example below

```{r, eval = FALSE}
kgl_auth(username = "mkearney", key = "9as87f6faf9a8sfd76a9fsd89asdf6dsa9f8")
#> Your Kaggle key has been recorded for this session and saved as `KAGGLE_PAT` environment variable for future sessions.
```


## `kgl_competitions_list_.*()`

Browse or search for Kaggle compeitions.

```{r complist}
## look through all competitions (paginated)
comps1 <- kgl_competitions_list()
comps1

## it's paginated, so to see page two:
comps2 <- kgl_competitions_list(page = 2)
comps2

## search by keyword for competitions
imagecomps <- kgl_competitions_list(search = "image")
imagecomps
```

## `kgl_competitions_data_.*()`

Look up the datalist for a given Kaggle competition. **IF you've already accepted the competition rules, then you should be able to download the dataset too (I haven't gotten there yet to test it)**

```{r}
## data list for a given competition
c1_datalist <- kgl_competitions_data_list(comps1$id[1])
c1_datalist

## download set sets (IF YOU HAVE ACCEPTED COMPETITION RULES)
c1_data <- kgl_competitions_data_download(
  comps1$id[1], c1_datalist$name[1])
```

## `kgl_datasets_.*()`

Get a list of all of the datasets.

```{r datalist}
## get competitions data list
datasets <- kgl_datasets_list()
datasets
```


## `kgl_competitions_leaderboard_.*()`

View the leaderboard for a given competition.

```{r leaderboard}
## get competitions data list
c1_leaderboard <- kgl_competitions_leaderboard_view(comps1$id[1])
c1_leaderboard
```


## Note(s)

+ The author is in no way affiliated with Kaggle.com, and, as such, makes no
assurances that there won't be breaking changes to the API at any time.

+ Although I am not affiliated, it's good practice to be informed, so here is
the link to Kaggle's terms of service: https://www.kaggle.com/terms