hltb-client

hltb-client

A TypeScript client for the HowLongToBeat API. Get game completion times programmatically.

Installation

npm install hltb-client

Usage

Basic Example

import { HLTBClient } from 'hltb-client';

const client = new HLTBClient();

// Search for games
const games = await client.search('Elden Ring');
console.log(games[0]);
// {
//   id: '68151',
//   name: 'Elden Ring',
//   imageUrl: 'https://howlongtobeat.com/games/68151_Elden_Ring.jpg',
//   completionTimes: { main: 60, mainExtra: 101, completionist: 136, allStyles: 98 },
//   platforms: 'PC, PlayStation 4, PlayStation 5, Xbox One, Xbox Series X/S',
//   releaseYear: 2022,
//   reviewScore: 92
// }

// Get a single game
const game = await client.searchOne('The Witcher 3');

// Get just completion times
const times = await client.getCompletionTimes('Zelda Breath of the Wild');
console.log(times);
// { main: 50, mainExtra: 98, completionist: 189, allStyles: 97 }

CommonJS

const { HLTBClient } = require('hltb-client');

const client = new HLTBClient();
const games = await client.search('Dark Souls');

API Reference

new HLTBClient(options?)

Creates a new HLTB client instance.

Options

Option	Type	Default	Description
userAgent	string	Chrome UA	Custom user agent string
tokenCacheDuration	number	3600000	Token cache duration in ms (1 hour)

client.search(query, options?)

Search for games by name.

Parameters:

• query (string) - Search query
• options (object, optional)
  • limit (number) - Max results to return (default: 20)
  • platform (string) - Filter by platform
  • sortBy (string) - Sort by: 'popular', 'name', 'rating', 'length', 'release'

Returns: Promise<HLTBGame[]>

const games = await client.search('Mario', { limit: 5, sortBy: 'popular' });

client.searchOne(name)

Search for a single game by name. Returns the best match.

Parameters:

• name (string) - Game name to search for

Returns: Promise<HLTBGame | null>

const game = await client.searchOne('Hollow Knight');
if (game) {
  console.log(`${game.name}: ${game.completionTimes.main} hours`);
}

client.getCompletionTimes(name)

Get completion times for a game. Convenience method that returns just the times.

Parameters:

• name (string) - Game name to search for

Returns: Promise<HLTBCompletionTimes>

const times = await client.getCompletionTimes('Celeste');
console.log(`Main story: ${times.main} hours`);
console.log(`Completionist: ${times.completionist} hours`);

Types

HLTBGame

interface HLTBGame {
  id: string;                           // HowLongToBeat game ID
  name: string;                         // Game name
  imageUrl?: string;                    // Cover image URL
  completionTimes: HLTBCompletionTimes; // Completion times in hours
  platforms?: string;                   // Available platforms
  releaseYear?: number;                 // Release year
  reviewScore?: number;                 // User score (0-100)
}

HLTBCompletionTimes

interface HLTBCompletionTimes {
  main?: number;         // Main story (hours)
  mainExtra?: number;    // Main + extras (hours)
  completionist?: number; // 100% completion (hours)
  allStyles?: number;    // Average of all playstyles (hours)
}

HLTBSearchOptions

interface HLTBSearchOptions {
  limit?: number;    // Results to return (default: 20)
  platform?: string; // Platform filter
  sortBy?: 'popular' | 'name' | 'rating' | 'length' | 'release';
}

Error Handling

The client throws errors for network issues or authentication failures:

try {
  const games = await client.search('Some Game');
} catch (error) {
  if (error.message.includes('authentication')) {
    console.error('Failed to authenticate with HLTB');
  } else {
    console.error('Network error:', error.message);
  }
}

How It Works

This client interfaces with HowLongToBeat's internal API:

• Fetches an authentication token from /api/search/init
• Uses the token to make search requests to /api/search
• Caches tokens for 1 hour to minimize requests

Rate Limiting

HowLongToBeat doesn't publish rate limits. This client:

• Caches auth tokens to reduce requests
• Makes one token request per hour max
• Does not implement request throttling (add your own if needed)

Disclaimer

This is an unofficial client. HowLongToBeat doesn't provide a public API, so this library may break if they change their internal API. Use responsibly.

License

MIT