IFDB APIs > viewgame

The viewgame API

The viewgame API lets applications retrieve IFDB's listing data for a game, either in JSON, or in the Treaty of Babel's iFiction XML format.

Identifying a game

There are two main ways to identify a game for the purposes of this API: by TUID, and by IFID.

A TUID is an IFDB-specific identifier assigned when a new IFDB game listing is created. A TUID is unique within IFDB, and never changes (it will always be the same as long as the listing exists). TUIDs generally are only meaningful within IFDB, so the most likely source of a TUID in a client application would be another IFDB service, such as the search API.

An IFID is an identifier defined by the Treaty of Babel. The key thing about IFIDs is that you can generally find a game's IFID if you have a copy of the game's story file (i.e., the byte-code file for a virtual machine system like the Z Machine, TADS, or Hugo, or simply an executable file for games created without VM systems). For games created after the Babel spec was created, the IFID generally takes the form of a standard UUID, randomly generated by the authoring system when the game is created and stored in the story file in a format-specific manner. Most of the major IF systems define an algorithm for reliably extracting this UUID given a story file. Before Babel, none of the systems had anything specifically UUID-like, so for "legacy" games, Babel instead defines format-specific algorithms for synthesizing a unique identifier from a story file. Combined, these before-and-after rules cover virtually all story files, which means that if you have a copy of a story file, you can get an IFID. So given a story file, you can directly look up the game's IFDB listing data using this API.

JSON API

The viewgame API is implemented as an http web service. To invoke the API, you construct a URL that encodes the game's identifier (see above) and send it to IFDB with an http GET request. You must choose whether you want to use the JSON API or the XML API (see below).

In new code, prefer the JSON API.

To retrieve data by TUID, use this URL: 

  https://ifdb.org/viewgame?json&id=TUID

To retrieve data by IFID, use this URL: 

  https://ifdb.org/viewgame?json&ifid=IFID

The output looks like this:

{
  "colophon": {
    "generator": "ifdb.org/viewgame",
    "generatorversion": 1,
    "originated": "Today's date, YYYY-MM-DD"
  },
  "identification": {
    "ifids": [
      "Treaty of Babel IFIDs"
    ],
    "format": "The file format of the game, e.g. zcode or glulx. This key may be absent if we can't identify the game's format"
  },
  "bibliographic": {
    "title": "Title of the game",
    "author": "Author of the game",
    "language": "Language in two-letter code format, e.g. en or zh",
    "firstpublished": "publication date, YYYY-MM-DD",
    "genre": "Genre, e.g. Fantasy, Horror, Science Fiction",
    "description": "Description of the game (in HTML format)"
  },
  "contacts": [
    "url": "The official Web Site of the game, if any (this key will be absent if there's no web site)"
  ],
  "ifdb": {
    "tuid": "TUID",
    "pageversion": The version number of the page,
    "link": "URL to game's main listing page",
    "coverart": {
      "url": "URL to cover art"
    },
    "playTimeInMinutes": Estimated play time in minutes
    "primaryPlayOnlineUrl": "The URL used in the main "Play online" button for the game (this key will be absent if there's no play online URL)
    "downloads": {
      "links": [
        {
          "url": "URL to the file",
          "playOnlineUrl" : The "play online" version of a given URL (this key will be absent if there's no online-playable version)
          "title": "Title of the file",
          "desc": "Description of the file",
          "isGame": true if this link points to a playable version of the game, such as a story file or an executable application; false otherwise,
          "format": "The file's format, from the File Format page"
        }
      ]
    },
    "averageRating": Raw "star" rating average,
    "starRating": Rounded "star" rating average, for display,
    "ratingCountAvg": Number of ratings in the average (note that reviews can choose to "omit" their ratings from the average),
    "ratingCountTot": Total number of ratings,
    "tags": [
      {
         "name": Text of the tag,
         "tagcnt": Number of users who have used the tag on the current game,
         "gamecnt": How many games have used the tag
      }
    ]
  }
}

averageRating provides the average IFDB member rating as a decimal floating-point number, such as "3.575". This is a simple arithmetic average of the ratings for the game entered by IFDB users; each user rating is simply an integer from 1 to 5. starRating provides the average value rounded to the nearest half-star, which is what IFDB usually displays on its own generated pages. IFDB usually uses a graphic image showing the number of stars in the average, and it only has an image for each half-star increment, so it has to round for this kind of display. It'd be easy enough for client code to do the rounding itself, but the API provides the rounded value anyway because this eliminates any guesswork about the exact rounding rules for boundary cases, ensuring that a client can always display the same rounded value IFDB itself does.

ratingCountAvg and ratingCountTot provide the number of ratings that went into the average, and the total number of ratings for the game, respectively. The reason these are stated separately is that a user can opt to omit their rating for a given game from the game's average. If a user exercises this option, the rating will be recorded but won't be used to compute the average. This means that the ratingCountTot value is always equal to or greater than the ratingCountAvg value.

tagcnt shows how many users have used that tag on the currently selected game. (Normally, tagcnt will be 1, because it's unusual for a player to add a tag when the game already has that tag.) gamecnt shows how many games have used that tag. gamecnt is the number that appears in parentheses next to each tag on the game listing page.

iFiction XML API

In this API, IFDB replies with an XML content body containing an extended iFiction record. By extended, we mean that the record contains the standard iFiction elements, plus some custom IFDB-specific extensions.

To retrieve data by TUID, use this URL: 

  https://ifdb.org/viewgame?ifiction&id=TUID

To retrieve data by IFID, use this URL: 

  https://ifdb.org/viewgame?ifiction&ifid=IFID

True iFiction records vs. IFDB data

It's important to understand that the XML file returned from the viewgame API is in the form of an iFiction record, but it's not the "true" iFiction record for the game.

The true iFiction record for a game is the one provided by the game's author, or by an archivist or other authoritative third party if the author hasn't provided one. The iFiction returned from the viewgame API, in contrast, is a copy of the IFDB listing data for the game, formatted as an iFiction record. IFDB doesn't store the official iFiction for a game anywhere, and it doesn't have any automatic way to synchronize its data with the official iFiction record for a game. On the contrary, IFDB listings are editable by all IFDB members, Wiki-style, so a listing might have information beyond or different from what the author would have entered. The contents might therefore diverge from the official iFiction data provided by the author.

For post-Babel games, the author's official iFiction record can be embedded directly in the story file. If you retrieve an iFiction record for a game from IFDB, and compare it to the iFiction record embedded in the game's story file, you might well find differences. This isn't an error; it simply reflects the different origins of the respective records.

Reply format

On error, the reply has this structure: 

   <viewgame xmlns="http://ifdb.org/api/xmlns">
     <errorCode>code</errorCode>
     <errorMessage>Error message text</errorMessage>
   </viewgame>

The error code is a string indicating the specific type of error that occurred:

The error message text is a human-readable error message. This is the message that the regular game listing page viewer would have displayed for the same error condition, which might or might not be suitable for display in your application.

On success, the reply is in the form of a Babel iFiction record. The following fields are included, to the extent the corresponding data are present in the listing:

In addition, the following IFDB extensions are included. The extensions are all grouped under a single <ifdb> tag that appears at the same XML nesting level as <identification>, <bibliographic>, etc (that is, as a direct child of the <story> element). The structure is as follows: 

   <ifdb xmlns="http://ifdb.org/api/xmlns">
     <tuid>TUID</tuid>
     <link>URL to game page</link>
     <coverart>
       <url>URL to cover art image</url>
     </coverart>
     <playTimeInMinutes>Estimated play time in minutes</playTimeInMinutes>
     <primaryPlayOnlineUrl>The main URL for playing this game online (also used for IFDB's large "Play online" button)</primaryPlayOnlineUrl>
     <averageRating>Average user rating</averageRating>
     <starRating>Star rating</starRating>
     <ratingCountAvg>Number of ratings included in the average</ratingCountAvg>
     <ratingCountTot>Total number of ratings</ratingCountTot>
     <tags>
       <tag>
         <name>Text of the tag</name>
         <tagcnt>Number of users who have used the tag on the current game</tagcnt>
         <gamecnt>How many games have used the tag</gamecnt>
       </tag>
     </tags>
   </ifdb>

While not shown above, the <playOnlineUrl> tags enclose the "play online" version of any given game URL (even if it's not the primary "play online" link for that game).

The TUID is the game's IFDB internal identifier (see above).

The link element gives the URL to the main IFDB listing page for the game.

The coverart element is included only if the IFDB listing include a cover art image; if so, the url element gives an http URL to the image. This URL yields an image file (JPEG, GIF, or PNG) containing the full-size cover art image for the game. You can retrieve a thumbnail of this image by appending &thumbnail=WxH to the URL, where W and H are the desired width and height, in pixels, of the thumbnail. The server preserves the original aspect ratio of the image by treating the given dimensions as a bounding rectangle, and shrinking the image to fit these bounds.

The averageRating element provides the average IFDB member rating as a decimal floating-point number, such as "3.575". This is a simple arithmetic average of the ratings for the game entered by IFDB users; each user rating is simply an integer from 1 to 5. The starRating element provides the average value rounded to the nearest half-star, which is what IFDB usually displays on its own generated pages. IFDB usually uses a graphic image showing the number of stars in the average, and it only has an image for each half-star increment, so it has to round for this kind of display. It'd be easy enough for client code to do the rounding itself, but the API provides the rounded value anyway because this eliminates any guesswork about the exact rounding rules for boundary cases, ensuring that a client can always display the same rounded value IFDB itself does.

The ratingCountAvg and ratingCountTot elements provide the number of ratings that went into the average, and the total number of ratings for the game, respectively. The reason these are stated separately is that a user can opt to exclude her rating for a given game from the game's average. If a user exercises this option, the rating will be recorded but won't be used to compute the average. This means that the ratingCountTot value is always equal to or greater than the ratingCountAvg value.

The returned iFiction record also includes the colophon element, which identifies how the record was generated. For the purposes of the colophon, the API identifies itself with the generator name "ifdb.org/viewgame".

API Index
IFDB Home | Contact Us | Code of Conduct | Terms of Service | Privacy | Copyrights & Trademarks | API
Interactive Fiction technology Foundation
IFDB is managed by the Interactive Fiction Technology Foundation. It is funded by the donations of IF supporters like you. All donations go to support the operation of this web site and IFTF's other services.