from: https://api-docs.igdb.com/

Getting Started

One of the principles behind IGDB.com is accessibility of data. We wish to share the data with anyone who wants to build cool video game oriented websites, apps and services.

This means that you are not only contributing to the value of IGDB 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!

For a high level overview of our juicy data, check out the endpoints section.START USING US NOW, IT’S FREE!

Account Creation

In order to use our API, you must have a Twitch Account.

Sign Up with Twitch for a free account
Ensure you have Two Factor Authentication enabled
Register your application in the Twitch Developer Portal
Manage your newly created application
Generate a Client Secret by pressing [New Secret]
Take note of the Client ID and Client Secret

The IGDB.com API is free for non-commercial usage under the terms of the Twitch Developer Service Agreement.Note: We offer commercial partnership for users with a commercial need in their projects. For more details on that process please reach out to partner@igdb.com

Authentication

Now that you have a Client ID and Client Secret you will be authenticating as a Twitch Developer using Oauth2.
Detailed information can be found in the Twitch Developer Docs.

Make a POST request to https://id.twitch.tv/oauth2/token with the following query string parameters, substituting your Client ID and Client Secret accordingly.

client_id=Client ID

client_secret=Client Secret

grant_type=client_credentials

Example

If your Client ID is abcdefg12345 and your Client Secret is hijklmn67890, the whole url should look like the following.

POST: https://id.twitch.tv/oauth2/token?client_id=abcdefg12345&client_secret=hijklmn67890&grant_type=client_credentials

The response from this will be a json object containing the access token and the number of second until the token expires.

{
  "access_token": "access12345token",
  "expires_in": 5587808,
  "token_type": "bearer"
}

Note: The expires_in shows you the number of seconds before the access_token will expire and must be refreshed.

Requests

Most of the requests to the API will use the POST method
The base URL is: https://api.igdb.com/v4
You define which endpoint you wish to query by appending /{endpoint name} to the base URL eg. https://api.igdb.com/v4/games
Include your Client ID and Access Token in the HEADER of your request so that your headers look like the following.
- Take special care of the capitalisation. Bearer should be hard-coded infront of your access_token

Client-ID: Client ID
Authorization: Bearer access_token

You use the BODY of your request to specify the fields you want to retrieve as well as any other filters, sorting etc

Example

If your Client ID is abcdefg12345 and your access_token is access12345token, a simple request to get information about 10 games would be.

POST: https://api.igdb.com/v4/games
Client-ID: abcdefg12345
Authorization: Bearer access12345token
Body: "fields *;"

Note: If you are trying to make these requests via the Browser you will run into CORS errors as the API does not allow requests directly from browsers. You can read more about CORS and how to go around this issue in the CORS Proxy section

More Examples

You can find some examples requests here

Rate Limits

There is a rate limit of 4 requests per second. If you go over this limit you will receive a response with status code 429 Too Many Requests.

You are able to have up to 8 open requests at any moment in time. This can occur if requests take longer than 1 second to respond when multiple requests are being made.

Wrappers

Get setup quickly by using one of these wrappers!

Apicalypse

Third Party

Examples

It’s recommended to try out your queries in an API viewer like Postman or Insomnia before using code. This helps you find problems a lot sooner!

Postman setup example

A very basic example to retrieve the name for 10 games.

https://api.igdb.com/v4/games/

fields name; limit 10;

Get all information from a specific game

1942, is the ID of a game.

https://api.igdb.com/v4/games/

fields *; where id = 1942;

Exclude irrelevant data from your query

Remove alternative_name from your result query

https://api.igdb.com/v4/platforms/

fields *;
exclude alternative_name;

Get all games from specific genres

Notice how you can comma separate multiple IDs (8, 9, and 11). You can do this with games, companies and anything else. Also note that when you have multiple IDs they have to be surrounded by a parenthesis. Single ids can be queried both with and without the parenthesis.

https://api.igdb.com/v4/genres/

fields *; where id = (8,9,11);

Count total games that have a rating higher than 75

https://api.igdb.com/v4/games/count

where rating > 75;

Order by rating

https://api.igdb.com/v4/games/

fields name,rating; sort rating desc;

Coming soon games for Playstation 4

https://api.igdb.com/v4/release_dates/

fields *; where game.platforms = 48 & date > 1538129354; sort date asc;

1538129354: Is the timestamp in milliseconds of 28/09/2018 (This you need to generate yourself) 48 Is the platform id of Playstation 4.

Recently released games for Playstation 4

fields *; where game.platforms = 48 & date < 1538129354; sort date desc;

Note: “where game.platforms = 48 & date > 1538129354” It is possible to use either & (AND) or | (OR) to combine filters to better define the behaviour of your query

Search, return certain fields.

https://api.igdb.com/v4/games/

search "Halo"; fields name,release_date.human;

https://api.igdb.com/v4/games/

fields name, involved_companies; search "Halo";

Search games but exclude versions (editions)

https://api.igdb.com/v4/games/

fields name, involved_companies; search "Assassins Creed"; where version_parent = null;

This will return search results with ID and name of the game but exclude editions such as “Collectors Edition”.

Searching all endpoints

Note: Search is now also it’s own endpoint. Search is usable on: Characters, Collections, Games, Platforms, and Themes

The example below searches for “Sonic the Hedgehog” which will find the Character Sonic, the collection Soninc the Hedgehog. And of course also several games with names containing Sonic the Hedgehog.

https://api.igdb.com/v4/search

fields *; search "sonic the hedgehog"; limit 50;

Get versions (editions) of a game

https://api.igdb.com/v4/game_versions/

fields game.name,games.name; where game = 28540;

The resulting object will contain all games that are a version of the game with id 28540

Get the parent game for a version

https://api.igdb.com/v4/games/

fields version_parent.*; where id = 39047;

The resulting object will contain all main games

Get all games that are playstation 4 exclusives

fields name,category,platforms;
where category = 0 & platforms = 48;

Get all games that are only released on playstation 4 AND PC

fields name,category,platforms;
where category = 0 & platforms = {48,6};

Endpoints

Age Rating

from requests import post
response = post('https://api.igdb.com/v4/age_ratings', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,content_descriptions,rating,rating_cover_url,synopsis;'})
print ("response: %s" % str(response.json()))

Age Rating according to various rating organisations

Request Path

https://api.igdb.com/v4/age_ratings

field	type	description
category	Category Enum	The organization that has issued a specific rating
checksum	uuid	Hash of the object
content_descriptions	Array of Age Rating Content Description IDs
rating	Rating Enum	The title of an age rating
rating_cover_url	String	The url for the image of a age rating
synopsis	String	A free text motivating a rating

Age Rating Enums

category

name	value
ESRB	1
PEGI	2
CERO	3
USK	4
GRAC	5
CLASS_IND	6
ACB	7

rating

name	value
Three	1
Seven	2
Twelve	3
Sixteen	4
Eighteen	5
RP	6
EC	7
E	8
E10	9
T	10
M	11
AO	12
CERO_A	13
CERO_B	14
CERO_C	15
CERO_D	16
CERO_Z	17
USK_0	18
USK_6	19
USK_12	20
USK_16	21
USK_18	22
GRAC_ALL	23
GRAC_Twelve	24
GRAC_Fifteen	25
GRAC_Eighteen	26
GRAC_TESTING	27
CLASS_IND_L	28
CLASS_IND_Ten	29
CLASS_IND_Twelve	30
CLASS_IND_Fourteen	31
CLASS_IND_Sixteen	32
CLASS_IND_Eighteen	33
ACB_G	34
ACB_PG	35
ACB_M	36
ACB_MA15	37
ACB_R18	38
ACB_RC	39

Alternative Name

from requests import post
response = post('https://api.igdb.com/v4/alternative_names', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,comment,game,name;'})
print ("response: %s" % str(response.json()))

Alternative and international game titles

Request Path

https://api.igdb.com/v4/alternative_names

field	type	description
checksum	uuid	Hash of the object
comment	String	A description of what kind of alternative name it is (Acronym, Working title, Japanese title etc)
game	Reference ID for Game	The game this alternative name is associated with
name	String	An alternative name

Artwork

from requests import post
response = post('https://api.igdb.com/v4/artworks', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,game,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

official artworks (resolution and aspect ratio may vary)

Request Path

https://api.igdb.com/v4/artworks

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
game	Reference ID for Game	The game this artwork is associated with
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Age Rating Content Description

from requests import post
response = post('https://api.igdb.com/v4/age_rating_content_descriptions', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,description;'})
print ("response: %s" % str(response.json()))

Age Rating Descriptors

Request Path

https://api.igdb.com/v4/age_rating_content_descriptions

field	type	description
category	Category Enum
checksum	uuid	Hash of the object
description	String

Age Rating Content Description Enums

category

name	value
ESRB_alcohol_reference	1
ESRB_animated_blood	2
ESRB_blood	3
ESRB_blood_and gore	4
ESRB_cartoon_violence	5
ESRB_comic_mischief	6
ESRB_crude_humor	7
ESRB_drug_reference	8
ESRB_fantasy_violence	9
ESRB_intense_violence	10
ESRB_language	11
ESRB_lyrics	12
ESRB_mature_humor	13
ESRB_nudity	14
ESRB_partial_nudity	15
ESRB_real_gambling	16
ESRB_sexual_content	17
ESRB_sexual_themes	18
ESRB_sexual_violence	19
ESRB_simulated_gambling	20
ESRB_strong_language	21
ESRB_strong_lyrics	22
ESRB_strong_sexual content	23
ESRB_suggestive_themes	24
ESRB_tobacco_reference	25
ESRB_use_of alcohol	26
ESRB_use_of drugs	27
ESRB_use_of tobacco	28
ESRB_violence	29
ESRB_violent_references	30
ESRB_animated_violence	31
ESRB_mild_language	32
ESRB_mild_violence	33
ESRB_use_of drugs and alcohol	34
ESRB_drug_and alcohol reference	35
ESRB_mild_suggestive themes	36
ESRB_mild_cartoon violence	37
ESRB_mild_blood	38
ESRB_realistic_blood and gore	39
ESRB_realistic_violence	40
ESRB_alcohol_and tobacco reference	41
ESRB_mature_sexual themes	42
ESRB_mild_animated violence	43
ESRB_mild_sexual themes	44
ESRB_use_of alcohol and tobacco	45
ESRB_animated_blood and gore	46
ESRB_mild_fantasy violence	47
ESRB_mild_lyrics	48
ESRB_realistic_blood	49
PEGI_violence	50
PEGI_sex	51
PEGI_drugs	52
PEGI_fear	53
PEGI_discrimination	54
PEGI_bad_language	55
PEGI_gambling	56
PEGI_online_gameplay	57
PEGI_in_game_purchases	58
CERO_love	59
CERO_sexual_content	60
CERO_violence	61
CERO_horror	62
CERO_drinking_smoking	63
CERO_gambling	64
CERO_crime	65
CERO_controlled_substances	66
CERO_languages_and others	67
GRAC_sexuality	68
GRAC_violence	69
GRAC_fear_horror_threatening	70
GRAC_language	71
GRAC_alcohol_tobacco_drug	72
GRAC_crime_anti_social	73
GRAC_gambling	74
CLASS_IND_violencia	75
CLASS_IND_violencia_extrema	76
CLASS_IND_conteudo_sexual	77
CLASS_IND_nudez	78
CLASS_IND_sexo	79
CLASS_IND_sexo_explicito	80
CLASS_IND_drogas	81
CLASS_IND_drogas_licitas	82
CLASS_IND_drogas_ilicitas	83
CLASS_IND_linguagem_impropria	84
CLASS_IND_atos_criminosos	85

Character Mug Shot

from requests import post
response = post('https://api.igdb.com/v4/character_mug_shots', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

Images depicting game characters

Request Path

https://api.igdb.com/v4/character_mug_shots

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Character

from requests import post
response = post('https://api.igdb.com/v4/characters', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields akas,checksum,country_name,created_at,description,games,gender,mug_shot,name,slug,species,updated_at,url;'})
print ("response: %s" % str(response.json()))

Video game characters

Request Path

https://api.igdb.com/v4/characters

field	type	description
akas	Array of Strings	Alternative names for a character
checksum	uuid	Hash of the object
country_name	String	A characters country of origin
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
description	String	A text describing a character
games	Array of Game IDs
gender	Gender Enum
mug_shot	Reference ID for Character Mug Shot	An image depicting a character
name	String
slug	String	A url-safe, unique, lower-case version of the name
species	Species Enum
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Character Enums

gender

name	value
Male	0
Female	1
Other	2

species

name	value
Human	1
Alien	2
Animal	3
Android	4
Unknown	5

Collection

from requests import post
response = post('https://api.igdb.com/v4/collections', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,games,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Collection, AKA Series

Request Path

https://api.igdb.com/v4/collections

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
games	Array of Game IDs	The games that are associated with this collection
name	String	Umbrella term for a collection of games
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Company

from requests import post
response = post('https://api.igdb.com/v4/companies', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields change_date,change_date_category,changed_company_id,checksum,country,created_at,description,developed,logo,name,parent,published,slug,start_date,start_date_category,updated_at,url,websites;'})
print ("response: %s" % str(response.json()))

Video game companies. Both publishers & developers

Request Path

https://api.igdb.com/v4/companies

field	type	description
change_date	Unix Time Stamp	The data when a company got a new ID
change_date_category	Change Date Category Enum
changed_company_id	Reference ID for Company	The new ID for a company that has gone through a merger or restructuring
checksum	uuid	Hash of the object
country	Integer	ISO 3166-1 country code
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
description	String	A free text description of a company
developed	Array of Game IDs	An array of games that a company has developed
logo	Reference ID for Company Logo	The company’s logo
name	String
parent	Reference ID for Company	A company with a controlling interest in a specific company
published	Array of Game IDs	An array of games that a company has published
slug	String	A url-safe, unique, lower-case version of the name
start_date	Unix Time Stamp	The date a company was founded
start_date_category	Start Date Category Enum
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item
websites	Array of Company Website IDs	The companies official websites

Company Enums

change_date_category

name	value
YYYYMMMMDD	0
YYYYMMMM	1
YYYY	2
YYYYQ1	3
YYYYQ2	4
YYYYQ3	5
YYYYQ4	6
TBD	7

start_date_category

name	value
YYYYMMMMDD	0
YYYYMMMM	1
YYYY	2
YYYYQ1	3
YYYYQ2	4
YYYYQ3	5
YYYYQ4	6
TBD	7

Company Logo

from requests import post
response = post('https://api.igdb.com/v4/company_logos', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

The logos of developers and publishers

Request Path

https://api.igdb.com/v4/company_logos

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Company Website

from requests import post
response = post('https://api.igdb.com/v4/company_websites', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,trusted,url;'})
print ("response: %s" % str(response.json()))

Company Website

Request Path

https://api.igdb.com/v4/company_websites

field	type	description
category	Category Enum	The service this website links to
checksum	uuid	Hash of the object
trusted	boolean
url	String	The website address (URL) of the item

Company Website Enums

category

name	value
official	1
wikia	2
wikipedia	3
facebook	4
twitter	5
twitch	6
instagram	8
youtube	9
iphone	10
ipad	11
android	12
steam	13
reddit	14
itch	15
epicgames	16
gog	17
discord	18

Cover

from requests import post
response = post('https://api.igdb.com/v4/covers', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,game,game_localization,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

The cover art of games

Request Path

https://api.igdb.com/v4/covers

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
game	Reference ID for Game	The game this cover is associated with. If it is empty then this cover belongs to a game_localization, which can be found under game_localization field
game_localization	Reference ID for Game Localization	The game localization this cover might be associated with
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

External Game

from requests import post
response = post('https://api.igdb.com/v4/external_games', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,countries,created_at,game,media,name,platform,uid,updated_at,url,year;'})
print ("response: %s" % str(response.json()))

Game IDs on other services

Request Path

https://api.igdb.com/v4/external_games

field	type	description
category	Category Enum	The id of the other service
checksum	uuid	Hash of the object
countries	Array of Integers	The ISO country code of the external game product.
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
game	Reference ID for Game	The IGDB ID of the game
media	Media Enum	The media of the external game.
name	String	The name of the game according to the other service
platform	Reference ID for Platform	The platform of the external game product.
uid	String	The other services ID for this game
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item
year	Integer	The year in full (2018)

External Game Enums

category

name	value
steam	1
gog	5
youtube	10
microsoft	11
apple	13
twitch	14
android	15
amazon_asin	20
amazon_luna	22
amazon_adg	23
epic_game_store	26
oculus	28
utomik	29
itch_io	30
xbox_marketplace	31
kartridge	32
playstation_store_us	36
focus_entertainment	37
xbox_game_pass_ultimate_cloud	54
gamejolt	55

media

name	value
digital	1
physical	2

Franchise

from requests import post
response = post('https://api.igdb.com/v4/franchises', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,games,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

A list of video game franchises such as Star Wars.

Request Path

https://api.igdb.com/v4/franchises

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
games	Array of Game IDs	The games that are associated with this franchise
name	String	The name of the franchise
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Game

from requests import post
response = post('https://api.igdb.com/v4/games', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields age_ratings,aggregated_rating,aggregated_rating_count,alternative_names,artworks,bundles,category,checksum,collection,cover,created_at,dlcs,expanded_games,expansions,external_games,first_release_date,follows,forks,franchise,franchises,game_engines,game_localizations,game_modes,genres,hypes,involved_companies,keywords,language_supports,multiplayer_modes,name,parent_game,platforms,player_perspectives,ports,rating,rating_count,release_dates,remakes,remasters,screenshots,similar_games,slug,standalone_expansions,status,storyline,summary,tags,themes,total_rating,total_rating_count,updated_at,url,version_parent,version_title,videos,websites;'})
print ("response: %s" % str(response.json()))

Video Games!

Request Path

https://api.igdb.com/v4/games

field	type	description
age_ratings	Array of Age Rating IDs	The PEGI rating
aggregated_rating	Double	Rating based on external critic scores
aggregated_rating_count	Integer	Number of external critic scores
alternative_names	Array of Alternative Name IDs	Alternative names for this game
artworks	Array of Artwork IDs	Artworks of this game
bundles	Array of Game IDs	The bundles this game is a part of
category	Category Enum	The category of this game
checksum	uuid	Hash of the object
collection	Reference ID for Collection	The series the game belongs to
cover	Reference ID for Cover	The cover of this game
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
dlcs	Array of Game IDs	DLCs for this game
expanded_games	Array of Game IDs	Expanded games of this game
expansions	Array of Game IDs	Expansions of this game
external_games	Array of External Game IDs	External IDs this game has on other services
first_release_date	Unix Time Stamp	The first release date for this game
follows	Integer	Number of people following a game
forks	Array of Game IDs	Forks of this game
franchise	Reference ID for Franchise	The main franchise
franchises	Array of Franchise IDs	Other franchises the game belongs to
game_engines	Array of Game Engine IDs	The game engine used in this game
game_localizations	Array of Game Localization IDs	Supported game localizations for this game. A region can have at most one game localization for a given game
game_modes	Array of Game Mode IDs	Modes of gameplay
genres	Array of Genre IDs	Genres of the game
hypes	Integer	Number of follows a game gets before release
involved_companies	Array of Involved Company IDs	Companies who developed this game
keywords	Array of Keyword IDs	Associated keywords
language_supports	Array of Language Support IDs	Supported Languages for this game
multiplayer_modes	Array of Multiplayer Mode IDs	Multiplayer modes for this game
name	String
parent_game	Reference ID for Game	If a DLC, expansion or part of a bundle, this is the main game or bundle
platforms	Array of Platform IDs	Platforms this game was released on
player_perspectives	Array of Player Perspective IDs	The main perspective of the player
ports	Array of Game IDs	Ports of this game
rating	Double	Average IGDB user rating
rating_count	Integer	Total number of IGDB user ratings
release_dates	Array of Release Date IDs	Release dates of this game
remakes	Array of Game IDs	Remakes of this game
remasters	Array of Game IDs	Remasters of this game
screenshots	Array of Screenshot IDs	Screenshots of this game
similar_games	Array of Game IDs	Similar games
slug	String	A url-safe, unique, lower-case version of the name
standalone_expansions	Array of Game IDs	Standalone expansions of this game
status	Status Enum	The status of the games release
storyline	String	A short description of a games story
summary	String	A description of the game
tags	Array of Tag Numbers	Related entities in the IGDB API
themes	Array of Theme IDs	Themes of the game
total_rating	Double	Average rating based on both IGDB user and external critic scores
total_rating_count	Integer	Total number of user and external critic scores
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item
version_parent	Reference ID for Game	If a version, this is the main game
version_title	String	Title of this version (i.e Gold edition)
videos	Array of Game Video IDs	Videos of this game
websites	Array of Website IDs	Websites associated with this game

Game Enums

category

name	value
main_game	0
dlc_addon	1
expansion	2
bundle	3
standalone_expansion	4
mod	5
episode	6
season	7
remake	8
remaster	9
expanded_game	10
port	11
fork	12
pack	13
update	14

status

name	value
released	0
alpha	2
beta	3
early_access	4
offline	5
cancelled	6
rumored	7
delisted	8

Game Engine

from requests import post
response = post('https://api.igdb.com/v4/game_engines', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,companies,created_at,description,logo,name,platforms,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Video game engines such as unreal engine.

Request Path

https://api.igdb.com/v4/game_engines

field	type	description
checksum	uuid	Hash of the object
companies	Array of Company IDs	Companies who used this game engine
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
description	String	Description of the game engine
logo	Reference ID for Game Engine Logo	Logo of the game engine
name	String	Name of the game engine
platforms	Array of Platform IDs	Platforms this game engine was deployed on
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Game Engine Logo

from requests import post
response = post('https://api.igdb.com/v4/game_engine_logos', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

The logos of game engines

Request Path

https://api.igdb.com/v4/game_engine_logos

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Game Localization

from requests import post
response = post('https://api.igdb.com/v4/game_localizations', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,cover,created_at,game,name,region,updated_at;'})
print ("response: %s" % str(response.json()))

Game localization for a game

Request Path

https://api.igdb.com/v4/game_localizations

field	type	description
checksum	uuid	Hash of the object
cover	Reference ID for Cover	The cover of this game localization
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
game	Reference ID for Game	The Game the localization belongs to
name	String
region	Reference ID for Region	The Region of the localization
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Game Mode

from requests import post
response = post('https://api.igdb.com/v4/game_modes', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Single player, Multiplayer etc

Request Path

https://api.igdb.com/v4/game_modes

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String	The name of the game mode
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Game Version Feature

from requests import post
response = post('https://api.igdb.com/v4/game_version_features', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,description,position,title,values;'})
print ("response: %s" % str(response.json()))

Features and descriptions of what makes each version/edition different from the main game

Request Path

https://api.igdb.com/v4/game_version_features

field	type	description
category	Category Enum	The category of the feature description
checksum	uuid	Hash of the object
description	String	The description of the feature
position	Integer	Position of this feature in the list of features
title	String	The title of the feature
values	Array of Game Version Feature Value IDs	The bool/text value of the feature

Game Version Feature Enums

category

name	value
boolean	0
description	1

Game Version Feature Value

from requests import post
response = post('https://api.igdb.com/v4/game_version_feature_values', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,game,game_feature,included_feature,note;'})
print ("response: %s" % str(response.json()))

The bool/text value of the feature

Request Path

https://api.igdb.com/v4/game_version_feature_values

field	type	description
checksum	uuid	Hash of the object
game	Reference ID for Game	The version/edition this value refers to
game_feature	Reference ID for Game Version Feature	The id of the game feature
included_feature	Included Feature Enum	The boole value of this feature
note	String	The text value of this feature

Game Version Feature Value Enums

included_feature

name	value
NOT_INCLUDED	0
INCLUDED	1
PRE_ORDER_ONLY	2

Game Video

from requests import post
response = post('https://api.igdb.com/v4/game_videos', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,game,name,video_id;'})
print ("response: %s" % str(response.json()))

A video associated with a game

Request Path

https://api.igdb.com/v4/game_videos

field	type	description
checksum	uuid	Hash of the object
game	Reference ID for Game	The game this video is associated with
name	String	The name of the video
video_id	String	The external ID of the video (usually youtube)

Genre

from requests import post
response = post('https://api.igdb.com/v4/genres', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Genres of video game

Request Path

https://api.igdb.com/v4/genres

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Involved Company

from requests import post
response = post('https://api.igdb.com/v4/involved_companies', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,company,created_at,developer,game,porting,publisher,supporting,updated_at;'})
print ("response: %s" % str(response.json()))

Request Path

https://api.igdb.com/v4/involved_companies

field	type	description
checksum	uuid	Hash of the object
company	Reference ID for Company
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
developer	boolean
game	Reference ID for Game
porting	boolean
publisher	boolean
supporting	boolean
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Keyword

from requests import post
response = post('https://api.igdb.com/v4/keywords', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Keywords are words or phrases that get tagged to a game such as “world war 2” or “steampunk”.

Request Path

https://api.igdb.com/v4/keywords

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Language

from requests import post
response = post('https://api.igdb.com/v4/languages', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,locale,name,native_name,updated_at;'})
print ("response: %s" % str(response.json()))

Languages that are used in the Language Support endpoint.

Request Path

https://api.igdb.com/v4/languages

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
locale	String	The combination of Language code and Country code
name	String	The English name of the Language
native_name	String	The Native Name of the Language
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Language Support

from requests import post
response = post('https://api.igdb.com/v4/language_supports', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,game,language,language_support_type,updated_at;'})
print ("response: %s" % str(response.json()))

Games can be played with different languages for voice acting, subtitles, or the interface language.

Request Path

https://api.igdb.com/v4/language_supports

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
game	Reference ID for Game
language	Reference ID for Language
language_support_type	Reference ID for Language Support Type
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Multiplayer Mode

from requests import post
response = post('https://api.igdb.com/v4/multiplayer_modes', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields campaigncoop,checksum,dropin,game,lancoop,offlinecoop,offlinecoopmax,offlinemax,onlinecoop,onlinecoopmax,onlinemax,platform,splitscreen,splitscreenonline;'})
print ("response: %s" % str(response.json()))

Data about the supported multiplayer types

Request Path

https://api.igdb.com/v4/multiplayer_modes

field	type	description
campaigncoop	boolean	True if the game supports campaign coop
checksum	uuid	Hash of the object
dropin	boolean	True if the game supports drop in/out multiplayer
game	Reference ID for Game	The game this multiplayer mode is associated with
lancoop	boolean	True if the game supports LAN coop
offlinecoop	boolean	True if the game supports offline coop
offlinecoopmax	Integer	Maximum number of offline players in offline coop
offlinemax	Integer	Maximum number of players in offline multiplayer
onlinecoop	boolean	True if the game supports online coop
onlinecoopmax	Integer	Maximum number of online players in online coop
onlinemax	Integer	Maximum number of players in online multiplayer
platform	Reference ID for Platform	The platform this multiplayer mode refers to
splitscreen	boolean	True if the game supports split screen, offline multiplayer
splitscreenonline	boolean	True if the game supports split screen, online multiplayer

Language Support Type

from requests import post
response = post('https://api.igdb.com/v4/language_support_types', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,updated_at;'})
print ("response: %s" % str(response.json()))

Language Support Types contains the identifiers for the support types that Language Support uses.

Request Path

https://api.igdb.com/v4/language_support_types

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Game Version

from requests import post
response = post('https://api.igdb.com/v4/game_versions', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,features,game,games,updated_at,url;'})
print ("response: %s" % str(response.json()))

Details about game editions and versions.

Request Path

https://api.igdb.com/v4/game_versions

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
features	Array of Game Version Feature IDs	Features and descriptions of what makes each version/edition different from the main game
game	Reference ID for Game	The game these versions/editions are of
games	Array of Game IDs	Game Versions and Editions
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Platform

from requests import post
response = post('https://api.igdb.com/v4/platforms', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields abbreviation,alternative_name,category,checksum,created_at,generation,name,platform_family,platform_logo,slug,summary,updated_at,url,versions,websites;'})
print ("response: %s" % str(response.json()))

The hardware used to run the game or game delivery network

Request Path

https://api.igdb.com/v4/platforms

field	type	description
abbreviation	String	An abbreviation of the platform name
alternative_name	String	An alternative name for the platform
category	Category Enum	A physical or virtual category of the platform
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
generation	Integer	The generation of the platform
name	String	The name of the platform
platform_family	Reference ID for Platform Family	The family of platforms this one belongs to
platform_logo	Reference ID for Platform Logo	The logo of the first Version of this platform
slug	String	A url-safe, unique, lower-case version of the name
summary	String	The summary of the first Version of this platform
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item
versions	Array of Platform Version IDs	Associated versions of this platform
websites	Array of Platform Website IDs	The main website

Platform Enums

category

name	value
console	1
arcade	2
platform	3
operating_system	4
portable_console	5
computer	6

Platform Logo

from requests import post
response = post('https://api.igdb.com/v4/platform_logos', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

Logo for a platform

Request Path

https://api.igdb.com/v4/platform_logos

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Platform Family

from requests import post
response = post('https://api.igdb.com/v4/platform_families', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,name,slug;'})
print ("response: %s" % str(response.json()))

A collection of closely related platforms

Request Path

https://api.igdb.com/v4/platform_families

field	type	description
checksum	uuid	Hash of the object
name	String	The name of the platform family
slug	String	A url-safe, unique, lower-case version of the name

Platform Version

from requests import post
response = post('https://api.igdb.com/v4/platform_versions', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,companies,connectivity,cpu,graphics,main_manufacturer,media,memory,name,online,os,output,platform_logo,platform_version_release_dates,resolutions,slug,sound,storage,summary,url;'})
print ("response: %s" % str(response.json()))

Request Path

https://api.igdb.com/v4/platform_versions

field	type	description
checksum	uuid	Hash of the object
companies	Array of Platform Version Company IDs	Who developed this platform version
connectivity	String	The network capabilities
cpu	String	The integrated control processing unit
graphics	String	The graphics chipset
main_manufacturer	Reference ID for Platform Version Company	Who manufactured this version of the platform
media	String	The type of media this version accepted
memory	String	How much memory there is
name	String	The name of the platform version
os	String	The operating system installed on the platform version
output	String	The output video rate
platform_logo	Reference ID for Platform Logo	The logo of this platform version
platform_version_release_dates	Array of Platform Version Release Date IDs	When this platform was released
resolutions	String	The maximum resolution
slug	String	A url-safe, unique, lower-case version of the name
sound	String	The sound chipset
storage	String	How much storage there is
summary	String	A short summary
url	String	The website address (URL) of the item

Platform Version Company

from requests import post
response = post('https://api.igdb.com/v4/platform_version_companies', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,comment,company,developer,manufacturer;'})
print ("response: %s" % str(response.json()))

A platform developer

Request Path

https://api.igdb.com/v4/platform_version_companies

field	type	description
checksum	uuid	Hash of the object
comment	String	Any notable comments about the developer
company	Reference ID for Company	The company responsible for developing this platform version
developer	boolean
manufacturer	boolean

Platform Version Release Date

from requests import post
response = post('https://api.igdb.com/v4/platform_version_release_dates', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,created_at,date,human,m,platform_version,region,updated_at,y;'})
print ("response: %s" % str(response.json()))

A handy endpoint that extends platform release dates. Used to dig deeper into release dates, platforms and versions.

Request Path

https://api.igdb.com/v4/platform_version_release_dates

field	type	description
category	Category Enum	The format of the release date
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
date	Unix Time Stamp	The release date
human	String	A human readable version of the release date
m	Integer	The month as an integer starting at 1 (January)
platform_version	Reference ID for Platform Version	The platform this release date is for
region	Region Enum	The region of the release
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
y	Integer	The year in full (2018)

Platform Version Release Date Enums

category

name	value
YYYYMMMMDD	0
YYYYMMMM	1
YYYY	2
YYYYQ1	3
YYYYQ2	4
YYYYQ3	5
YYYYQ4	6
TBD	7

region

name	value
europe	1
north_america	2
australia	3
new_zealand	4
japan	5
china	6
asia	7
worldwide	8
korea	9
brazil	10

Platform Website

from requests import post
response = post('https://api.igdb.com/v4/platform_websites', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,trusted,url;'})
print ("response: %s" % str(response.json()))

The main website for the platform

Request Path

https://api.igdb.com/v4/platform_websites

field	type	description
category	Category Enum	The service this website links to
checksum	uuid	Hash of the object
trusted	boolean
url	String	The website address (URL) of the item

Platform Website Enums

category

name	value
official	1
wikia	2
wikipedia	3
facebook	4
twitter	5
twitch	6
instagram	8
youtube	9
iphone	10
ipad	11
android	12
steam	13
reddit	14
discord	15
google_plus	16
tumblr	17
linkedin	18
pinterest	19
soundcloud	20

Player Perspective

from requests import post
response = post('https://api.igdb.com/v4/player_perspectives', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Player perspectives describe the view/perspective of the player in a video game.

Request Path

https://api.igdb.com/v4/player_perspectives

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Region

from requests import post
response = post('https://api.igdb.com/v4/regions', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,created_at,identifier,name,updated_at;'})
print ("response: %s" % str(response.json()))

Region for game localization

Request Path

https://api.igdb.com/v4/regions

field	type	description
category	String	This can be either ’locale’ or ‘continent’
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
identifier	String	This is the identifier of each region
name	String
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Screenshot

from requests import post
response = post('https://api.igdb.com/v4/screenshots', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alpha_channel,animated,checksum,game,height,image_id,url,width;'})
print ("response: %s" % str(response.json()))

Screenshots of games

Request Path

https://api.igdb.com/v4/screenshots

field	type	description
alpha_channel	boolean
animated	boolean
checksum	uuid	Hash of the object
game	Reference ID for Game	The game this video is associated with
height	Integer	The height of the image in pixels
image_id	String	The ID of the image used to construct an IGDB image link
url	String	The website address (URL) of the item
width	Integer	The width of the image in pixels

Release Date

from requests import post
response = post('https://api.igdb.com/v4/release_dates', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,created_at,date,game,human,m,platform,region,status,updated_at,y;'})
print ("response: %s" % str(response.json()))

A handy endpoint that extends game release dates. Used to dig deeper into release dates, platforms and versions.

Request Path

https://api.igdb.com/v4/release_dates

field	type	description
category	Category Enum	The format category of the release date
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
date	Unix Time Stamp	The date of the release
game	Reference ID for Game
human	String	A human readable representation of the date
m	Integer	The month as an integer starting at 1 (January)
platform	Reference ID for Platform	The platform of the release
region	Region Enum	The region of the release
status	Reference ID for Release Date Status	The status of the release.
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
y	Integer	The year in full (2018)

Release Date Enums

category

name	value
YYYYMMMMDD	0
YYYYMMMM	1
YYYY	2
YYYYQ1	3
YYYYQ2	4
YYYYQ3	5
YYYYQ4	6
TBD	7

region

name	value
europe	1
north_america	2
australia	3
new_zealand	4
japan	5
china	6
asia	7
worldwide	8
korea	9
brazil	10

Search

from requests import post
response = post('https://api.igdb.com/v4/search', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields alternative_name,character,checksum,collection,company,description,game,name,platform,published_at,test_dummy,theme;'})
print ("response: %s" % str(response.json()))

Request Path

https://api.igdb.com/v4/search

field	type	description
alternative_name	String
character	Reference ID for Character
checksum	uuid	Hash of the object
collection	Reference ID for Collection
company	Reference ID for Company
description	String
game	Reference ID for Game
name	String
platform	Reference ID for Platform
published_at	Unix Time Stamp	The date this item was initially published by the third party
test_dummy	Reference ID for Test Dummy
theme	Reference ID for Theme

Theme

from requests import post
response = post('https://api.igdb.com/v4/themes', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,name,slug,updated_at,url;'})
print ("response: %s" % str(response.json()))

Video game themes

Request Path

https://api.igdb.com/v4/themes

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
name	String
slug	String	A url-safe, unique, lower-case version of the name
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database
url	String	The website address (URL) of the item

Release Date Status

from requests import post
response = post('https://api.igdb.com/v4/release_date_statuses', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields checksum,created_at,description,name,updated_at;'})
print ("response: %s" % str(response.json()))

An endpoint to provide definition of all of the current release date statuses.

Request Path

https://api.igdb.com/v4/release_date_statuses

field	type	description
checksum	uuid	Hash of the object
created_at	Unix Time Stamp	Date this was initially added to the IGDB database
description	String	The description of the release date status.
name	String	The name of the release date status.
updated_at	Unix Time Stamp	The last date this entry was updated in the IGDB database

Website

from requests import post
response = post('https://api.igdb.com/v4/websites', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'},'data': 'fields category,checksum,game,trusted,url;'})
print ("response: %s" % str(response.json()))

A website url, usually associated with a game

Request Path

https://api.igdb.com/v4/websites

field	type	description
category	Category Enum	The service this website links to
checksum	uuid	Hash of the object
game	Reference ID for Game	The game this website is associated with
trusted	boolean
url	String	The website address (URL) of the item

Website Enums

category

name	value
official	1
wikia	2
wikipedia	3
facebook	4
twitter	5
twitch	6
instagram	8
youtube	9
iphone	10
ipad	11
android	12
steam	13
reddit	14
itch	15
epicgames	16
gog	17
discord	18

Webhooks

What?

Webhooks allow us to push data to you when it is added, updated, or deleted. Instead of polling the API for changes, you can listen on your own HTTP endpoint (Webhook) and we will deliver the data to you.

Using Webhooks will ensure that your data is always up to date!

from requests import post
response = post('https://api.igdb.com/v4/ENDPOINT/webhooks/', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token', 'Content-Type': 'application/x-www-form-urlencoded'}, 'data': 'url=YOUR_WEBHOOK_URL&secret=YOUR_WEBHOOK_SECRET&method=create'})
print ("response: %s" % str(response.json()))

How to register your webhook

To register a new webhook you need to send a POST request to ENDPOINT/webhooks. The endpoint is required as it specifies what type of data you want from your webhook.

The post request should contain x-www-form-urlencoded body with three parameters:

url this is your prepared url that is ready to accept data from us.
method this is the type of data you are expecting to your url, there are three types of methods
- create, sends new items from the API
- delete, sends deleted items from the API
- update, sends updated items from the API
secret this is your “secret” password for your webhook. Every request from the webhook service will have your secret in the header called X-Secret.

// Example response upon registering your webhook
{ 
    "id": WEBHOOK_ID, // A unique ID for the webhook
    "url": "YOUR_WEBHOOK_URL", // Your chosen URL
    "category": 1, // Based on the endpoint you chose
    "sub_category": 0, // Based on your method (can be 0, 1, 2)
    "active": true, // Is the webhook currently active
    "api_key": "YOUR_CLIENT_ID", // Displays the api key the webhook is connected to
    "secret": "YOUR_SECRET", // Your chosen secret
    "created_at": "2018-11-25T23:00:00.000Z", // Created at date
    "updated_at": "2018-11-25T23:00:00.000Z" // Updated at date
}

Registering your webhook in Postman Once your webhook is registered you will receive a response with the new webhook object

That’s it!
The data will now be sent to your webhook in the body of a post request. The data is a single json object representing an unexpanded entity.Tip! Always validate your received data with you secret!

Webhooks have an active field, as you can see in the JSON response above, The service will keep the webhook active as long as the webhook url is capable of receiving data from the service. If the url fails 5 times the webhook will be set to inactive (active: false) and the service will stop to send data to this webhook.

Reactivating the webhook is done by re-registering it, this will update the active status to true.Tip! Re-register your webhook on service start, to make sure it’s always active!

Viewing your webhooks

You can always get information about your webhooks from the API. To get ALL of your registered webhooks simply send a GET request to /webhooks, without the endpoint. This will return a JSON array of your webhooks

To get information about a specific webhook you can make a GET request with the webhook id to /webhooks/WEBHOOK_ID, without the endpoint. This will return the webhook of that id.

# Get ALL registered Webhooks
from requests import post
response = get('https://api.igdb.com/v4/webhooks/', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'}})
print ("response: %s" % str(response.json()))

Viewing your webhooks

To get information about a specific webhook you can make a GET request with the webhook id to /webhooks/WEBHOOK_ID, without the endpoint. This will return the webhook of that id.

from requests import post
response = delete('https://api.igdb.com/v4/webhooks/WEBHOOK_ID', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'}})
print ("response: %s" % str(response.json()))

Removing a Webhook

To remove your existing webhook you need to send a DELETE request to /webhooks/WEBHOOK_ID, without the endpoint. The Webhook id is returned during the registration process or can be found with a GET request to /webhooks/.

The DELETE request will receive the deleted webhook as confirmation.

from requests import post
response = post('https://api.igdb.com/v4/ENDPOINT/webhooks/test/WEBHOOK_ID?entityId=ENTITY_ID', **{'headers': {'Client-ID': 'Client ID', 'Authorization': 'Bearer access_token'}})
print ("response: %s" % str(response.json()))

Testing

To make sure you have everything setup just right we have a test endpoint for the webhook service. This endpoint will send an object of your choosing to your newly created webhook.

Send a POST request to ENDPOINT/webhooks/test/WEBHOOK_ID?entityId=ENTITY_ID. The entity id is the id of the object from the endpoint you wish to test with, example:

POST to games/webhooks/test/42?entityId=1337:
This request will send the game object with id 1337 to your webhook url.

Handling Webhooks on your end

When recieveing the webhook message on your end what we expect is to recieve a 200 OK back within 15 seconds. If the endpoint takes longer than 15 seconds to respond the event will be deemed as a failed event, fail 5 times and the webhook will be set to inactive.

CORS Proxy

CORS

If you intend to use our API from your website you will encounter an issue with security; namely CORS Cross-Origin Resource Sharing.

There are security mechanisms in place by all major browsers to stop websites from accessing other domains without getting explicit permission. This is done through HTTP headers. So, for example, amazinggameswebsite.com cannot access api.igdb.com without us explicitly stating in the HTTP headers (Access-Control-Allow-Origin) that they have permission.

We do not offer the configuration of these headers as a service, so any browser-based javascript and mobile javascript frameworks will not be able to communicate directly with the IGDB API.

Workaround

See the guide for setting up a proxy or set up a proxy using CORS Anywhere

Proxy

There are a number of reasons why you may wish to proxy requests to the IGDB API.

To have a backend that keeps track of your Oauth Application Tokens
Caching requests to the API for better performance
Enable application logging to track/debug usage
Enable CORS between the proxy and applications

How do I set up a proxy?

Proxies can be complex, but to get you started we have a simple guide to get you up and running quickly through AWS.

We have provided a single link that will let you deploy an AWS Api Gateway in your own AWS account that will serve as a proxy. This Stack will also handle your Access Token rotations automatically for you, so you don’t need to think about that.

What will it cost?

AWS has a very generous free-tier for new users and the services used in the provided solution (Api Gateway, Secrets Manager, Lambda). Please use the AWS Pricing Calculator to gauge how much this will cost you before setting up your Stack.

Stack Setup

Prerequisites: You need to have an AWS account with permissions to deploy CloudFormation stacks.

Click this link to get started.
Go over the Stack Details
- You have to agree to the terms and conditions.
- You have to fill in your Twitch Application Credentials
- It’s recommended to protect your proxy by enabling Api Keys
- NOTE: Enabling Caching will come with extra costs as this is NOT covered by the Free-tier
- NOTE: Enabling CORS will ‘break’ Protobuf responses, some libraries might not work.
Click Next
Configure Stack Options – Nothing is required here, you can click Next
Verify Settings, click the checkbox at the bottom, then click “Create Stack”
You will now see the “Stack Details” screen, hit the refresh arrow button on the right until your stack name on the left says “UPDATE_COMPLETE”
Click on the “Outputs” tab to get the URL to your new proxy.
- The “Resources” tab summarises all the services deployed on your account.
- The “Template” tab displays the template used for deployment.
You can now post requests to your URL and it will proxy to our API
- If you enabled Api Keys you will need to specify the header x-api-key and the key can be found via a link through the “Resources” tab for “ApiDefaultKey”

Important Note: The url generated will end in production, so you will want to post to
https://<your-api-gateway-unique-id>.execute-api.us-west-2.amazonaws.com/production/v4/games

What’s next?

You can do a lot of things via API Gateway.

You can improve the security of your proxy by creating another sort of Authentication, to prevent others from using up your RPS quota.
You can also setup your own Domain name and SSL with Route53
You can modify the path of the proxy to have it serve as the front-end to your own APIs
- Perform a calculation? Lambda Integration
- Just want to store some records? DynamoDB Integration
- Want users to be able to upload/download files? S3 Integration
Enable request logging

Alternatives

CORS: Setup a proxy using CORS Anywhere

Reference

Images

Note: Images that are removed or replaced from IGDB.com exist for 30 days before they are removed. Keep that in mind when designing cache logic.

Examples

Address:
- https://api.igdb.com/v4/games/
Body:
- fields screenshots.*; where id = 1942;

Here we retrieve the image properties of the game with the id “1942”

[{
	"id": 1942,
	"screenshots": [{
			"id": 9742,
			"game": 1942,
			"height": 1080,
			"image_id": "mnljdjtrh44x4snmierh",
			"url": "//images.igdb.com/igdb/image/upload/t_thumb/mnljdjtrh44x4snmierh.jpg",
			"width": 1920
		},
		{
			"id": 9743,
			"game": 1942,
			"height": 1080,
			"image_id": "em1y2ugcwy2myuhvb9db",
			"url": "//images.igdb.com/igdb/image/upload/t_thumb/em1y2ugcwy2myuhvb9db.jpg",
			"width": 1920
		}
	]
}]

Response example on the right –>

Image url structure:

https://images.igdb.com/igdb/image/upload/t_screenshot_med_2x/dfgkfivjrhcksyymh9vw.jpg

Break down:

https://images.igdb.com/igdb/image/upload/t_{size}/{hash}.jpg

size is one of the interchangeable size types listed below. hash is the id of the image. The image sizes are all maximum size but by appending _2x to any size, you can get retina (DPR 2.0) sizes (cover_small_2x).

Name	Size	Extra
cover_small	90 x 128	Fit
screenshot_med	569 x 320	Lfill, Center gravity
cover_big	264 x 374	Fit
logo_med	284 x 160	Fit
screenshot_big	889 x 500	Lfill, Center gravity
screenshot_huge	1280 x 720	Lfill, Center gravity
thumb	90 x 90	Thumb, Center gravity
micro	35 x 35	Thumb, Center gravity
720p	1280 x 720	Fit, Center gravity
1080p	1920 x 1080	Fit, Center gravity

Fields

What?

Fields are properties of an entity. For example, a Game field would be genres or release_dates. Some fields have properties of their own, for example, the genres field has the property name.

Where?

Fields can be used on any entity that has sub-properties such as Games, Companies, People etc.

How?

Fields are requested in a comma separated list. For example, to get some information for some Games, Genres, Themes or anything else, you could request it like this:

Apicalypse

where id = (4356,189,444);
fields name,release_dates,genres.name,rating

Legacy Parameters

/games/4356,189,444?fields=name,release_dates,genres.name,rating

Note in Apicalypse the name property of genres can be accessed directly with a dot (genres.name).

A full list of fields can be obtained by passing a * as a field. Alternatively you can use the meta postfix: /games/meta to get a list of all fields.

Shorthand

Another way of writing fields is to use the shorthand f which achieves the same result.

f name,release_dates,genres.name,rating;
w id = (4356,189,444);

Exclude

What?

Exclude is a complement to the regular fields which allows you to request all fields with the exception of any numbers of fields specified with exclude.

How?

Fields to be excluded are specified as a comma separated list. For example, to get all fields excpect for screenshots, you could request it like this:

Apicalypse

fields *;
exclude screenshots;

Shorthand

Another way of writing exclude is to use the shorthand x which achieves the same result.

f *;
x screenshots;

Expander

What?

Some fields are actually ids pointing to another endpoint. The expander feature is a convenient way to go into these other endpoints and access more information from them in the same query, instead of having to do multiple queries.

Where?

Expands are specificed among the regular fields in the body of the query.

How?

Fields can be expanded with a dot followed by the fields you want to access from a certain endpoint.

Examples

In the example below we request the fields name and genres for the game The Witcher 3 with id 1942.

fields name,genres;
where id = 1942;

But this query will only return ids for the genres, which can be seen in the first response to the right:

"First example response showing genre ids"
[
    {
        "id ": 1942,
        "genres":[
            12,
            31
        ],
        "name": "The Witcher 3: Wild Hunt"
    }
]

For some use cases the id is all that is needed, but other times more data is needed, This is when the expander features comes in handy.

fields name,genres.name;
where id = 1942;

This example with expander retrieves the name of each genre which can be seen in the second response to the right.

"Second example response showing genre ids and name"
[
    {
        "id": 1942,
        "genres": [
            {
                "id": 12,
                "name": "Role-playing (RPG)"
            },
            {
                "id": 31,
                "name": "Adventure"
            }
        ],
        "name": "The Witcher 3: Wild Hunt"
    }
]

And lastly lets take a look at how you can use a wildcard character * to retrieve all data from genres in the previous example.

fields name,genres.*;
where id = 1942;

See the third response to the right where all available data for each genre is included in the response.

"Third example response showing all available genre data"
[
    {
        "id": 1942,
        "genres": [
            {
                "id": 12,
                "created_at": 1297555200,
                "name": "Role-playing (RPG)",
                "slug": "role-playing-rpg",
                "updated_at": 1323216000,
                "url": "https://www.igdb.com/genres/role-playing-rpg"
            },
            {
                "id": 31,
                "created_at": 1323561600,
                "name": "Adventure",
                "slug": "adventure",
                "updated_at": 1323561600,
                "url": "https://www.igdb.com/genres/adventure"
            }
        ],
        "name": "The Witcher 3: Wild Hunt"
    }
]

Filters

What?

Filters are used to sift through results to get what you want. You can exclude and include results based on their properties. For example you could remove all Games where the rating was below 80 (where rating >= 80).

How?

Filters are parameter arrays so must be added using special keys like this:

Address:
- https://api.igdb.com/v4/games/
Body:
- search “zelda”; where rating >= 80 & release_dates.date > 631152000;

Where?

Filters can be used on any entity that has sub-properties such as Games, Companies, People etc.

Available Postfixes

= Equal: Exact match equal.
!= Not Equal: Exact match equal.
> Greater than (works only on numbers).
>= Greater than or equal to (works only on numbers).
< Less than (works only on numbers).
<= Less than or equal to (works only on numbers).
= "Your input string"* Prefix: Exact match on the beginning of the string, can end with anything. (Case sensitive).
~ "Your input string"* Prefix: Exact match on the beginning of the string, can end with anything. (Case insensitive).
= *"Your input string" Postfix: Exact match at the end of the string, can start with anything. (Case sensitive).
~ *"Your input string" Postfix: Exact match at the end of the string, can start with anything. (Case insensitive).
= *"Your input string"* Infix Exact match in the middle of the string, can start and end with anything. (Case sensitive).
~ *"Your input string"* Infix Exact match in the middle of the string, can start and end with anything. (Case insensitive).
!= null The value is not null.
= null The value is null.
[V1,V2,...Vn] The value exists within the (comma separated) array (AND between values).
![V1,V2,...Vn] The values must not exist within the (comma separated) array (AND between values).
(V1,V2,...Vn) The value has any within the (comma separated) array (OR between values).
!(V1,V2,...Vn) The values must not exist within the (comma separated) array (OR between values).
{V1,V2,...V2} Exact match on arrays. (Does not work on ids, strings, etc).

Examples

Filter by multiple platforms

To get games that are released on PS4 OR XBOX ONE OR PC

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where release_dates.platform = (48,49,6);

Similarly if you want games released on PS4 AND XBOX ONE AND PC

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where release_dates.platform = [48,49,6];

If you want games released only on PC

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where release_dates.platform = 6;

And if you want games released for PC OR any other platform

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where release_dates.platform = (6);

Combining Multiple Filters

It is possible to to use logical operators between filters, which could look something like this:

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name,platforms,genres.name; where (platforms = [6,48] & genres = 13) | (platforms = [130,48] & genres = 12);

The response from this example query will be games that fulfil one or both of two sets or requirements:

Games released for for both PC (6), and PS4 (48) and also has the genre simulator (13).
Games released for for both Switch (130), and PS4 (48) and also has the genre Role-Playing (13).

Prefix, Postfix and Infix

Prefix

Filtering for game names beginning with “Super” (this will return games such as for example Super Mario World)

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where name = "Super"*;

Postfix

Filtering for game names ending with with “World” (this will also return games such as for example Super Mario World)

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where name = *"World";

Infix

Filtering for game names containing the string “Smash” anywhere (this will return games such as for example Super Smash Bros)

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where name = *"Smash"*;

case insensitive version

Filtering for game names containing the string “Smash” (this will return games such as for example Super Smash Bros)

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where name ~ *"Smash"*;

Removing erotic games from API responses

Some queries may return games with erotic themes. All erotic games in the database has the theme ’erotic’ (id = 42). So by adding a simple filter like the one below you can remove them from your responses.

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name; where themes != (42);

Sorting

What?

Sorting is used to order results by a specific field.

How?

You can order results like this:

Address:
- https://api.igdb.com/v4/games/
Body:
- sort release_dates.date desc; where rating >= 80;

Notice the appended :desc (descending) which could also be :asc (ascending) if required.

Order by rating

Rating parameter for games. You can access it like this:

Address:
- https://api.igdb.com/v4/games/
Body:
- fields name,rating; sort rating desc; where rating != null;

Where?

Ordering can be used on any entity.

Search

What?

Search based on name, results are sorted by similarity to the given search string.

Where?

Searchable endpoints:

Characters
Collections
Games
People
Platforms
Themes

How?

You specify which endpoint to search through in the Address field of your request. The search string is then entered in the body of the request by typing search, blank space followed by the string you wish to search for.

Address:
- https://api.igdb.com/v4/games/
Body:
- search “zelda”;

Pagination

Here is an example for how to use limit. The default limit is 10. The maximum value you can set for limit is 500.

Address:
- https://api.igdb.com/v4/platforms/
Body:
- limit 33;

There is also an offset. This will start the list at position 22 and give 33 results.

Address:
- https://api.igdb.com/v4/platforms/
Body:
- limit 33; offset 22;

Protocol Buffers

Google Protocol Buffers is a language neutral method for serializing structured data.
The IGDB API supports responses in this format so you do not have to write your own serialization libraries, but instead you could just generate one.
Since this is langage neutral it is supported by a variatey of languages.

How?

Generate the objects in your language of choise with our own Protobuf file, here
This file contains the mapping of the entire IGDB API and can be used to generate wrappers, code and tooling in any programming language.
The protobuf file is created in accordance with the proto3 specification

There are plenty of examples on how to do this Online and on the Protobuf Site.

Where?

To start recieving protobuf compatible responses from then api all you need to do is add .pb at the end of your request:
https://api.igdb.com/v4/games.pb
Then use your generated files to parse the response into the expected object.

Tag Numbers

Tag numbers are automatically generated numbers which provide a compact and fast way to do complex filtering on the IGDB API. The number calculation can be easily achieved with any programming language.

The basis of the calculation is a 32bit integer, where the first 4 bits contain the object type ID, and the remaining 28 bits represent the ID of the object we are generating the tag number for.

Using this method a flat index of custom object ‘hashes’ can be maintained in which index the search and filtering is faster than using conventional methods.

Currently the following object types use tags:

Type ID	Name
0	Theme
1	Genre
2	Keyword
3	Game
4	Player Perspective

Let’s see two examples for tag number calculation.

// Javascript
const genreTypeID = 1; // The type ID from the table above
const shooterGenreID = 5; // The Shooter genre's ID, coming from the genres endpoint.
let tagNumber = genreTypeID << 28; // Bit-shifting the genre's type ID by 28 bits, ensuring that it will get into the first four bits. The result will be 268435456
tagNumber |= shooterGenreID; // Adding the Shooter genre ID to the tag number with a bitwise OR operation. The result will be 268435461.

We try to find all the games which relate to the Shooter genre. The tag number generation in Javascript would look something like the example on the right.

Javascript example query:

Address:
- https://api.igdb.com/v4/games/
Body:
- where tags = (268435461);

# Python
keywordTypeID: 2 # The keyword's type ID from the table above/
keywordID: 148 # The ID of the 'moba' keyword
tagNumber: keywordTypeID << 28 # Bit-shifting the keywords's type ID by 28 bits, ensuring that it will get into the first four bits. The result will be 536870912
tagNumber |= keywordID # Adding the keyword ID to the tag number with a bitwise OR operation. The result will be 536871060.

Python example query:

Address:
- https://api.igdb.com/v4/games/
Body:
- where tags = (536871060);

Multi-Query

Multi-Query is a new way to request a huge amount of information in one request! With Multi-Query you can request multiple endpoints at once, it also works with multiple requests to a single endpoint as well.

A Multi-Query is made by making a POST request to: https://api.igdb.com/v4/multiquery.

Syntax Structure The Multi-Query syntax is made up of three pieces; “Endpoint name”, “Result Name (Given by you)”, and the APICalypse query inside the body {}.

important You can only run a maximum of 10 queries.

Example 1:

Get the count of platforms in the api.

query platforms/count "Count of Platforms" {
  // here we can have additional filters
};

This above query will give us the following result:

[
  {
    "name": "Count of Platforms",
    "count": 155
  }
]

Example 2:

Get Playstation 4 Exclusives

query games "Playstation Games" {
	fields name,platforms.name;
	where platforms !=n & platforms = {48};
	limit 1;
};

This above query will give us the following result:

[
    {
        "name": "Playstation Games",
        "result": [
            {
                "id": 52826,
                "name": "Skate 4",
                "platforms": [
                    {
                        "id": 48,
                        "name": "PlayStation 4"
                    }
                ]
            }
        ]
    }
]

Example 3:

Combining the queries of example 1 and 2.

query platforms/count "Count of Platforms" {
  // here we can ahve additional filters
};

query games "Playstation Games" {
	fields name,platforms.name;
	where platforms !=n & platforms = {48};
	limit 1;
};

[
    {
        "name": "Count of Platforms",
        "count": 155
    },
    {
        "name": "Playstation Games",
        "result": [
            {
                "id": 52826,
                "name": "Skate 4",
                "platforms": [
                    {
                        "id": 48,
                        "name": "PlayStation 4"
                    }
                ]
            }
        ]
    }
]

APICalypse

APICalypse cheatsheet

APICalypse is a new language used for this api which greatly simplifies how you can query your requests compared to the url parameters used in API V2.

Fields

Fields are used to select which fields you want back from your request to the api.

To select fields you need the APICalypse command fields or its shorthand f.

Popular wildcard is to add * instead of a field, this will give you all of the fields.

fields name,release_dates,genres.name,rating;
f name,release_dates,genres.name,rating;

Exclude

Commonly used with selecting all fields with the wildcard * this command will exclude the fields that you select.

To exclude fields you don’t need the APICalypse command exclude or its shorthand x.

fields *;
exclude tags,keywords;

f *;
x tags,keywords;

Where

Where is easiest described as a filter. With where you can filter on specific fields.

To filter your results use the APICalypse command where or its shorthand w.

fields *;
where genres = 4;

f *;
w genres = 4;

Limit

Limit describes how many results you will get back from the api, the standard value is 10.

To set a new limit use the APICalypse command limit or it’s shorthand l.

fields *;
limit 50;

f *;
l 50;

Offset

Offset describes how many results you will skip over, standard is 0.

To set a new offset use the APICalypse command offset or it’s shorthand o.
Offset is often used together with Limit for pagination.

limit 50;
offset 50;

l 50;
o 50;

Sort

Use Sort to order the results to your liking.

To order the results use the APICalypse command sort or it’s shorthand s.
Sort has two accompaning commands for “direction”; asc Ascending order and desc Decending order.

fields *;
sort rating asc;

f *;
s rating desc;

Search

To find a specific title you can use Search.

To use search use the APICalypse command search, it has no shorthand :(. Search has it’s own endpoint where it is good to use a filter for specific kinds of results, example where game != null; for only games.

search "Halo";
fields name;

search "Halo";
f name;

Other shorts

Null can be written null or n. Booleans can be written as true or t and false or f

FAQ

1. I want to use the API for a commercial project, is it allowed?

Yes, we offer commercial partnerships for users looking to integrate the API in monetized products. From our side, as part of the partnership, we ask for user facing attribution to IGDB.com from products integrating the IGDB API.

For more details on that process, please reach out to partner@igdb.com

2. What is the price of the API?

The API is free for both non-commercial and commercial projects.

3. Am I allowed to store/cache the data locally?

Yes. In fact, we prefer if you store and serve the data to your end users. You remain in control over your user experience, while alleviating pressure on the API itself.

4. Regarding user facing attribution (relating to the commercial partnership), any specific guidelines?

Not really. We expect fair attribution, i.e. attribution that is visible to your users and located in a static location (e.g. not in a change log).

5. What happens with the data retrieved, in the case of partnership termination?

You are allowed to keep all data you retrieve from the API and we will not ask you to remove the data in case of partnership termination.

6. We don’t wish to attribute IGDB.com as part of the partnership. Are there any other way?

Yes. If you have data that we think will complete the overall IGDB data set and you are willing to share that data with us, we can opt for this approach instead. Please be aware, however, that we are only interested in publicly available data that we can re-distribute using this API.

1. Can I use Twitch User Credentials to access the API?

The IGDB API uses Application Credentials to authenticate, you cannot use user credentials to authenticate API requests

More information about authentication can be found in the documentation, here

2. The requested images are in the wrong format!

Requesting images using the API returns a default image url using the t_thumb format. To request larger image sizes you should manually create your own image url using the image_id and the appropriate image size. example: https://images.igdb.com/igdb/image/upload/t_{size}/{image_id}.png

More information about images and image sizes can be found in our documentation, here

3. Why am I recieving a CORS error?

The IGDB API does not support browser requests, CORS, for security reasons. This is because the request would leak your access token! We suggest that you create a backend proxy which authenticates and queries the API directly, and can be set up as a trusted connection for your client application.

For more information see our documentation, here

4. My AccessToken stopped working, why?

Your Access Token is only active for 60 days and your application can only have 25 active Access Tokens at one time, going over this limit starts to inactivate older tokens.

5. Why am I only receiving IDs?

An empty request will only yield a list of IDs. To request more information in a single request you should expand your request.
Ex: fields *, cover.*;

More information about expanding requests, here
More example requests, here

6. Why am I only receiving 10 items, how do I get more?

The default item limit is set to 10. To edit this limit simply specify the limit in your request.
Ex: limit 50;
The maximum limit is set to 500 items/request.

7. How can I retrieve Popular Games?

Currently there is no popularity endpoint or popularity field on the game. The main reason is because popularity is quite vague since they can be many different ways to order/define popularity.

It used to be in v3 however we were not confident enough on the data so it was not moved on the V4 version.

Furthermore, the popular games you can see in IGDB.com homepage is specifically within the context of the website. Popularity is different in different context.

Support

Have a question?

If you have any questions about the API we recommend that you join our Discord, there you can discuss the API with other people working with it as well as the developers of the API and ask questions.

Reporting a bug

If you would like to report a bug you can do so in Discord or use Uservoice

License

Any code examples or snippets found under api-docs.igdb.com are made available under the Twitch Developer Services Agreement as Program Materials.

IGDB API Documents

Getting Started

Account Creation

Authentication

Example

Requests

Example

More Examples

Rate Limits

Wrappers

Apicalypse

Third Party

Examples

A very basic example to retrieve the name for 10 games.

Get all information from a specific game

Exclude irrelevant data from your query

Get all games from specific genres

Count total games that have a rating higher than 75

Order by rating

Coming soon games for Playstation 4

Recently released games for Playstation 4

Search, return certain fields.

Search games but exclude versions (editions)

Searching all endpoints

Get versions (editions) of a game

Get the parent game for a version

Get all games that are playstation 4 exclusives

Get all games that are only released on playstation 4 AND PC

Endpoints

Age Rating

Request Path

Age Rating Enums

Alternative Name

Request Path

Artwork

Request Path

Age Rating Content Description

Request Path

Age Rating Content Description Enums

Character Mug Shot

Request Path

Character

Request Path

Character Enums

Collection

Request Path

Company

Request Path

Company Enums

Company Logo

Request Path

Company Website

Request Path

Company Website Enums

Cover

Request Path

External Game

Request Path

External Game Enums

Franchise

Request Path

Game

Request Path

Game Enums

Game Engine

Request Path

Game Engine Logo

Request Path

Game Localization

Request Path

Game Mode

Request Path

Game Version Feature

Request Path

Game Version Feature Enums

Game Version Feature Value

Request Path

Game Version Feature Value Enums

Game Video

Request Path