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're looking to gain access to this API for not-for-profit use, it's completely free - please contact Simon Carless via a MobyGames private message & explain what you plan to use it for.

(We have a small/nominal fee for for-profit use to help us continue to develop our website and database - please reach out in the same way if interested!)

Contents

Tips

Authorization

Requests to the API are authenticated using your private API key, found on your profile. 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.

To gain access to the API, you may contact Simon Carless via a MobyGames private message.

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!

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": [
    {
      "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."
}