HowLongToBeat Ruby API

A simple Ruby API to read data from howlongtobeat.com.

It is inspired by ScrappyCocco's HowLongToBeat Python API.

Add this line to your application's Gemfile:

gem 'howlongtobeat'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install howlongtobeat

Keep one Client per process: use HowLongToBeat::Client.default, or build a single instance of your own. It paces requests (2 seconds apart by default) and caches the search endpoint and auth token, so every extra instance pays for its own endpoint discovery. Errors are distinct, so "rate-limited" never looks like "not found". The legacy HowLongToBeat::HowLongToBeat API uses Client.default unless you pass client:.

client = HowLongToBeat::Client.default

detail = client.game(10270)          # one request; nil if HLTB's 404 page says there is no such game
detail.main_story                    # => 51.68 (hours)
detail.steam_app_id                  # => 292030

begin
  client.search("The Witcher 3")     # => [HowLongToBeat::SearchResult, ...]; [] when nothing matches
rescue HowLongToBeat::RateLimitedError
  # HLTB answered 429: back off before trying again
rescue HowLongToBeat::RequestError
  # network failure, timeout or an HTTP error: retry later
rescue HowLongToBeat::ParseError
  # HLTB changed its site, so the gem needs an update
end

HowLongToBeat has no official API and rate-limits bursts. Please keep the default pacing.

require 'howlongtobeat'

hltb = HowLongToBeat::HowLongToBeat.new
results = hltb.search("The Witcher 3")

The search method returns an array of possible games ([] when nothing matches), or nil if the game name is empty or the request failed.

Each result is an HowLongToBeatEntry object containing:

• game_id: The game's ID on HowLongToBeat (Integer)
• game_name: The game's name (String)
• game_alias: Alternative names for the game (String)
• game_type: Type of content (e.g., "game", "dlc") (String)
• game_image_url: URL to the game's cover image (String)
• game_web_link: URL to the game's HowLongToBeat page (String)
• review_score: User review score (Integer, 0-100)
• profile_dev: Developer information (String)
• profile_platforms: Available platforms (Array of Strings)
• release_world: Release year (Integer)

• main_story: Main story completion time (Float)
• main_extra: Main story + side quests completion time (Float)
• completionist: 100% completion time (Float)
• all_styles: Average time across all playstyles (Float)
• coop_time: Co-op gameplay time (Float)
• mp_time: Multiplayer gameplay time (Float)

• complexity_lvl_combine: Combined gameplay complexity (Boolean)
• complexity_lvl_sp: Single-player complexity (Boolean)
• complexity_lvl_co: Co-op complexity (Boolean)
• complexity_lvl_mp: Multiplayer complexity (Boolean)

• similarity: How closely the game name matches the search query (Float, 0.0 to 1.0)
• json_content: Raw JSON data from the API (Hash)

You can also search for a game using its HowLongToBeat ID:

result = hltb.search_from_id(10270)  # The Witcher 3: Wild Hunt

This returns a single HowLongToBeatEntry object or nil if not found.

Since 0.3.0 search_from_id reads the game page in one request, so it fills fewer fields than before (no image URL, review score, developer, platforms, JSON content or complexity flags). See the CHANGELOG for the exact list.

You can filter your search results using modifiers:

hltb = HowLongToBeat::HowLongToBeat.new
results = hltb.search("The Witcher 3", HowLongToBeat::HTMLRequests::SearchModifiers::HIDE_DLC)

Available modifiers:

• NONE: Default search (includes DLCs)
• ISOLATE_DLC: Show only DLCs
• ISOLATE_MODS: Show only mods
• ISOLATE_HACKS: Show only hacks
• HIDE_DLC: Hide DLCs and show only games

By default, the search filters results with a similarity score greater than 0.4. You can adjust this threshold:

# Return all results without filtering
hltb = HowLongToBeat::HowLongToBeat.new(0.0)
results = hltb.search("The Witcher 3")

# Use a higher threshold for stricter matching
hltb = HowLongToBeat::HowLongToBeat.new(0.7)
results = hltb.search("The Witcher 3")

This gem was originally created for and is being used by SearchToPlay, a platform that helps gamers discover and track their gaming journey.

After checking out the repo, run bundle install to install dependencies. Then run bundle exec rspec --tag '~live' to run the offline tests. rake spec runs everything, including the live specs that call howlongtobeat.com (paced, about 3 minutes); run those with bundle exec rspec --tag live before a release.

Bug reports and pull requests are welcome on GitHub.

The gem is available as open source under the terms of the MIT License.