The search API

The IFDB search API provides programmatic access to IFDB's full-text and structured-data search capabilities. The API replicates the functionality of IFDB's main Search Web interface.

Protocol

The search API is implemented as a simple http XML service. Parameters are encoded into a URL query string, and the URL is sent to IFDB as an http GET request. The server replies with an JSON content body that contains the search results.

Optionally, you can also sign in with your IFDB email address and password using HTTP Basic Authentication, using the Authorization: Basic ... header. This will allow you to perform searches "as yourself", e.g. searching for games you've played with played:yes.

The root of the URL is https://ifdb.org/search?json.

The search term and object type are added to the root URL as query parameters, using standard URL encoding. That is, each parameter is appended as &paramName=paramValue. Each parameter value is encoded with spaces converted to "+" signs, and "unsafe" characters converted to the "%xx" notation (where xx is the hexadecimal value of the ASCII code for the character). The exact sets of "safe" and "unsafe" characters can be found in the W3C URL spec, but generally, alphanumerics are safe and most punctuation marks aren't. When in doubt, you can always %-encode a character, even when you don't have to.

The first parameter is the object type to search for. A search operators on one type of object; this must be one of the following:

game - search for a game listing
list - search for a Recommended List
poll - search for a poll
comp - search for a competition/award event
member - search the member directory
tag - search the list of tags

The object type parameter requires no value, so simply tack it onto the URL as &game, &list, etc.

The additional query parameters are:

searchfor: The search term, including full-text search keywords and search operators. This is the same string you'd type into the regular IFDB search user interface.

Search operators

The format of the search string used in the API, including the search operators, is the same as for the regular IFDB user interface for search. That's beyond the scope of this documentation; simply refer to the regular Search help page for details. The API uses the same underlying search engine that the user interface does, so any new operators added in the future will be available through the API as soon as they're available in the UI.

Example

To search for a game listing for Deep Space Drifter:

https://ifdb.org/search?json&game&searchfor=Deep+Space+Drifter

Reply

The response is a JSON object, like this:

{
  "games": [
    {
      "tuid": "k82q3libhff6ks8l",
      "title": "Deep Space Drifter",
      "link": "https://ifdb.org/viewgame?id=k82q3libhff6ks8l",
      "author": "Michael J. Roberts and Steve McAdams",
      "devsys": "TADS 2",
      "published": {
        "machine": "1990",
        "printable": "1990"
      },
      "averageRating": 2.428571428,
      "numRatings": 7,
      "starRating": 2.5,
      "starSort": 2.16074024927881,
      "coverArtLink": "https://ifdb.org/coverart?id=k82q3libhff6ks8l&version=4"
    }
  ]
}

A search that yields no results will simply return an empty "group" tag. (A search with zero results isn't an error; it's a search that successfully determined that there were no items in the database matching the search terms.)

The contents of the item tags vary according to the object type. The following sections describe the results for the different object types.

Most of the item replies include a "TUID" value. This the internal ID for the object assigned by IFDB when the object's IFDB listing was originally created. A TUID uniquely identifies the object on IFDB, and it never changes for a given object, so it will always identify the same object as long as the listing exists on IFDB. The TUID can be used in various IFDB URLs to access pages related to the object.

Games

{
  "games": [
    {
      "tuid": "TUID",
      "title": "Title of the game",
      "link": "URL to game's main listing page",
      "author": "Author(s)",
      "devsys": "Development system used to create this game",
      "published": {
        "machine": "Publication date in YYYY or YYYY-MM-DD format",
        "printable": "Publication date in English format"
      },
      "averageRating": Raw "star" rating average,
      "numRatings": Number of ratings in the average (note that reviews can choose to "omit" their ratings from the average),
      "starRating": Rounded "star" rating average,
      "starSort": Star rating for sorting; see below,
      "coverArtLink": "URL to cover art (this key will be absent if there's no cover art)",
      "playTimeInMinutes": "Estimated play time in minutes. This key will be absent if there's no estimated play time."
    }
  ]
}

The "star" rating average is given in three forms. The "raw" average is the arithmetic average of the ratings, as a decimal floating point value (e.g., "3.3333"). The "rounded" average is the average value rounded to the nearest half-star (e.g., "3.5"). IFDB itself generally displays the rounded value, since it uses a graphical image with half-star resolution.

We determine the games with the highest ratings using Evan Miller's formula, which we call "starSort." We used to sort by average rating, but this would tend to rank games with just one perfect 5-star rating above games with dozens of 5-star ratings and a few 4-star ratings. Evan Miller's formula sorts by our confidence in the game, by adding five "fake" ratings to the average (one 1-star, one 2-star, one 3-star, one 4-star, and one 5-star rating) and subtracting the standard deviation from the result.

coverArtLink, if present, will contain a URL to the cover art image. This URL will yield an image file (currently, this can be a JPEG, PNG, or GIF file) containing the full-sized image. You can get a "thumbnail" - i.e., the image at a reduced size - by appending &thumbnail=WxH to the URL, where W is the desired width in pixels, and H is the desired height. The thumbnailer maintains the original image's aspect ratio by treating the request size as a bounding rectangle, and reducing the display size as needed to fit this bounding box.

The publication date is provided in two separate formats for the client's convenience. The "machine" version is a standard numeric YYYY-MM-DD format, such as "2009-09-14" for September 14, 2009, or simply the four-digit year if the full date isn't available. The "printable" version is the equivalent date with the full month name spelled out in English, such as "September 14, 2009", or again just the four-digit year if that's all that's available. These will be present as empty tags if the publication date isn't in the database.

The estimated play time, given in minutes, is based on times submitted by IFDB members for a given game. The estimated play time is the median time rounded to the nearest minute (for games an hour or less) or rounded to the nearest 5 minutes (for games over an hour).

More detail is available for each game in the search results, using the viewgame API.

Lists

{
  "lists": [
    {
      "tuid": "TUID",
      "title": "Title of the list",
      "link": "URL to list's main display page",
      "desc": "List's description (in HTML format)",
      "creatorID": "Member TUID of list's author",
      "creatorName": "Name of list's author",
      "numItems": Number of games in the list
    }
  ]
}

Polls

{
  "polls": [
    {
      "tuid": "TUID",
      "title": "Title of the poll",
      "link": "URL to poll's main display page",
      "desc": "Poll description (in HTML format)",
      "creatorID": "Member TUID of poll's author",
      "creatorName": "Name of poll's author",
      "numGames": Number of distinct games with votes,
      "numVotes": Number of votes
    },
  ]
}

Competitions/Awards

{
  "competitions": [
    {
      "tuid": "TUID",
      "title": "Title of the competition",
      "link": "URL to competition's main display page",
      "desc": "Description (in HTML format)",
      "numGames": Number of games listed,
      "numDivisions": Number of divisions
    }
  ]
}

Members

{
  "members": [
    {
      "tuid": "TUID",
      "name": "Display name",
      "link": "URL to member's public profile page",
      "location": "Location, set in the user's profile",
      "badge": ""Top N Reviewer" badge, if any",
      "pictureLink": "Link to the user's profile photo (this key will be absent if the user has no profile picture)"
    }
  ]
}

The location is usually a city or country name; the exact format is unpredictable because it's simply whatever the user entered in her profile.

If present, the pictureLink value will be a URL to the image; this will yield an image file, currently of type JPEG, PNG, or GIF. You can get a thumbnail just as for game cover art images, by appending &thumbnail=WxH to the URL.

Legacy XML format

You can also use our legacy XML-based search.

To search for a game listing for Deep Space Drifter in XML:

https://ifdb.org/search?xml&game&searchfor=Deep+Space+Drifter

The reply is an XML file with this enclosing structure:

   <?xml version="1.0" encoding="UTF-8" ?>
   <searchReply xmlns="http://ifdb.org/api/xmlns">
      reply-data
   </searchReply>

If an error occurs, the reply-data will be an <error> tag containing a human-readable text error message:

   <error>
      error message text
   </error>

On success, the reply-data will be a "group" tag for the object type, containing a list of zero or more "item" tags for the individual results.

Type Group Tag Item Tag

Game <games> <game>

Recommended List <lists> <list>

Poll <polls> <poll>

Competition/Awards <comps> <comp>

Member <members> <member>

Tag <tags> <tag>

Type	Group Tag	Item Tag
Game	<games>	<game>
Recommended List	<lists>	<list>
Poll	<polls>	<poll>
Competition/Awards	<comps>	<comp>
Member	<members>	<member>
Tag	<tags>	<tag>

For example, for a Poll search yielding three results, the reply-data section would look like this:

   <polls>
     <poll>
       first item
     </poll>
     <poll>
       second item
     </poll>
     <poll>
       third item
     </poll>
   </polls>

The contents of the item tags vary according to the object type. The following sections describe the results for the different object types.

Games

  <game>
    <tuid>TUID</tuid>
    <title>Title of the game</title>
    <link>URL to game's main listing page</link>
    <author>Author(s)</author>
    <averageRating>Raw "star" rating average</averageRating>
    <numRatings>Number of ratings in the average</numRatings>
    <starRating>Rounded "star" rating average</starRating>
    <starSort>Star rating for sorting; see below</starRating>
    <hasCoverArt>Cover art exists: yes or no</hasCoverArt>
    <devsys>Name of development system</devsys>
    <published>
      <machine>Publication date in YYYY or YYYY-MM-DD format</machine>
      <printable>Publication date in English format</printable>
    </published>
    <coverArtLink>URL to cover art</coverArtLink>
  </game>

The "star" rating average is given in two forms. The "raw" average is the arithmetic average of the ratings, as a decimal floating point value (e.g., "3.3333"). The "rounded" average is the average value rounded to the nearest half-star (e.g., "3.5"). IFDB itself generally displays the rounded value, since it uses a graphical image with half-star resolution.

The hasCoverArt value is simply "yes" or "no", indicating whether or not the game has cover art. If this is "yes", the coverArtLink element will also be present, and will contain a URL to the cover art image. This URL will yield an image file (currently, this can be a JPEG, PNG, or GIF file) containing the full-sized image. You can get a "thumbnail" - i.e., the image at a reduced size - by appending &thumbnail=WxH to the URL, where W is the desired width in pixels, and H is the desired height. The thumbnailer maintains the original image's aspect ratio by treating the request size as a bounding rectangle, and reducing the display size as needed to fit this bounding box.

Lists

  <list>
    <tuid>TUID</tuid>
    <title>Title of the list</title>
    <link>URL to list's main display page</link>
    <desc>List's description</desc>
    <creatorID>Member TUID of list's author</creatorID>
    <creatorName>Name of list's author</creatorName>
    <numItems>Number of games in the list</numItems>
  </list>

Polls

  <poll>
    <tuid>TUID</tuid>
    <title>Title of the poll</title>
    <link>URL to poll's main display page</link>
    <desc>Poll description</desc>
    <creatorID>Member TUID of poll's creator</creatorID>
    <creatorName>Name of poll's creator</creatorName>
    <numGames>Number of distinct games with votes</numGames>
    <numVotes>Number of votes</numVotes>
  </poll>

Competitions/Awards

  <comp>
    <tuid>TUID</tuid>
    <title>Title of the competition</title>
    <link>URL to competition's main display page</link>
    <desc>Description</desc>
    <numGames>Number of games listed</numGames>
    <numDivisions>Number of divisions</numDivisions>
  </comp>

Members

  <member>
    <tuid>TUID</tuid>
    <name>Display name</name>
    <link>URL to member's public profile page</link>
    <loc>Location</loc>
    <hasPicture>Member photo present: yes or no</hasPicture>
    <pictureLink>URL to member photo</pictureLink>
    <badge>"Top N Reviewer" badge, if any</badge>
  </member>

The location is usually a city or country name; the exact format is unpredictable because it's simply whatever the user entered in her profile.

The hasPicture value is "yes" or "no", indicating whether or not the user has a profile photo. If this is "yes", the pictureLink value will be a URL to the image; this will yield an image file, currently of type JPEG, PNG, or GIF. You can get a thumbnail just as for game cover art images, by appending &thumbnail=WxH to the URL.

The search API

Protocol

Search operators

Example

Reply

Games

Lists

Polls

Competitions/Awards

Members

Tags

Legacy XML format

Games

Lists

Polls

Competitions/Awards

Members

Tags