DOCSEARCHbyAlgolia
Submit Docs

howlongtobeat

repository·master·Indexed 19 days ago

https://github.com/ckatzorke/howlongtobeat

A simple API wrapper for the HowLongToBeat website (version 1.8.0) that allows developers to programmatically search for games and retrieve estimated completion times, such as Main Story and Completionist runs, via the HowLongToBeatService class.

Tokens
1.4K
Snippets
6
Records
8
Agent score
15%

What's inside howlongtobeat

  1. Understand HowLongToBeatEntry data and timeLabels

    master

    The HowLongToBeatEntry object contains game metadata and time estimates.

    Key fields include:

    • id: Unique identifier for the game.
    • name: Title of the game.
    • imageUrl: URL to the game's image.
    • gameplayMain: Hours for the Main Story.
    • gameplayMainExtra: Hours for Main + Extras.
    • gameplayCompletionist: Hours for Completionist run.
    • timeLabels: An array used for mapping time categories to their descriptions.

    The timeLabels attribute maps to the 7 different ways HLTB counts game hours:

    • Main Story
    • Main + Extras
    • Completionist
    • Single-Player
    • Solo
    • Co-Op
    • Vs.

  3. Initialize HowLongToBeatService

    master

    To use the API, you must instantiate the HowLongToBeatService class. This can be done using CommonJS require or TypeScript/ESM import syntax.

    // JavaScript (CommonJS)
let hltb = require('howlongtobeat');
let hltbService = new hltb.HowLongToBeatService();
    // TypeScript
import { HowLongToBeatService, HowLongToBeatEntry } from 'howlongtobeat';

let hltbService = new HowLongToBeatService();

  5. Get game details using detail()

    master

    The detail(id) method fetches specific information for a single game using its unique ID. It returns a Promise that resolves to a HowLongToBeatEntry object.

    Note: If the provided ID is unknown, the promise will reject with an error. You should always include a .catch() block to handle potential errors.

    hltbService.detail('36936').then(result => console.log(result)).catch(e => console.error(e));

  6. Calculate string similarity with HowLongToBeatService.calcDistancePercentage

    master

    The static method calcDistancePercentage(text: string, term: string): number calculates the similarity between two strings using Levenshtein distance. It returns a value between 0 and 1, where 1 represents an exact match (after trimming and lowercasing). This is useful for ranking search results based on how closely the game name matches the user's query.

    import { HowLongToBeatService } from 'howlongtobeat';

const similarity = HowLongToBeatService.calcDistancePercentage('Elden Ring', 'elden ring');
// similarity will be 1.0

  7. Use HowLongToBeatService to fetch game data

    master

    The HowLongToBeatService class is the primary entry point for interacting with the HowLongToBeat API. It provides methods to search for games and retrieve detailed information for a specific game using its internal ID.

    Methods

    • search(query: string, signal?: AbortSignal): Promise<Array<HowLongToBeatEntry>> Performs a search based on a query string. Returns an array of HowLongToBeatEntry objects.
    • detail(gameId: string, signal?: AbortSignal): Promise<HowLongToBeatEntry> Fetches the full details for a specific game using its HowLongToBeat internal gameId.
    import { HowLongToBeatService } from 'howlongtobeat';

const service = new HowLongToBeatService();

// Search for games
const searchResults = await service.search('Elden Ring');

// Get specific game details
if (searchResults.length > 0) {
  const details = await service.detail(searchResults[0].id);
  console.log(details.name, details.gameplayMain);
}

  8. Understand the HowLongToBeatEntry data structure

    master

    The HowLongToBeatEntry class encapsulates all information retrieved for a game.

    Properties

    PropertyTypeDescription
    idstringThe internal HowLongToBeat game ID
    namestringThe name of the game
    descriptionstringA brief description of the game
    platformsstring[]List of platforms the game is playable on
    imageUrlstringURL to the game's cover image
    timeLabelsArray<string[]>Metadata mapping time types to labels (e.g., [['gameplayMain', 'Main Story']])
    gameplayMainnumberEstimated hours for the main story
    gameplayMainExtranumberEstimated hours for main story + extra content
    gameplayCompletionistnumberEstimated hours for full completion
    similaritynumberSimilarity score (0-1) between the search term and the game name
    searchTermstringThe original search term used
    playableOnstring[]Deprecated: Alias for platforms

    Note: playableOn is maintained for backward compatibility but you should use platforms instead.