Giant Bomb API

An unofficial ruby wrapper for the Giantbomb API. An API that provides structured data about videogames. You should inform yourself about the endpoints at http://www.giantbomb.com/api/documentation .

This gem aims to provide access to most endpoints on the API. You'll be able to search, filter and page throught most of them. See further below on what is supported.

Contributors are welcome. Please contact @toadle.

Gem Version Code Climate Test Coverage Travis CI

Changelog

  • 2017-06-30: each_page-iterator instead of all, which supports rate-limiting. Thanks to @naiyt
  • 2015-09-19: Initial release as 0.5.1

Installation

As you'd expect. Nothing special here: 

gem install giant_bomb_api

or in your Gemfile

gem 'giant_bomb_api'

How to use

Configuration

Before you use GiantBombApi you need to configure it:

GiantBombApi.configure do |config|
  config.api_key = "your api-key"
end

Usage

There is several ways to query the GiantBomb-Database.

GiantBombApi.search("your query")

It will return a list of games that match you query.

If you want to be more specific, you can create your own search-request: 

GiantBombApi::Request::Search.new("your query", resources: [array of GiantBombApi::Resource-classes], limit: 100, page: 1)

e.g.

GiantBombApi::Request::Search.new("spelunky", resources: [GiantBombApi::Resource::Game], limit: 100, page: 1)

or

GiantBombApi::Request::Search.new("mario", resources: [GiantBombApi::Resource::Game, GiantBombApi::Resource::Character], limit: 100, page: 1)

your can then use GiantBombApi.client to send the request like: 

GiantBombApi.client.send_request(<your request>)

This returns a GiantBombApi::Response where your can find your results in response.results. This might be a collection of things or just one object.

Getting details

If you want a special object by ID you can just do something like:

GiantBombApi::Resource::Game.find(id)

Available resources are:

- GiantBombApi::Resource::Accessory
- GiantBombApi::Resource::Character
- GiantBombApi::Resource::Chat
- GiantBombApi::Resource::Company
- GiantBombApi::Resource::Concept
- GiantBombApi::Resource::Franchise
- GiantBombApi::Resource::Game
- GiantBombApi::Resource::GameRating
- GiantBombApi::Resource::Genre
- GiantBombApi::Resource::Location
- GiantBombApi::Resource::Object
- GiantBombApi::Resource::Person
- GiantBombApi::Resource::Platform
- GiantBombApi::Resource::Promo
- GiantBombApi::Resource::RatingBoard
- GiantBombApi::Resource::Region
- GiantBombApi::Resource::Release
- GiantBombApi::Resource::Review
- GiantBombApi::Resource::Theme
- GiantBombApi::Resource::UserReview
- GiantBombApi::Resource::Video
- GiantBombApi::Resource::VideoType

Requesting collections

You can also directly query a resource that has a collection-endpoint.

This is available for all resources that the Giantbomb API offers a 'collection' for. e.g. game and gamesor character and characters.

Use the each_page method to iterate through each page of a collection. each_page will accept a block and pass it the current page of results.

GiantBombApi::Resource::Game.each_page do |page|
  names = page.results.map(&:name)
  puts names
end

each_page accepts the following optional keyword arguments:

  • sort: a sort option for the results
  • limit: the number of results to return per page. Defaults to 100 (the max allowed through the Giant Bomb API)
  • offset: defaults to 0
  • should_rate_limit: pass this in as true if you want to ensure that you are rate limiting your requests to under the required 200 per resource per hour (which is important if you're trying to iterate through every page of a resource)
  • rate_per_hour: defaults to 200 (the standard Giant Bomb hourly request limit). Override this value if you want to send more requests per hour (not recommended) or less.

Example using the optional arguments:

GiantBombApi::Resource::Game.each_page(sort: { name: :desc }, limit: 50, should_rate_limit: true) do |page|
  # do something with the page
end

if you want to get more detailed your can do: 

GiantBombApi::Resource::Game.where(name: "spelunky", aliases: "something", sort: { name: :desc }, limit: 10, offset: 0)

Response

Every API-request will always return a GiantBombApi::Response-object that has the following attributes:

  • limit: The limit that applied
  • offset: The offset that applied
  • number_of_page_results: Guess!
  • number_of_total_results: Meeeh...
  • results: An array of stuff that you were looking for ;-)

For everything else I urge you to look through the code.

Feedback

Feedback and pull-request are always welcome. You can find the author via http://toadle.me

License

The giant_bomb_api-gem is released under the MIT License.