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

offset

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

limit

offset

platform

genre

group

title

format

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

offset

age

format

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

format

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

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."
}