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 XML content body that contains the search results.

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

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

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?xml&game&searchfor=Deep+Space+Drifter

Reply

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>

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>

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 ("tads.org Unique Identifier"). 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. A TUID has no significance outside of IFDB, and has no internal structure; it's just a string of 16 random letters and numbers. This format was chosen because (a) it reliably yields gibberish strings without word breaks, which makes it an excellent key for a generic Web text search, (b) it's effectively a sort of UUID, since the range is so large (there are about 8 trillion trillion possible combinations) that collisions with similarly formatted ID keys in other databases will essentially never happen, and (c) it doesn't look like a standard UUID, which might have been somewhat confusing given that the Babel spec uses standard UUIDs for IFIDs

(It might seem strange that IFDB doesn't just use Babel IFIDs as primary identifiers, but there are good reasons: (a) Babel only applies IFIDs to games, whereas IFDB needs primary identifiers for other kinds of entities, such as recommended lists, user profiles, and polls; and (b) a single game can have multiple Babel IFIDs, so even for games there'd still be a need in the database structure for a single unique identifier per game.)

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.

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.

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.

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.

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.