API Documentation
MobyGames API
MobyGames now features a fully fledged video game database API for exporting and extracting all kinds of useful information from our world-leading database!
If you'd like access to the free API (not-for-profit use), create a MobyGames account and then visit your profile page. Click the 'API' link under your user name to sign up for an API key. If you wish to use the API key with an existing game launcher or plugin please specify which launcher and plugin you will be using.
If you have a commercial (for-profit) use in mind for the API, email [email protected] to register interest. Please include your use case.
Tips
Authorization
Requests to the API are authenticated using your private API key, found on
your profile, accessible from the menu at the top right. You may provide the
key as the value of the api_key
query argument, e.g.
https://api.mobygames.com/v1/games?api_key=YOUR_KEY
.
Limits
Right now, API requests are limited to 360 per hour (one every ten seconds). In addition, requests should be made no more frequently than one per second.
Multi-valued parameters
If a query paramter accepts multiple values, such as the
genre
parameter to the /games
endpoint, provide
the multiple values by supplying the parameter multiple times, e.g.
https://api.mobygames.com/v1/games?genre=1&genre=2&genre=3
.
Null data
Some properties might be null, and lists might be empty. Be sure your code will properly handle these cases!
URL encode everything
All query arguments (including the api key!) must be urlencoded. If you don't urlencode an api key with a + in it, the key will not be valid.
Endpoints
/genres
This endpoint provides a list of genres which may be used for filtering games via the API.
Sample
GET https://api.mobygames.com/v1/genres { "genres": [ { "genre_category": "Basic Genres", "genre_category_id": 1, "genre_description": "Action games main mechanics revolve around one or more...", "genre_id": 1, "genre_name": "Action" }, { "genre_category": "Basic Genres", "genre_category_id": 1, "genre_description": "Adventure games emphasize experiencing a story through...", "genre_id": 2, "genre_name": "Adventure" }, { "genre_category": "Basic Genres", "genre_category_id": 1, "genre_description": "Simulation games can be one of many different...", "genre_id": 3, "genre_name": "Simulation" }, { "genre_category": "Basic Genres", "genre_category_id": 1, "genre_description": "Strategy/Tactics games revolve around strategic...", "genre_id": 4, "genre_name": "Strategy/Tactics" } ] }
/groups
This endpoint provides a list of groups which may be used for filtering games via the API.
Parameters
limit
- default 100, max 100
- the maximum number of groups to return
offset
- default 0
- The offset from which to begin returning groups
Sample
GET https://api.mobygames.com/v1/groups { "groups": [ { "group_description": "Monkey Island is a series of comedy...", "group_id": 1, "group_name": "Monkey Island series" }, { "group_description": "Games based on the writings of H. P. Lovecraft...", "group_id": 2, "group_name": "Inspiration: Author - H. P. Lovecraft" }, { "group_description": "A series of graphical fantasy adventure games...", "group_id": 3, "group_name": "King's Quest series" }, { "group_description": "Space Quest is a series of comedy...", "group_id": 4, "group_name": "Space Quest series" }, { "group_description": "In the early 1990s, Sierra got the idea to...", "group_id": 5, "group_name": "Sierra remakes" } ] }
/platforms
This endpoint provides a list of platforms which may be used for filtering games via the API.
Sample
GET https://api.mobygames.com/v1/platforms { "platforms": [ { "platform_id": 1, "platform_name": "Linux" }, { "platform_id": 2, "platform_name": "DOS" }, { "platform_id": 3, "platform_name": "Windows" }, { "platform_id": 4, "platform_name": "PC Booter" }, { "platform_id": 5, "platform_name": "Windows 3.x" } ] }
/games
This endpoint provides a list of games matching the filters given in the query parameters, ordered by ID.
Parameters
id
- IDs of games to return. If specified, other parameters besides format will be ignored.
limit
- default 100, max 100
- The maximum number of games to return
offset
- default 0
- The offset from which to begin returning games
platform
- multiple
- The ID of a platform on which the game was released
genre
- multiple
- The ID of a genre assigned to the game
group
- multiple
- The ID of a group assigned to the game
title
- A substring of the title (not case sensitive)
format
- default 'normal'
- The output format: id, brief, or normal
Output Formats
This endpoint can output several different formats, as specified by the
formats
parameter.
The id
format may be used to retrieve a list of game IDs
matching the selected filters.
The brief
format provides a minimal selection of data about a
game, suitable for generating links.
The normal
format provides all major information about a game,
including abbreviated release information. This is the default format.
Samples
GET https://api.mobygames.com/v1/games?format=id { "games": [ 1, 2, 3, 4, 5 ] }
GET https://api.mobygames.com/v1/games?format=brief { "games": [ { "game_id": 1, "moby_url": "http://www.mobygames.com/game/x-files-game", "title": "The X-Files Game" }, { "game_id": 2, "moby_url": "http://www.mobygames.com/game/who-framed-roger-rabbit", "title": "Who Framed Roger Rabbit" }, { "game_id": 3, "moby_url": "http://www.mobygames.com/game/wing-commander", "title": "Wing Commander" }, { "game_id": 4, "moby_url": "http://www.mobygames.com/game/sid-meiers-alpha-centauri", "title": "Sid Meier's Alpha Centauri" }, { "game_id": 5, "moby_url": "http://www.mobygames.com/game/indianapolis-500-the-simulation", "title": "Indianapolis 500: The Simulation" } ] }
GET https://api.mobygames.com/v1/games?format=normal { "games": [ { games":[ { "alternate_titles":[ { "description":"Finnish title", "title":"Salaiset Kansiot" }, { "description":"French title", "title":"The X-Files: Le Jeu" }, { "description":"PSX title", "title":"The X Files" }, { "description":"Simplified Chinese spelling", "title":"X\u6863\u6848" } ], "description": "As an extension of one of the most long-running...", "game_id": 1, "genres": [ { "genre_category": "Basic Genres", "genre_category_id": 1, "genre_id": 2, "genre_name": "Adventure" }, { "genre_category": "Perspective", "genre_category_id": 2, "genre_id": 7, "genre_name": "1st-person" }, { "genre_category": "Narrative Theme/Topic", "genre_category_id": 8, "genre_id": 55, "genre_name": "Detective / Mystery" }, { "genre_category": "Setting", "genre_category_id": 10, "genre_id": 8, "genre_name": "Sci-Fi / Futuristic" }, { "genre_category": "Other Attributes", "genre_category_id": 6, "genre_id": 82, "genre_name": "Licensed Title" } ], "moby_score": 3.8, "moby_url": "http://www.mobygames.com/game/x-files-game", "num_votes": 53, "official_url": null, "platforms": [ { "first_release_date": "1998", "platform_id": 3, "platform_name": "Windows" }, { "first_release_date": "1998-06", "platform_id": 74, "platform_name": "Macintosh" }, { "first_release_date": "1999", "platform_id": 6, "platform_name": "PlayStation" } ], "sample_cover": { "height": 927, "image": "http://www.mobygames.com/images/covers/l/3-the-x-files-game...", "platforms": [ "Windows" ], "thumbnail_image": "http://www.mobygames.com/images/covers/s/3-the-x-files...", "width": 800 }, "sample_screenshots": [ { "caption": "Mulder and Special Agent Willmore", "height": 480, "image": "http://www.mobygames.com/images/shots/l/86087-the-x-files...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/86087-the...", "width": 640 }, { "caption": "Title screen (from intro)", "height": 480, "image": "http://www.mobygames.com/images/shots/l/313897-the-x-files-game...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/313897-the-x...", "width": 640 }, { "caption": "Gillian Anderson (from intro)", "height": 480, "image": "http://www.mobygames.com/images/shots/l/313919-the-x-files-game...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/313919-the-x...", "width": 640 }, { "caption": "David Duchovny (from intro)", "height": 480, "image": "http://www.mobygames.com/images/shots/l/313908-the-x-files-game-windows...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/313908-the-x-files...", "width": 640 } ], "title": "The X-Files Game" } ] }
/games/recent
This endpoint provides a list of games that have been modified recently. By default, only a list of IDs is returned, but the output format may be chosen as with the /games endpoint.
Parameters
limit
- default 100, max 100
- The maximum number of games to return
offset
- default 0
- The offset from which to begin returning games
age
- default 21, max 21
- Return only games modified in the last
age
days
format
- default 'id'
- The output format: id, brief, or normal
Sample
GET https://api.mobygames.com/v1/games/recent { "games": [ 53431, 81032, 81045, 56748, 80903 ] }
/games/random
This endpoint provides a list of random games. By default, only a list of IDs is returned, but the output format may be chosen as with the /games endpoint.
It is recommended to cache the response from this endpoint for local use, rather than to call it repeatedly. This endpoint will provide at most 100 random games, with the list being refreshed at most once per five minutes.
Parameters
limit
- default 100, max 100
- The maximum number of games to return
format
- default 'id'
- The output format: id, brief, or normal
Sample
GET https://api.mobygames.com/v1/games/random { "games": [ 22611, 53167, 75945, 47739, 66268 ] }
/games/{game_id}
A convenience endpoint providing information about a single game.
/games/12345
is equivalent to /games?id=12345
.
Parameters
format
- default 'normal'
- The output format: id, brief, or normal
Sample
GET https://api.mobygames.com/v1/games/31910?format=brief { "game_id": 31910, "moby_url": "http://www.mobygames.com/game/mordor-the-depths-of-dejenol", "title": "Mordor: The Depths of Dejenol" }
/games/{game_id}/platforms
Lists platforms for which a game was released.
Sample
GET https://api.mobygames.com/v1/games/31910/platforms { "platforms": [ { "first_release_date": "1995", "platform_id": 5, "platform_name": "Windows 3.x" } ] }
/games/{game_id}/platforms/{platform_id}
Lists information about a game's releases on the specified platform.
Sample
GET https://api.mobygames.com/v1/games/31910/platforms/5 { "attributes": [ { "attribute_category_id": 6, "attribute_category_name": "Input Devices Supported", "attribute_id": 23, "attribute_name": "Keyboard" }, { "attribute_category_id": 6, "attribute_category_name": "Input Devices Supported", "attribute_id": 24, "attribute_name": "Mouse" }, { "attribute_category_id": 10, "attribute_category_name": "Minimum OS Class Required", "attribute_id": 205, "attribute_name": "Windows 3.0" }, { "attribute_category_id": 11, "attribute_category_name": "Minimum CPU Class Required", "attribute_id": 66, "attribute_name": "80386" }, { "attribute_category_id": 15, "attribute_category_name": "Minimum RAM Required", "attribute_id": 104, "attribute_name": "4 MB" }, { "attribute_category_id": 16, "attribute_category_name": "Business Model", "attribute_id": 124, "attribute_name": "Commercial" }, { "attribute_category_id": 21, "attribute_category_name": "Media Type", "attribute_id": 516, "attribute_name": "3.5\" Floppy Disk" }, { "attribute_category_id": 21, "attribute_category_name": "Media Type", "attribute_id": 518, "attribute_name": "CD-ROM" }, { "attribute_category_id": 40, "attribute_category_name": "Number of Players: Offline", "attribute_id": 489, "attribute_name": "1 Player" } ], "first_release_date": "1995", "game_id": 31910, "patches": [], "platform_id": 5, "platform_name": "Windows 3.x", "ratings": [], "releases": [ { "companies": [ { "company_id": 10734, "company_name": "MakeItSo Software", "role": "Published by" } ], "countries": [ "United States" ], "description": null, "product_codes": [], "release_date": "1995" } ] }
/games/{game_id}/platforms/{platform_id}/screenshots
Lists screenshots for the specified game and platform.
Sample
GET https://api.mobygames.com/v1/games/31910/platforms/5/screenshots { "screenshots": [ { "caption": "Opening Screen", "height": 976, "image": "http://www.mobygames.com/images/shots/l/272039-mordor...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/272039...", "width": 1428 }, { "caption": "When creating a character, the race, alignment, and...", "height": 977, "image": "http://www.mobygames.com/images/shots/l/272040-mordor...", "thumbnail_image": "http://www.mobygames.com/images/shots/s/272040...", "width": 1429 } ] }
/games/{game_id}/platforms/{platform_id}/covers
Lists cover groups for the specified game and platform.
Sample
GET https://api.mobygames.com/v1/games/15/platforms/5/covers { "cover_groups": [ { "comments": null, "countries": [ "Germany" ], "covers": [ { "comments": null, "description": null, "height": 807, "image": "http://www.mobygames.com/images/covers/l/21069-sid-meier...", "scan_of": "Media", "thumbnail_image": "http://www.mobygames.com/images/covers/s/21069...", "width": 800 }, { "comments": null, "description": null, "height": 1030, "image": "http://www.mobygames.com/images/covers/l/90498-sid-meier...", "scan_of": "Back Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/90498...", "width": 800 }, { "comments": null, "description": null, "height": 1026, "image": "http://www.mobygames.com/images/covers/l/90499-sid-meier...", "scan_of": "Front Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/90499...", "width": 800 } ] }, { "comments": null, "countries": [ "United Kingdom" ], "covers": [ { "comments": null, "description": null, "height": 1016, "image": "http://www.mobygames.com/images/covers/l/91437-sid-meier...", "scan_of": "Front Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/91437...", "width": 800 }, { "comments": null, "description": null, "height": 1032, "image": "http://www.mobygames.com/images/covers/l/91438-sid-meier...", "scan_of": "Back Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/91438...", "width": 800 }, { "comments": null, "description": null, "height": 802, "image": "http://www.mobygames.com/images/covers/l/111824-sid-meier...", "scan_of": "Media", "thumbnail_image": "http://www.mobygames.com/images/covers/s/111824...", "width": 800 } ] }, { "comments": null, "countries": [ "Brazil" ], "covers": [ { "comments": null, "description": null, "height": 1011, "image": "http://www.mobygames.com/images/covers/l/161237-sid-meier...", "scan_of": "Front Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/161237...", "width": 800 }, { "comments": null, "description": null, "height": 1013, "image": "http://www.mobygames.com/images/covers/l/161238-sid-meier...", "scan_of": "Back Cover", "thumbnail_image": "http://www.mobygames.com/images/covers/s/161238...", "width": 800 }, { "comments": null, "description": null, "height": 800, "image": "http://www.mobygames.com/images/covers/l/161290-sid-meier...", "scan_of": "Media", "thumbnail_image": "http://www.mobygames.com/images/covers/s/161290...", "width": 800 } ] } ] }
Error Messages
In case there is a problem processing a request, an error message will be returned. Here you will find several common errors.
400 Bad Request
Sent if your query could not be processed, possibly due to invalid parameter types, e.g. a string where an integer was expected.
Sample
GET https://api.mobygames.com/v1/games?id=not_an_integer { "code": 6, "error": "Error parsing parameters", "message": "An unspecified error was encountered parsing query parameters. Ensure that all parameter values are of valid types." }
401 Unauthorized
Sent if you attempt to access an endpoint without providing a valid API key.
Sample
GET https://api.mobygames.com/v1/games { "code": 401, "error": "Authorization required", "message": "You must have an API key to use this resource." }
404 Not Found
Sent if you attempt to access an object that does not exist.
Sample
GET https://api.mobygames.com/v1/games/0 { "code": 1, "error": "Game not found", "message": "" }
422 Unprocessable Entity
Sent if the value of some parameter was of the right type, but was invalid.
Sample
GET https://api.mobygames.com/v1/games?title=long... { "code": 9, "error": "Title too long", "message": "Title filter must be <= 128 characters." }
429 Too Many Requests
Sent if you make a request exceeding your API quota.
Sample
GET https://api.mobygames.com/v1/games { "code": 429, "error": "Too many requests", "message": "Oy, you're making requests too frequently for us to handle. Please wait at least 1 seconds between requests." }