pikapomelo

Enjoyed reading! Thanks.

I do feel a little bad when I run around on a horse and spam magic at bosses, but... not too bad. I've put in my hours with swords and rolling.

There are also those enemies like the dragons that seem impossible without shooting a billion arrows as they go though their path.

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!

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?

I encountered a similar issue with search. Search seems to ignore by "resource_type" filter. Instead, I just get all results.

Example,

http://www.giantbomb.com/api/search/?api_key=[your-key]&format=json&query=%22metroid%20prime%22&resource_type=game

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!

Thanks, I'll try to make a thread with info.

I just started trying the API (btw, is there any documentation in terms of formatting the URLs?) and ran into a weird issue.

It seems like the first query I send gets cached and any subsequent queries with the same number of arguments get the results from that first query.

Here is an example (Metroid Prime 3),

http://www.giantbomb.com/api/game/3030-4725/?api_key=<key-removed>&format=json&field_list=description,image,aliases

If I do this the first time, I get the correct results. However, if I change the field_list to "description,image,name" I get the same results. If I change the number of arguments, this doesn't happen.

For example,

http://www.giantbomb.com/api/game/3030-4725/?api_key=fb4ddf4291080ec0826929e3e84b6d9909b1ca16&format=json&field_list=description

Am I using this incorrectly?

I've been force refreshing the browser (Chrome on Win8) and it doesn't seem to do anything.

Btw, if there isn't a quick set of documentation / an example, I could try to put a page together. It seems fairly straight forward, but I got as far as I did above through guessing and looking through random threads for people with issues.

Thank you,

Dan