HowLongToBeat Python API
A simple Python API to read data from howlongtobeat.com.
It is inspired by ckatzorke - howlongtobeat JS API.
Content
- HowLongToBeat Python API
Usage
Installation
Installing the package downloading the last release
pip install howlongtobeatpy
Installing the package from the source code
Download the repo, enter the folder with 'setup.py' and run the command
pip install .
Usage in code
Start including it in your file
from howlongtobeatpy import HowLongToBeat
Now call search()
The API main functions are:
results = HowLongToBeat().search("Awesome Game")
or, if you prefer using async:
results = await HowLongToBeat().async_search("Awesome Game")
The return of that function is a list of possible games, or None in case you passed an invalid "game name" as parameter or if there was an error in the request.
If the list is not None you should choose the best entry checking the Similarity value with the original name, example:
results_list = await HowLongToBeat().async_search("Awesome Game")
if results_list is not None and len(results_list) > 0:
best_element = max(results_list, key=lambda element: element.similarity)
Once done, "best_element" will contain the best game found in the research. Every entry in the list (if not None in case of errors) is an object of type: HowLongToBeatEntry.
Alternative search (by ID)
If you prefer, you can get a game by ID, this can be useful if you already have the game's howlongtobeat-id (the ID is the number in the URL, for example in https://howlongtobeat.com/game/7231 the ID is 7231).
To avoid a new parser, the search by ID use a first request to get the game title, and then use the standard search with that title, filtering the results and returning the unique game with that ID.
Remember that it could be a bit slower, but you avoid searching the game in the array by similarity.
Here's the example:
result = HowLongToBeat().search_from_id(123456)
or, if you prefer using async:
result = await HowLongToBeat().async_search_from_id(123456)
This call will return an unique HowLongToBeatEntry or None in case of errors.
DLC search
An enum has been added to have a filter in the search:
SearchModifiers.NONE # default
SearchModifiers.ISOLATE_DLC
SearchModifiers.HIDE_DLC
This optional parameter allow you to specify in the search if you want the default search (with DLCs), to HIDE DLCs and only show games, or to ISOLATE DLCs (show only DLCs).
Results auto-filters
To ignore games with a very different name, the standard search automatically filter results with a game name that has a similarity with the given name > than 0.4, not adding the others to the result list.
If you want all the results, or you want to change this value, you can put a parameter in the constructor:
results = HowLongToBeat(0.0).search("Awesome Game")
putting 0.0 (or just 0) will return all the found games, otherwise you can write another (float) number between 0...1 to set a new filter, such as 0.7.
Also remember that by default the similarity check is case-sensitive between the name given and the name found, if you want to ignore the case you can use:
results = HowLongToBeat(0.0).search("Awesome Game", similarity_case_sensitive=False)
Remember that, when searching by ID, the similarity value and the case-sensitive bool are ignored.
An auto-filter for game-types has been added, it is not active by default (False) but can be used as:
results = HowLongToBeat(input_auto_filter_times = True).search("The Witcher 3")
That auto-filter "nullify" values based on the game-type, if it is a singleplayer game then the coop/multiplayer values are overridden to Null; on the other side if it is a Multiplayer game the singleplayer values such as "main story" could be overridden to Null if that game doesn't have a story. Use with caution, it is probably better if you decide what fits best for you.
Reading an entry
An entry is made of few values, you can check them in the Entry class file. It also include the full JSON of values (already converted to Python dict) received from HLTB.
Issues, Questions & Discussions
If you found a bug report it as soon as you can creating an issue, the code may not be perfect.
If you need any new feature, or want to discuss the current implementation/features, consider opening a discussion or even propose a change with a Pull Request.
Authors
- ScrappyCocco - Thank you for using my API
License
This project is licensed under the MIT License - see the LICENSE.md file for details
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file howlongtobeatpy-1.0.23.tar.gz.
File metadata
- Download URL: howlongtobeatpy-1.0.23.tar.gz
- Upload date:
- Size: 16.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1445bcd72b90c8172e7858ffe46ff357bc4d4b360a74299701dd04418a2296eb
|
|
| MD5 |
00520e4dcb8e38254083f7589460fa0c
|
|
| BLAKE2b-256 |
b7b11f70430e1afd9b4d7e1441e4246e030a06551a68c7cbe67e76c712756c67
|
Provenance
The following attestation bundles were made for howlongtobeatpy-1.0.23.tar.gz:
Publisher:
manual-publish-version.yml on ScrappyCocco/HowLongToBeat-PythonAPI
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
howlongtobeatpy-1.0.23.tar.gz -
Subject digest:
1445bcd72b90c8172e7858ffe46ff357bc4d4b360a74299701dd04418a2296eb - Sigstore transparency entry: 2582997341
- Sigstore integration time:
-
Permalink:
ScrappyCocco/HowLongToBeat-PythonAPI@145b3e76715ccb3541a94349d589657113e4da20 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/ScrappyCocco
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
manual-publish-version.yml@145b3e76715ccb3541a94349d589657113e4da20 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file howlongtobeatpy-1.0.23-py3-none-any.whl.
File metadata
- Download URL: howlongtobeatpy-1.0.23-py3-none-any.whl
- Upload date:
- Size: 13.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9faff74f6a864f96d6a72b2871ce91845cfee06533ed867441f2156e535f920c
|
|
| MD5 |
762ef9dfc5d7d44561323d80a77d36ff
|
|
| BLAKE2b-256 |
53794627a4f61942bea808a7dcc7de9392a511cc9c7ea3ab62cc444ff68c8a2a
|
Provenance
The following attestation bundles were made for howlongtobeatpy-1.0.23-py3-none-any.whl:
Publisher:
manual-publish-version.yml on ScrappyCocco/HowLongToBeat-PythonAPI
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
howlongtobeatpy-1.0.23-py3-none-any.whl -
Subject digest:
9faff74f6a864f96d6a72b2871ce91845cfee06533ed867441f2156e535f920c - Sigstore transparency entry: 2582997349
- Sigstore integration time:
-
Permalink:
ScrappyCocco/HowLongToBeat-PythonAPI@145b3e76715ccb3541a94349d589657113e4da20 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/ScrappyCocco
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
manual-publish-version.yml@145b3e76715ccb3541a94349d589657113e4da20 -
Trigger Event:
workflow_dispatch
-
Statement type:
