IFDB APIs

IFDB offers a few Application Program Interfaces (APIs) that let third parties create Web-based or client-side software that accesses IFDB's data.

The IFDB APIs are implemented as HTTP services. Invoking an API is just like accessing a Web page: you construct a URL, perform an HTTP GET or POST operation on the URL, and read the results. The main thing that makes an API call different from an ordinary page view is that the results of an API call are designed to be machine-readable, whereas an ordinary page view returns HTML formatted for visual display. The API calls return function-specific data structures formatted into JSON, which is readily parseable in software.

Since the IFDB API calls are performed using standard HTML verbs and content formats, you should be able to use any HTTP client library to construct the calls, and any JSON library to parse the JSON responses. Most modern programming languages have some degree of HTTP client and JSON parsing support, either built in or via open source libraries.

Caveats and limitations

The APIs are designed primarily for low-volume, user-driven applications, rather than big batches of automated requests. They're not really meant for constantly crawling the database, high-speed mirroring, etc. The servers that IFDB runs on are from a shared hosting service marketed for personal and small business sites, so they're not set up for high scalability. Please use the APIs with this in mind. If you're contemplating a usage that might put a lot of load on the servers, please consider technical measures that would minimize the impact, such as adding artificial delays while generating requests to throttle the rate.

If the application you have in mind doesn't need live data, note that full exports of the IFDB SQL database (minus users' personal information) are available on the IF Archive in the info/ifdb directory. You can use these exports to create local copies of the database for more computation-intensive analysis, without using any network bandwidth and without creating any load on the IFDB servers. The exports are updated roughly quarterly, so they're not live, but they're always reasonably recent.

It probably goes without saying, but the APIs are subject to change or withdrawal at any time. If you're developing an application that makes use of the APIs, we'd be interested in hearing about your plans, so that we can keep you in mind as the system evolves. Likewise, if you have a need for any additional API services beyond what's currently available, let us know.

Beware HTTP Error 403 Forbidden: Error Code 1010

IFDB is hosted behind Cloudflare, which attempts to detect and reject "bot" traffic with Error Code 1010.

This error indicates that Cloudflare thinks you're a "bot." To circumvent it, you must set a custom user-agent header on your HTTP request.

For example, in Python urllib, you could do this, setting your user-agent header to literally "whatever":

url = 'https://ifdb.org/viewgame?id=aearuuxv83plclpl&json'
req = urllib.request.Request(u)
req.add_header('user-agent', 'whatever')
with urllib.request.urlopen(req) as response:
    print(response.read())

List of APIs

putific: Create or edit a listing by uploading an iFiction XML file. This API is designed primarily for use by IF authoring software, so that a client-side authoring tool can offer a "Publish to IFDB" command that automatically creates a listing from project metadata.

search: Run a search (for games, Recommended Lists, etc). This invokes IFDB's Advanced Search engine, which can perform both full-text and structured (metadata-based) searches.

viewgame: Retrieve a game listing, either in JSON or in the iFiction XML format. This allows client programs, such as IF browsers or "jukeboxes", to take advantage of IFDB's structured data about most of the IF games in circulation.

taggame: Edit tags on an IFDB listing.

gametags: (Deprecated) View the current list of tags associated with an IFDB listing.

JSON is preferred for most APIs

Most of our public APIs have the option to use XML or JSON, but we recommend that you use JSON for all new code.

One exception: the putific only supports XML iFiction submissions.

Note on XML namespaces

Most of the APIs can reply with XML and/or take XML content parameters, and most of the XML formats use XML namespaces. The namespace identifiers are in the form of URLs, according to the XML convention, but we use them simply as GUIDs (which is also a typical XML convention). There are no actual resources (i.e., files to download) at the URL paths we use for our namespace identifiers. Each API's documentation page serves as the definitive specification for the namespaces used in the API.