Quick Start Guide to Using the API

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?

This guide is not going to cover any legal discussion / usage rights and it's also not going to cover any technical guides to JSON / XML or Javascript / etc to do things with the data once you have it.

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?

1. Get a key*: http://www.giantbomb.com/api
2. 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!),

http://www.giantbomb.com/api/game/3030-4725/?api_key=[YOUR-KEY]

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,

http://www.giantbomb.com/api/game/3030-4725/?api_key=[YOUR-KEY]&format=json&field_list=genres,name

This illustrates a few things about the query structure.

http://www.giantbomb.com/api/[RESOURCE-TYPE]/[RESOURCE-ID]/?api_key=[YOUR-KEY]&format=[RESPONSE-DATA-FORMAT]&field_list=[COMMA-SEPARATED-LIST-OF-RESOURCE-FIELDS]

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.

Results Object

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.

http://www.giantbomb.com/api/search?api_key=[YOUR-KEY]&format=[RESPONSE-DATA-FORMAT]&query=[YOUR-SEARCH]&resources=[SOME-TYPES]

Example:

http://www.giantbomb.com/api/search/?api_key=[YOUR-KEY]&format=json&query="metroid prime"&resources=game

As you would expect, you get an object of results. You can then explore those results and access the associated data.

What more?

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.

Good luck!

As I play with the API a bit more I will try to add explanations of the sorts and filters. Is there anything else missing from this quick start guide?

Can we get the documentation in PDF format?

why is there html in the response? how does one retrieve just the game information?

@dynamic_cast: Your best bet is probably to use regex to remove the html tags.

Seems like the link to the documentation (http://www.giantbomb.com/api/documentation/) - is broke.

The correct address for the documentation is Seems like the link to the documentation is http://www.giantbomb.com/api/documentation without the slash :)

How do you search a game title and get back the id for the web page (3030-9169)? Or is there a way to download a complete game list with the associate identifiers?

http://www.giantbomb.com/api/documentation is getting me a 404 page...

@spitz1000: You need to remove the trailing slash, like so: giantbomb.com/api/documentation

giantbomb.com/api/documentation/ should work, but it doesn't.

I'm getting an 500 error when I try to access http://www.giantbomb.com/api to get a key

@pandaeskimo: Thanks for this ultra useful startup guide! This is exactly what I was looking for. Thanks again!

If you look in the results, you'll see something like:

site_detail_url: "http://www.giantbomb.com/metroid-prime/3030-15473/",

For the links, yeah, you have to remove the trailing '/'. It's pretty funny that the Giant Bomb text editor (WYSIWYG) adds those and breaks the links and that they don't have redirects. Oh well.

BTW, glad people have found this useful. I haven't used the API since I wrote this post and I haven't checked the forums, but thanks to those who have left helpful comments!

Hi,

is there any "modifiedSince" filter or do I have to go through offset/sort method?

I don't mean to necro-post, but I'm just wondering if the API documentation is intentionally 404'd:

https://www.giantbomb.com/api/documentation/

thanks!

@diachron: You'll have to drop the last forward slash: https://www.giantbomb.com/api/documentation

how do i retrieve boxart images for a specific platform?

Anyone know what the [id] is for on the video_categories api?

https://www.giantbomb.com/api/video_categories/[id]/?api_key=[YOUR API KEY]

The documentation doesn't mention it anywhere. I'm just trying to get a list of all possible video categories. I tried it by just putting "1" for the id and it seems to give me what I want so maybe the api is ignoring it anyway.

Hi I am testing out the service and have mistakenly called up the api to list every single game. As a result I now get "api key blocked due to malicious use" - is there any way to undo that? Thanks.

I have a similar problem to ericdgreene. I made a mistake by copying and pasting the sample URLs from quick start guide like this one (http://www.giantbomb.com/api/game/3030-4725/?api_key=[YOUR-KEY])and forgot to replace it with my actual key. I did it a couple times and now it says its telling me that I got blocked for using multiple API Keys and lists them as:

• %5BYOUR-KEY%5D
• [YOUR-KEY]
• and my actual API Key as the third one

I understand why that protocol exists, but in my case it was clearly an accident and not a form of abuse. I know it says that I will regain access in 24 hours, but I am a student and I am working on my final Capstone Project that is due in 10 days. I would really love it if I could regain access, or else I won't be able to do any work tomorrow at school.

This was helpful.