What is this guide?
This guide should get you up and running using the Giant Bomb API. This guide will walk you through a simple example which should be all you need to figure out the rest thanks to the great documentation the Giant Bomb guys have already done.
What is this guide not?
What is an API?
An API is a way of accessing a system through (in this case) internet queries (URLs). The Giant Bomb site makes a lot of their data available through this system and their API lets you access that data. It doesn't let you change or update that data and it doesn't create pages or videos for you to plop in your site or App. What it does is provide data in a text format that you can interpret. You can then use this data to display text or images or video.
Very generally, this data can be accessed in two ways. The first is by finding information about a specific piece of content. The second is to search the database based on certain keywords to find content.
Yeah Yeah Yeah, how do I use it?
- Get a key*: http://www.giantbomb.com/api
- Load up the API reference: http://www.giantbomb.com/api/documentation
* An API key is like a password. It lets the system know who's access the data and without it you can't get any data. It needs to be sent with each request.
Test it out:
We are going to do a test query. This can be done in a browser by entering a URL into the address bar. Fill in your key with the URL below to load up some Metroid Prime 3 data (Hey, I'm playing it now!),
If your API key is working, you should get a bunch of text back (XML data) that has info on Metroid Prime 3.
Let's do another test,
This illustrates a few things about the query structure.
Resource Type: This is the type of resource you want to get information on. Game is the base type.
Resource ID: This is the ID of the resource. The easiest way to find this is to browse Giant Bomb. The resource IDs are in the URLs of the pages in the wiki. (example: http://www.giantbomb.com/metroid-prime-3-corruption/3030-4725/)
Response Data Format: There are (at least) two data formats. The default is XML which is an older standard, while another optional one is JSON which is the current (Spring 2013) standard for APIs. I would recommend JSON since it's awesome and supported natively by a lot of stuff (except browsers :()
Field List: You can optionally limit the response to only a few fields. It makes exploring the data easier, but for most Apps it may not be necessary. You can find the list of available fields in the API documentation.
If you are unfamiliar with URL parameters, they are typically written by adding a "?" mark at the end of a URL followed by a list of fields and values separated by the "&" symbol. The order does not matter and typically if you leave out a field, the default value will be used.
Looking at a Response
I'm going to assume JSON for this section, but the XML is similar.
Assuming your API key is working and your URL is correct, you are going to get back a data object. That object tells you a little about the request / response and then contains the actual data you want. The information about response codes, etc is in the documentation (http://www.giantbomb.com/api/documentation). For the most part you can ignore it at the beginning, you just want to look at the results part of it.
The results object will list all (or a selection if you restricted the fields) of fields. Each of these portion of the results is another object with data in it.
Here are some useful things to look for.
name: This will most likely be the field with the actual data in it.
id: This is the ID for the specific bit of data. In the example above, each genre has it's own resource ID. This ID is not specific to the game in this example, it's the ID of the genre that could be linked to many games.
api_detail_url: This is a request URL that you would use to get more data about this resource. In this example, the URL can be used as the base URL for an API request. You would need to add your API key to it as described above.
site_detail_url: This is a URL to the actual page on Giant Bomb. These would be good for links in your apps.
Doing a search
Doing a search is very similar to accessing content.
As you would expect, you get an object of results. You can then explore those results and access the associated data.
I recommend exploring the API with a browser like Chrome or Firefox and installing an add on / extension that displays JSON. This will let you play around with the data and see what's there.
Typically, you would use this data by finding one piece of content and then finding all the related bits of content connected to it. This API makes that incredibly easy since the query is included with the data objects.