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%"
)
```

# rTwitchAPI

<!-- badges: start -->
  [![Travis build status](https://travis-ci.org/Freguglia/rTwitchAPI.svg?branch=master)](https://travis-ci.org/Freguglia/rTwitchAPI)
<!-- badges: end -->

`rTwitchAPI` allows you to make calls to the [API](https://dev.twitch.tv/docs/api/reference/) of the popular streaming website [twitch.tv](twitch.tv) with simple R functions, allowing users to interact with the API even without great understaing of REST APIs and http. Since R is primarily used for statistical analysis, currently, the package only provides access to endpoints that return data, for example, [`GET https://api.twitch.tv/helix/streams`](https://dev.twitch.tv/docs/api/reference/#get-streams). Users who might need other functionalities are very likely to also need integration with tools from other programming languages and/or have enough background to directly implement the call with [`httr`](https://github.com/r-lib/httr).

In summary, `rTwitchAPI` removes the burden of writing the calls to specific endpoints and proccess results, making code cleaner, simpler and more accessible. It is just an interface to access the API and is in no way related to Twitch or the Twitch API. As stated in the [official documentation](https://dev.twitch.tv/docs/), by using it, you agree to [Twitch Developer Services Agreement](https://www.twitch.tv/p/legal/developer-agreement/).

## Installation

<!---You can install the released version of rTwitchAPI from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("rTwitchAPI")
```-->

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("Freguglia/rTwitchAPI")
```

## Authentication

As most API's, Twitch API requires authentication for some types of calls, in the form of a **Client-ID** and/or an **Oauth token**. You can setup your Client-ID with the `twitch_auth()` function. For more information access on Client-ID and how to register your app, read [this link](https://dev.twitch.tv/dashboard/apps/create).

**Define your Client-ID and Client-Secret variable.**

In order to add your Client-ID and Client-Secret to your environment file, you can use the function `edit_r_environ()` from the [`usethis` package](https://usethis.r-lib.org/).

```{r, eval = F}
usethis::edit_r_environ()
```


This will open your .Renviron file in your text editor. Now, you can add the following line to it:

```{r, eval = F}
TWITCH_CLIENT_ID=YOUR_CLIENT_ID
TWITCH_CLIENT_SECRET=YOUR_CLIENT_SECRET
```

Save the file and restart R for the changes to take effect.

## Example

```{r}
library(rTwitchAPI)

# Setup authentication
twitch_auth()

# An example request to the streams endpoint
streams_live <- get_streams(first = 15, language = "en")
streams_live$data
```

## Contributions

If you find anything wrong in the package, have a suggestion, comment or request, please file an issue. Pull requests are also welcome.