Overview

With the Whiskey Media API, you can retrieve wiki content created by our staff and users. To get started, you must create an account and request an API key. Your API key will be sent with each API request.

Table of Contents

• Definitions
• Making Requests
  • Detail Resource Requests
  • List Resource Requests
  • Pagination
• Handling Responses
• Delivery Formats
• Resources
  • accessories
  • characters
  • chats
  • companies
  • concepts
  • franchises
  • games
  • Game Ratings
  • genres
  • locations
  • objects
  • people
  • platforms
  • Promos
  • Rating Boards
  • regions
  • releases
  • Reviews
  • Search
  • themes
  • Types
  • User Reviews
  • videos
  • video_types
• Description Field Formatting

Definitions

Below is a list of terms and definitions used throughout this document.

• Resource - A mapping between an URL path and a data type. The resource defines a list of fields that will be returned within the response. There are primarily two types of resources:
  • List Resource - Returns zero or more records. List resources can be filtered and sorted to customize the result set. A List Resource typically returns fewer fields than the corresponding Detail Resource for the same item. However, each record will contain a field named "api_detail_url", providing a link to the Detail Resource for that item. List Resources are limited to returning no more than 100 results per request. Subsequent queries can be made to continue fetching more results. See the Pagination section below.
  • Detail Resource - Returns all information about a single item. A Detail Resource contains information about the requested object as well as all of its relations to other objects.
• API Key - An alpha-numeric string used to identify the user making the request.
• Filter - A parameter passed with the request that filters the result set based on the filter value. These are most commonly used on List Resources.

Making Requests

Our number one goal is to make our data easy for you to access. That's why we've adopted a RESTful style of query access. As long as you can make a web request, you can access our data.

Each request is made against a specific resource. A resource defines the type of object that will be returned, the fields on that object, and any filters that can be used to customize the result set.

Detail Resource Requests

A request to a Detail Resource contains a resource name, the ID of the object being queried, an API key, and optionally a response format. For example, the following URL would make a request to retrieve the character with an ID of 248 in XML format:

http://api.giantbomb.com/character/248/?api_key=ABCDEF123456&format=xml
        

List Resource Requests

A request to a List Resource contains a resource name and an API Key. Optionally filters, sorting, and response format can be specified. Refer to the resource reference below for a list of fields that can be filtered and sorted. A request to retrieve all male characters sorted by birth_date in XML format would look like:

http://api.giantbomb.com/characters/?api_key=ABCDEF123456&gender=M&sort=birth_date&format=xml
        

That URL becomes easier to understand if broken apart. The "/characters/" path refers to the /characters/ resource. (See a complete list of resources below.)

The query string holds the rest of the request. The api_key parameter specifies your API key. The gender parameter specifies that the request should be filtered by gender. Passing "M" or "F" to it will filter the result set by either male- or female-only characters. Finally, the sort parameter specifies that the result set should be sorted by the "birth_date" field.

Pagination

For performance reasons, we only allow up to 100 results to be returned at a time. However, we've created the ability for a client to make subsequent requests for more data. A special offset filter is available on all List Resources. By specifying an offset, the client can start retrieving results mid-way through the result set. For example, if there are 357 characters matching a request, the following four requests would retrieve all of the characters:

# Retrieves items 1-100
http://api.giantbomb.com/characters/?api_key=ABCDEF123456
# Retrieves items 101-200
http://api.giantbomb.com/characters/?api_key=ABCDEF123456&offset=100
# Retrieves items 201-300
http://api.giantbomb.com/characters/?api_key=ABCDEF123456&offset=200
# Retrieves items 301-357
http://api.giantbomb.com/characters/?api_key=ABCDEF123456&offset=300
        

NOTE: Result sets are always sorted in a consistent manner even if a sort order isn't specified as part of the request. This guarantees that a client relying on pagination won't retrieve duplicate results over multiple requests.

Handling Responses

Every response contains a set of meta data. Using this meta data, you can determine if the request was processed successfully, how many results were returned in the response, and how many results you still need to fetch. The following grid describes each piece of meta data available.

Delivery Formats

We currently support three delivery formats: XML, JSON, and JSONP. We may add additional formats going forward, but feel these three encompass most use cases for now. When making a request, you can choose the response format you prefer by specifying the 'format' option. For example, to get results as JSON, pass a querystring with the 'format' variable set to 'json'. If no format is specified, you'll receive data in the default format, which is XML.

XML XML parsers can be found in nearly every programming language. See the Wikipedia entry for an in-depth discussion of XML. Here's an example of an XML response.

<?xml version="1.0" encoding="UTF-8" ?>
<response>
<error>OK</error>
<limit>1</limit>
<number_of_page_results>1</number_of_page_results>
<number_of_total_results>1</number_of_total_results>
<offset>0</offset>
<results>
    <character>
        <id>1</id>
        <site_detail_url>http://www.giantbomb.com/mario/94-1/</site_detail_url>
        <name<Mario</name>
        <gender>M</gender>
        <friends>
            <character>
                <id>2</id>
                <name>Luigi</name>
                <api_detail_url>http://api.giantbomb.com/character/2/</api_detail_url>
            </character>
        </friends>
        <!-- more character fields -->
    </character>
</results>
<status_code>1</status_code>
</response>
            

JSON JSON stands for JavaScript Object Notation. JSON can be parsed natively by JavaScript. Many other languages have libraries that convert native structures to and from JSON. JSON is generally smaller than XML, which is convenient for smaller requests. See the Wikipedia entry for an in-depth discussion of JSON. Here's an example of a JSON response.

{
"number_of_page_results": 1,
"status_code": 1,
"error": "OK",
"results": {
    "id": 1,
    "site_detail_url": "http://www.giantbomb.com/mario/94-1/",
    "name": "Mario",
    "gender": "M",
    "friends": [
            {
                "id": 2,
                "name": "Luigi",
                "api_detail_url": "http://api.giantbomb.com/character/2/"
            }
        ]
    // More character fields...
    },
"limit": 1,
"offset": 0,
"number_of_total_results": 1
}
            

JSONP JSONP wraps a JSON response in a user-defined callback function. JSONP is generally used to circumvent the security restriction of browsers requiring JavaScript requests to be made from the same domain the page was served from. See the Wikipedia entry for an in-depth discussion of JSONP. NOTE: The JSONP format requires an additional querystring variable, 'json_callback', to be included in the request. The following example assumes the request was made with 'json_callback=my_callback'.

my_callback( {
"number_of_page_results": 1,
"status_code": 1,
"error": "OK",
"results": {
    "id": 1,
    "site_detail_url": "http://www.giantbomb.com/mario/94-1/",
    "name": "Mario",
    "gender": "M",
    "friends": [
            {
                "id": 2,
                "name": "Luigi",
                "api_detail_url": "http://api.giantbomb.com/character/2/"
            }
        ]
    // More character fields...
    },
"limit": 1,
"offset": 0,
"number_of_total_results": 1
} );
            

Resources

Description Fields

The description fields that include the bulk of the text content for our pages are for the most part fairly clean in terms of markup. We do however use a standard set of HTML tags to style h2s, h3s and the images that are floated inside text. The following CSS should cover all non-regular formatting that exists in the description fields.

.wiki-img {
    width:150px;
    padding:8px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-small {
    width:50px;
    padding:8px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-thumb {
    width:150px;
    padding:3px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-screen {
    width:192px;
    padding:3px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-medium {
    width:150px;
    padding:8px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-super {
    padding:8px;
    background:#FFF;
    border:solid 1px #CCC;
    color:#000;
    font-weight:bold;
    text-align:center;
}

.wiki-img-left {
    background:#FFF;
    float:left;
    margin:0px 15px 15px 0px;
}

.wiki-img-right {
    background:#FFF;
    float:right;
    margin:0px 0px 15px 15px;
}

.wiki-img-center {
    background:#FFF;
    padding:0px 0px 15px 0px;
}

.plain-list li {
    list-style-type:square;
    margin-left:25px;
    margin-top:6px;
}