howlongtobeatpy Python API

The API includes automatic filters to ignore results with low similarity to your search term. By default, results must have a similarity > 0.4.

• Adjust Similarity Threshold: Pass a float between 0.0 and 1.0 to the HowLongToBeat constructor. Setting it to 0.0 returns all found games.
• Case Sensitivity: By default, similarity checks are case-sensitive. Set similarity_case_sensitive=False in the search() method to ignore case.

# Return all found games regardless of similarity
results = HowLongToBeat(0.0).search("Awesome Game")

# Search with a specific similarity threshold and ignore case
results = HowLongToBeat(0.7).search("Awesome Game", similarity_case_sensitive=False)

You can install the package via pip for the latest release or from the source code.

# Install the latest release
pip install howlongtobeatpy

# Or install from source code
# Download the repo, enter the folder with 'setup.py' and run:
pip install .

Use the HowLongToBeat class to search for games by name. The search() method returns a list of HowLongToBeatEntry objects, or None if the name is invalid or an error occurs.

Because the search returns multiple possible matches, it is recommended to select the best result by checking the similarity attribute of the returned entries.

from howlongtobeatpy import HowLongToBeat

# Synchronous search
results = HowLongToBeat().search("Awesome Game")

# Asynchronous search
results = await HowLongToBeat().async_search("Awesome Game")

# Selecting the best match based on similarity
if results is not None and len(results) > 0:
    best_element = max(results, key=lambda element: element.similarity)

When initializing HowLongToBeat, you can set input_auto_filter_times=True. This feature automatically 'nullifies' time values that don't match the game type. For example, if a game is singleplayer, coop/multiplayer values are set to Null. If it is multiplayer, singleplayer values like 'main story' may be set to Null. Use this with caution.

# Enable auto-filtering of game-type specific values
results = HowLongToBeat(input_auto_filter_times=True).search("The Witcher 3")

If you have the specific HowLongToBeat ID (the number found in the game's URL, e.g., 7231 from howlongtobeat.com/game/7231), you can use search_from_id() or async_search_from_id().

This method returns a single HowLongToBeatEntry object or None. It is slightly slower than a direct search because it performs an initial request to find the title before searching, but it avoids the need for manual similarity filtering.

from howlongtobeatpy import HowLongToBeat

# Synchronous search by ID
result = HowLongToBeat().search_from_id(123456)

# Asynchronous search by ID
result = await HowLongToBeat().async_search_from_id(123456)

You can use the SearchModifiers enum to filter whether DLCs are included in your search results. This is an optional parameter passed to the search methods.

# Available SearchModifiers:
# SearchModifiers.NONE (default)
# SearchModifiers.ISOLATE_DLC
# SearchModifiers.HIDE_DLC