Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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 .

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


  • 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


As you'd expect. Nothing special here:

gem install giant_bomb_api

or in your Gemfile

gem 'giant_bomb_api'

How to use


Before you use GiantBombApi you need to configure it:

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


There is several ways to query the GiantBomb-Database.

General 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:"your query", resources: [array of GiantBombApi::Resource-classes], limit: 100, page: 1)

e.g."spelunky", resources: [GiantBombApi::Resource::Game], limit: 100, page: 1)

or"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:


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 =
  puts names

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

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)


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 and pull-request are always welcome. You can find the author via


The giant_bomb_api-gem is released under the MIT License.


An unofficial ruby wrapper for the Giantbomb API. An API that provides structured data about videogames.







No releases published


No packages published