The New API -- Almost the Same as the Old API

Changelog

• [4.2.13] The date fields can now be filtered by a range of dates. The start and end date is separated by a pipe. Using one date will be considered as filtering for the exact date.
• [3.7.13] Removed companies from person resource call
• [3.7.13] The logic for video URLs will now follow these guidelines:
  • Non-premium API users gets low_url and high_url for non-premium videos.
  • Non-premium API users gets no video urls for premium videos.
  • Premium API users gets the low_url, high_url and the masked hd_url for every video.
• Added comma-delimited platform list to game search results
• Added platform abbreviation to game resource call
• Added version tag
• Empty values will return null instead of an empty string
• Added sorting and filtering on the list resource calls; check out the docs for available fields. Filtering by words is greedy and case-sensitive. When filtering against 'ids', multiple ids can be separated by a |. Example for sort and filter:
  
  • To sort by score descending, followed by the publish date ascending: http://api.giantbomb.com/reviews/?api_key=API_KEY&sort=score:desc,publish_date:asc
  • To filter for PC games with an expected release year of 2014: http://api.giantbomb.com/games/?api_key=API_KEY&filter=expected_release_year:2014,platforms:94
• Making a singular call will require the resource's type. Calling the types resource will provide a list of types for each resource. For example, to get the game Eve Online, it would be: http://api.giantbomb.com/game/3030-14447/?api_key=API_KEY
• Added Youtube ID to video resource call
• Use page instead of offset to paginate through search results; extended search limit to 100
• Removed platforms from character resource call

What Is The Same...For Now

• Singular resource call will still accept just an id, which means http://api.giantbomb.com/game/14447?api_key=API_KEY will still work.
• Added legacy support for the old sort and filter.
• The above two will be removed in 2-3 months time.

What To Expect In The Present

Initially, the first resource calls will be slow and/or timeout due to the image resizing. But subsequent calls that return the same results will be faster.

A Look to the Future

Login support, CORS support, Reverse API, New Resources

When Will The FutureArrive?

Way, way far in the future, past the rise of Comic Vine.

So there's still time to fix my random page script before it breaks?

Is this actually deployed yet - I'm not seeing any of the changes in my requests (IDs are still old format, no version, etc)?

It seems like it's halfway, in that the old stuff no longer works, and the new stuff isn't in place yet. >_<

Assuming I'm doing this right, this URL should give back the Aliens Colonial Marines Quick Look, right?

http://api.giantbomb.com/video/2300-7033/?api_key=API_KEY

The API should be deployed now. Old and new links should work. There may be some cases of the 500 error as seen on the rest of the site, refreshing clears it up until we get that server working correctly.

When I go to this URL (using my actual API key) I get details about the Aliens Quick Look, which is all good and well.

However, when I go to the next URL given back by that API call, under response -> results -> hd_url, I get some problems.

This next URL is: http://www.giantbomb.com/api/protected_video/2300-7033/?download=1

I try to go to this next URL, and I tack my "&api_key=<MY_API_KEY>" on the end, but everything except Chrome gives me some XML with a status code of 102, and an error element saying "Error in URL Format".

Chrome just starts playing the video, like everything is cool.

Help?

edit: "everything except Chrome" is Firefox, IE, wget, and curl.

The XML that comes back from the hd_url download URL follows:

<response><error>Error in URL Format</error><limit>0</limit><offset>0</offset><number_of_page_results>0</number_of_page_results><number_of_total_results>0</number_of_total_results><status_code>102</status_code><results/></response>

@frobie: I'm getting 503 errors on every request, for example

http://api.giantbomb.com/promos/?api_key=<KEY>

Hey all, we had to take this down due to some performance issues. We'll get it back up once it's stable.

@frobie: It would be really nice if the /search API could inherit the filters from for example /games, or that there's a better way to search for games with /games.

Searching for games at /games is not very efficient, for the ?filter=name:value parameter has to match the entire name. For example, /games/?filter=name:Guild%20Wars will not send back a list of titles that match Guild Wars, but instead an empty set. Though /games/?filter=name:World will give a list of titles that have World in it. How does this work?

Note: the api_key parameter is left out for the examples, but used when testing the above.

@claiver: This seems to work slightly better

http://www.giantbomb.com/api/games/?api_key=12345&filter=name:Guild,name:Wars

Sorry duders, we had to take down the api.giantbomb.com vanity URL because the load took down the servers.

@frobie: When do you plan on putting it back up? I have been getting a lot of questions about this.

Word is early next week. The stability of the site takes precedence over the API :(.

The release date seems to no longer be returned for unreleased games. Is there a way to get the release date of unreleased games? Possibly by region. I can see them on the Wiki.

@eclips said:

Cobbling together the three expected fields--expected_release_month, expected_release_quarter, expected_release_year--will give you the release date of an unreleased game. Each release resource returns a region associated to the release.

If I fill in the release date field for an unreleased game, there will be discrepancies when the only data available is either a year or a quarter.

@jondan said:

This is fixed. Non-chrome browsers will be able to play the video if the browser has a built-in video plugin or download the file if they do not. Also, a more descriptive error message has been added in cases were a non-subscriber tries to access the HD video.

This is fixed. The call for /games/?filter=name:Guild Wars will now return results. The matching is a case sensitive match for the name of the game containing the given phrase. ( e.g. name LIKE '%phrase%' )

@frobie: Much appreciated, keep up the good work!
I take it www.giantbomb.com/api/ will always be available, myes? In that case I'll just let my application rely on that url instead of the pretty api.giantbomb.com url.

Bit of a surprise last night when one of my users reported that my site was broken. Thankfully you had the fix posted here, but an API developer's mailing list might be a good idea. The API forum on here is pretty dead, so it's not something I check often.

Very pleased though that I don't have to make massive changes to my app to accommodate the API changes, so thanks for that. And I'm especially happy that the search method has finally been improved. Hooray for alias and special character support!

@frobie: Thanks for the response. Is there any plan for an expected release day? Looking up SimCity I can see March 2013 (Q1) but nothing tells me its the 5th.

@eclips said:

Added. However, there are some discrepancies with the day in cases where the day is not added to the expected date. We store the expected release date as a date value, so when a day is not entered, we default it to 1. I'll add this note to the documentation.

@claiver said:

Yes. In the future, a rewrite will be put in place to route that one to the pretty one.

Some of these changes do break existing libraries (like mine) but I've been able to accommodate the changes (namely, if you try and deserialize the JSON platforms for a game to an array you'll run into issues when GiantBomb returns a comma-delimited string for list resources, same with original game rating).

Some bugs I found:

• I'm still not getting data back for Morrowind's GOTY release: http://giantbomb.com/api/release/3050-29726/?api_key=<KEY>&format=json (500 error)
  • I can workaround this by using releases/?filter=id:29726 but then I lose out on some properties
• In release and platform resource (at least!), the date_last_udpatedis spelled wrong
• Platform resource abbreviationseems to be missing
• Seems like some games' release dates got messed up unless somebody knowingly allowed Skyrim to be edited as being released February 7, 2012. I submitted an edit to fix it.
  • Same is happening with The Witcher 3. On GB, the wiki editor says it's a 2013 release date. But the API is returningJan 15, 2013 which means it's released. I would expect expected_release_year == 2013, not original release date to be filled.

Man, some of these bugs are really throwing a wrench into my site... which is totally based on accurate release dates for games. Hope you guys can fix it soon.

I'll be releasing an update to GiantBomb-CSharp that works with the latest API.

Noted and committed fixes for listed bugs. Changed the platform and original game rating from a comma delimited list to an array; abbreviation included in the platform array.

Fixes will appear Tuesday unless someone does a ninja push to production over the weekend.

@frobie: Thank you!

I also noticed last night that the expected_release_month is included even when expected_release_quarter is there, is that a known issue? So my notifications from my site read: The Last of Us now has an estimated release date of Jun Q2 2013 (was 5/7/13). Previously if quarter was present, the month would be left off.

It's a little bit of a pickle, because how can I accurately determine whether a game's expected release really is the month it says vs. the quarter it says? For example, if quarter is present, it could trump, but then you have cases like The Last of Us (see below) where it really is June, not estimated to be Q2. It's really an expected_release_date vs. something that's not a solid estimate. I could say, if day and month are present, they trump quarter. But that still leaves cases where we know a game will come out in April 2013, yet the API will return Q2 April 2013, but "Q2 2013" has a different meaning than "April 2013".

For example:

Q2 begins in April, so if a game was expected to be released in April, the response would be:

• "expected_release_day": null,
• "expected_release_month": 4,
• "expected_release_quarter": 2,
• "expected_release_year": 2013,
• "original_release_date": null

What would you display? Q2 2013 or Apr 2013? Both have very different meanings to gamers.

My hope would be that one of those fields will be null if the other is present, and not include values for both (same as v1).

Also, the site AND the API list Watch_Dogs as being released in 2013, rather than unreleased but estimated to be released in 2013. I wish it were true, but I got a notification from my site saying it was released :( Same issue with Metro: Last Light. Looks like the estimated release year isn't being set correctly.

• "expected_release_day": null,
• "expected_release_month": null,
• "expected_release_quarter": null,
• "expected_release_year": null,
• "original_release_date": "2013-01-01 00:00:00",

With Destiny, I'm getting expected release date of January 14, 2014, yet the site just says 2014 (which is right):

• "expected_release_day": 14,
• "expected_release_month": 1,
• "expected_release_quarter": 1,
• "expected_release_year": 2014,

It also seems the logic for expected vs original has changed. For example, The Last of Us is expected to be released Jun 14, 2013. In APIv1, that would be in original_release_date but now it's part of the expected_release_* fields. I do like this better honestly, but is that the new standard going forward? Just want to make sure that's intentional.

• "expected_release_day": 14,
• "expected_release_month": 6,
• "expected_release_quarter": 2,
• "expected_release_year": 2013,
• "original_release_date": null

Lastly, I see you guys added DLC to game pages... any timeline on when that'll be added to the API? It would be awesome to track DLC releases on my site as well :D

PS. Please don't take my posts as any criticism... I love GB, after all you guys make sites like mine possible, I just want it to be the best it can be!

@subkamran: I don't take it as criticism, keep the suggestions coming.

Unfortunately, we're storing only one date for a release, so there is no way to determine if the expected release date is legitimately a month or just a quarter. The assumption made is that if the expected release date has passed then its considered the original release date and the expected fields will be null. The vice versa of this scenario holds true.

There was talk about adding new fields to store the expected date, I'll follow up to see where the status of that is.

There is no timetable to add new resources. I have to jump on getting the Comic Vine API up and running before I can add new features here.

Looks like a ninja push actually happened. Woot!

EDIT: Will fix the expected release date logic.

The promos resource seems to consist almost entirely of videos. It didn't work that way on the old site.

Also it would be nice if the video resource exposed the video's Youtube ID when available. Android has a new YouTube player API that I'd like to use for Giant Bomb videos but it's not currently possible unless I scrape the YouTube URL from the video page.

Awesome. The misspelled "date_last_udpated" field still looks to be outstanding but getting releases by ID and abbreviation are fixed.

Thanks again!

@frobie: I found a few bugs while testing my app:

1. The reviews resource uses the game field (like the V0 API), but the review item resource instead has games/release in its place
2. When I sort the promos resource by date_added desc it does affect the sort order but not in the way I'd expect (maybe stringwise sort instead of datewise?)
3. The promos resource seems to only contain video and chat items. For example - on the front page of the site the first promo is for this week's Worth Reading but it's nowhere in the promos resource return data
4. Character items are missing the platforms field
5. Person items are missing the companies field
6. We return a promo for an item that isn't up yet (first one in the list is for Monday's QL of Metal Gear)

@lordandrew

• Limited the promo resource call to return just the ones seen on the home page.
• Added Youtube ID as a field; value is null if the video has not been uploaded to youtube.

@subkamran

• Fixed the spelling mistake on the release resource and the dozen other places I did a bad copy/paste.
• Fixed the expected* date so that only one of the quarter/month pair will exist at a given time.

@thefaxman

• Per Dave, staff reviews are now tied to a release or dlc. To avoid confusion, I'll revert the game field to match what was returned in v0 and add a new release field for the review.
• The sort order is arbitrarily decided by the editors so date added isn't a factor. I'll make the default order match what is seen on the site.
• Fixed in LordAndrew's fix.
• Added platforms to character resource call.
• Added companies to person resource call.
• Removed unpublished promos from return.

Fixes will be in at next push to production.

@frobie: Just wanted to say thanks for the quick updates and fixes. After years of inactivity with the API, this feels like Christmas.

Thanks frobie. I really appreciate the great work you're doing here.

This! Thanks very much @frobie !

Awesome, thanks! I think that clears up my issues.

@frobie: One more bug today -

The image field for the chats resource returns a single string directly rather than the image format used elsewhere

@thefaxman said:

Fix will go live most likely tomorrow morning.

Was wondering if anybody else is experiencing the same problems that I am. I am trying to do queries against /search/ as well as a couple of others and they have all had the same behavior for the last few days. Offset and Limit do not appear to be working, and the results have defaulted back to limit 20 max instead of the new 100. Is this a known issue? I am currently unable to search for more than 20 entries because /search/?limit=20&offset=20&... is not returning the next page in the result set.

Aside from that, I am loving the new updated documentation page and the changes that have been made.

@frobie: There's an inconsistency with querying /games/ and a querying single game through /game/. Certain games with merely Stubs show up when requesting a list of games through /games/, but then I cannot load them individually, I get a "Object Not Found" message.

Example: World of Fantasy, shows up on /games/&filter=name:World%20of%20Fantasy but loading it through /game/3030-4975/ gives the error.
I think it would be good to either hide the stubs from /games/ or show the stubs at /game/.

@RoamingLost Fixed the search bug. Instead of offset to paginate through the results, use page instead. Also, increased the limit to 100 for search.

@claiver This is my bad. I didn't return results that did not have an image. Changed it to return the game even if images are missing.

Should be in production later today.

@frobie Some inconsistencies with the first page of search results. Setting the limit to 10 returns 11 results. In the response body "limit" is set to 12 and "number_of_page_results" is set to 11.

@frobie: the &page parameter seems to have no effect on the /games/ command; &offset works though.

Also: the pages numbers seems to be incorrect when querying /games/?limit=100&filter=platforms:94|17
It states my limit is 100, and the number_of_pages seems to be equal to the limit, as @beforeseven described above.

See here:

@claiver&page is just for the search. The rest of the list results will still use &offset. Reason being the search method I am using only accepts limit and page as parameters. From what I read, number_of_page_results represents the number of results returned in the query. So if you offset by 15940 in your example and do another query with a limit of 100, number_of_page_results will be 8.

@beforeseven There is a bit of weirdness to the search results due to the aliases. Let's say the limit is 10. The search method gathers >10 number of matches and does its magic to get the 10 most relevant matches. Of the 10, it drops the last two and prepends 2 alias results that match the query. If there are no alias matches, it just returns the 8. This happens for only the first page of the search results.

On my end, I am trying to account for those two alias results on the first page or lack thereof but it seems my hackery is failing to get the correct number of results. I'll take a look at it tomorrow.

@frobie: Do you think there would be any possibility to somehow have the URLs for the Squared images for games available (as used on the Giantbomb Games listing)?
That would work really well with listings of games, currently I need to use the small_url which is still about 300px in width; quite large and I need to scale them down to about 150x150, a bit of a loss of bandwidth.

@claiver We're doing the same thing you're doing--scaling down a larger image to a smaller image. The first game on the games listing page is using this image: http://static.giantbomb.com/uploads/square_small/0/389/533007-01___wow_.jpg

EDIT: The search count bug is fixed.

@frobie: I've noticed some requests to load specific entities fail even though I can see them on the site. For example - http://www.giantbomb.com/scott-k-tsumura/3040-5449/. When I try to request person 3040-5449 via the API I get an object not found error.

@thefaxman said:

Fix should be in and pushed to production after noon today. Also applied the same fix to the other resources that were not returning results that had no images.

I'm not sure if this is an API question or a site / video encoding question, but, since @frobie has fielded both, this thread seemed a decent place to ask:

The website has long offered video downloads at four quality levels (HD, High, Low, and Mobile) while the API only provides three (HD, High, and Low). Before the redesign, HD, High, and Low meant the same thing whether through site or API and, even though Mobile wasn't provided in the API, it was easy to infer due to the the consistent naming scheme. Unfortunately, things don't seem quite so clear for newer videos:

*Low is now called "Med" in the download menu on the site, though it's still referred to as "Low" in the video player & API

My question pretty much boils down to: how will the site and API correspond to each other going forward, if at all?

@soup_menu: nice catch. I was using the wrong low video for the API. Switching it to the 800 bitrate and should be out later today.

@frobie: Awesome, thanks. Are there any changes coming with regard to the Mobile quality (either it disappearing entirely or getting added to the API)? If not, would you be able to speak to if the ".ipod" or "_250" file is going to stick around as the new filename? I'd like to continue to provide Mobile as an option in my app, but only if I can do so reliably.

@soup_menu Our resident video encoder guru @rchen recommends sticking with the ".ipod" file, not because the "_250" will go away but that its barely watchable. The ipod file is encoded at 600 bitrate.