Quick Start Guide to Using the API

Avatar image for pikapomelo
pikapomelo

33

Forum Posts

2

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#1  Edited By pikapomelo

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!

Avatar image for pikapomelo
pikapomelo

33

Forum Posts

2

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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?

Avatar image for thatuxguy
thatuxguy

5

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#3  Edited By thatuxguy

Can we get the documentation in PDF format?

Avatar image for dynamic_cast
dynamic_cast

8

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#5  Edited By dynamic_cast

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

Avatar image for chaser324
chaser324

8762

Forum Posts

14877

Wiki Points

0

Followers

Reviews: 1

User Lists: 11

#6 chaser324  Moderator

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

Avatar image for Karthas
Karthas

153

Forum Posts

324

Wiki Points

0

Followers

Reviews: 0

User Lists: 5

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

Avatar image for reality3d
reality3d

2

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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

Avatar image for rangersedge
rangersedge

8

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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?

Avatar image for spitz1000
spitz1000

213

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

Avatar image for devinant
Devinant

33

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 1

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

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

Avatar image for xwalrus11
xWalrus11

2

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

Avatar image for eriklougee
eriklougee

2

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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

Avatar image for pikapomelo
pikapomelo

33

Forum Posts

2

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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?

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!

Avatar image for droid_ste
droid_ste

1

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

Hi,

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

Avatar image for diachron
Diachron

104

Forum Posts

383

Wiki Points

0

Followers

Reviews: 0

User Lists: 10

#16  Edited By Diachron
Avatar image for alecgdouglas
alecgdouglas

107

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#17  Edited By alecgdouglas

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

Avatar image for t3612965
t3612965

1

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#18  Edited By t3612965

how do i retrieve boxart images for a specific platform?

Avatar image for jgittins
jgittins

27

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

#19  Edited By jgittins

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.

Avatar image for ericdgreene
ericdgreene

1

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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.

Avatar image for batkins4
batkins4

1

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

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.

Avatar image for coderevolution
CodeRevolution

5

Forum Posts

0

Wiki Points

0

Followers

Reviews: 0

User Lists: 0

This was helpful.