NOTICE

This repository is for the v3 version of the API and no longer supported.

A member of the community has created this for V4: https://github.com/praster1/igdbV4

igdb-api-r

An R wrapper for the IGDB.com Free Video Game Database API.

About IGDB

One of the principles behind IGDB.com is accessibility of data. We wish to share the data with anyone who wants to build cool videogame oriented websites, apps and services. This means that the information you contribute to IGDB.com can be used by other projects as well.

Thus, you are not only contributing to the value of this site but to thousands of other projects as well. We are looking forward to see what exciting game related projects you come up with. Happy coding!

More info here:

• About the API
• API Documentation

Installation and setup

To get the current version from github:

install.packages("devtools")
devtools::install_github("igdb/igdb-api-r")

Using your API key

• create a local variable and pass that to your requests

igdb_key <- "YOUR KEY"
igdb_request(GAMES, params, igdb_key)

• OR create a environment variable and pass that to your requests

Sys.setenv(igdb_key = "YOUR KEY")
igdb_key = Sys.getenv("igdb_key")
igdb_request(GAMES, params, igdb_key) || igdb_request(GAMES, params, Sys.getenv("igdb_key")

Usage

All API endpoints are available as variables in the wrapper.

Example: you want to request the games endpoint then you use the variable 'GAMES'

All endpoints (variables)

• CHARACTERS
• COLLECTIONS
• COMPANIES
• CREDITS
• FEEDS
• FRANCHISES
• GAME_ENGINES
• GAME_MODES
• GAMES
• GENRES
• KEYWORDS
• PAGES
• PEOPLE
• PLATFORMS
• PLAYER_PERSPECTIVES
• PULSE_GROUPS
• PULSE_SOURCES
• PULSES
• RELEASE_DATES
• REVIEWS
• THEMES
• TITLES

Requesting Data

Arguments

• endpoint - the chosen endpoint to request, use the variables above
• Parameters - An object specifying the operations to be performed, ex. expander, filter, ordering etc. These Operations can be found in the API documentation under References: (https://igdb.github.io/api/references/)
• key - Your api key for authentication

Using the parameters function

To help you structure your requests correctly you should use the igdb_parameters function. The functions parameters:

igdb_parameters <- function(
  fields = "",
  limit = 10,
  offset = 0,
  order = "",
  ids = "",
  expand = "",
  search = "",
  filter = list(),
  query = ""
){}

query is for advanced usage which overrides the logic of the function. It is basically a return(query)

IMPORTANT

• Note that the filter param is a list() of "strings"
• Note that you cannot use both search and ids, this will trow an exception

The response structure

The response is returnes as a structure which looks like this:

structure(
    list(
      content = The parsed JSON response,
      path = The complete path,
      response = The response from httr
    ),
    class = "igdb_api"
  )

this can help with debugging requests. To get the json from the response: json_resp$content

EXAMPLES Requesting games from the API

igdb_key <- "YOUR KEY"
params <- igdb_parameters(fields = "*", order = "published_at:desc")
json_resp <- igdb_request(GAMES, params, igdb_key)
# The sent request will look like this:
# https://api-endpoint.igdb.com/games/?fields=*&order=published_at:desc 

Searching for a game m the API

igdb_key <- "YOUR KEY"
params <- igdb_parameters(search = "Zelda", fields = "*", order = "published_at:desc")
json_resp <- igdb_request(GAMES, params, igdb_key)
# The sent request will look like this:
# https://api-endpoint.igdb.com/games/?search=Zelda&fields=*&order=published_at:desc 

Using filter

igdb_key <- "YOUR KEY"
params <- igdb_parameters(fields = "*", 
                         order = "published_at:desc", 
                         filter = list("[themes][not_in]=42"))
json_resp <- igdb_request(GAMES, params, igdb_key)
# The sent request will look like this:
# https://api-endpoint.igdb.com/games/?fields=*&filter[themes][not_in]=42&order=published_at:desc 

More examples

Search for up to two Atari platforms and return their names

params <- igdb_parameters(search = "Atari", fields = "name", limit = 2)
json_resp <- igdb_request(PLATFORMS, params, igdb_key)

# The sent request will look like this:
# https://api-endpoint.igdb.com/platforms/?search=Atari&fields=name&limit=2 

Search for up to five Zelda games with release dates between 1 Jan and 31 Dec 2011, sorted by release date in descending order.

params <- igdb_parameters(search = "Zelda", 
                         fields = "name,release_dates.date,rating,hypes,cover", 
                         filter = list("[release_dates.date][gt]=2010-12-31", 
                                      "[release_dates.date][lt]=2012-01-01"),
                         limit = 2),
                         order = "release_dates.date:desc")
json_resp <- igdb_request(GAMES, params, igdb_key)

# The sent request will look like this:
# https://api-endpoint.igdb.com/games/?search=Zelda&fields=name,release_dates.date,rating,hypes,cover&filter[release_dates.date][gt]=2010-12-31&filter[release_dates.date][lt]=2012-01-01&limit=5&order=release_dates.date:desc 

Search for companies with 'rockstar' in their name. Return up to five results sorted by name in descending order

params <- igdb_parameters(search = "rockstar", 
                         fields = "name,logo", 
                         filter = list("[name][in]=rockstar"),
                         limit = 5),
                         order = "name:desc")
json_resp <- igdb_request(COMPANIES, params, igdb_key)

# The sent request will look like this:
# https://api-endpoint.igdb.com/companies/?search=rockstar&fields=name,logo&filter[name][in]=rockstar&limit=5&offset=0&order=name:desc

Search for two specific games by their IDs

params <- igdb_parameters(ids = "18472,18228", 
                         fields = "name,cover")
json_resp <- igdb_request(GAMES, params, igdb_key)

# The sent request will look like this:
# https://api-2445582011268.apicast.io/games/18472,18228?fields=name,cover