HowLongToBeat.com provides information and data about video games, and how long it will approximately take to finish them.
This library is a simple wrapper api to fetch data from HowLongToBeat. HowLongToBeat is an awesome website and a great service, free and also living from community data.
You get the option to get raw and extensive game data or a simplified, formatted version of it.
âš Disclaimer: This library is not affiliated nor endorsed with HowLongToBeat.com or Ziff Davis LLC in any way. Please use this library responsibly and do not abuse or overload the HowLongToBeat servers.
âš Verify you are running Golang version 1.20, by running
go versionin a terminal or console window. Older versions can produce errors, but newer versions are usually fine.âš HowLongToBeat uses go modules, there is no dependency on
$GOPATHvariable.
go get -u github.com/forbiddencoding/howlongtobeatpackage main
import (
"context"
"github.com/forbiddencoding/howlongtobeat"
)
func main() {
hltb, err := howlongtobeat.New()
if err != nil {
// error handling
}
// ...
}// ...
searchResults, err := hltb.Search(context.TODO(), "The Witcher 3: Wild Hunt", hltb.SearchModifierNone, nil)
if err != nil {
// error handling
}
// ...// ...
gameDetails, err := hltb.Detail(context.TODO(), 40171)
if err != nil {
// error handling
}
// ...A note about the returned data: When using the
Simplemethods, the data is already formatted and cleaned up, reducing it to the most commonly used data. Part of the formatting includes converting the time values from seconds to hours.If you find that the
Simplemethods, or theReducemethod respectively, trim away too much data, please open an issue and let me know. I am happy to add more data to theSimplemethods, if it is required by the community.
Search allows you to search for games by their name. It returns a raw list of search results. The result usually contains most of the data you would want or need, but might need to be formatted or cleaned up.
| Name | Type | Description |
|---|---|---|
query |
string |
The title of the game or DLC. |
modifier |
SearchModifier |
The search modifier to use. Possible values are:SearchModifierNone for the default behaviour returning both games as well as DLCs the default behaviourSearchModifierOnlyDLC to only get DLCs matching the search term or compatible with the gameSearchModiferHideDLC to only get games |
pagination |
*SearchGamePagination |
Used for custom pages sizes or pagination if too many matching result have been found by the HLTB API. The default page size is 20. |
// ...
searchResults, err := hltb.Search(context.TODO(), "The Witcher 3: Wild Hunt", hltb.SearchModifierNone, nil)
if err != nil {
// error handling
}
// ...{
"color": "blue",
"title": "",
"category": "games",
"count": 9,
"page_current": 0,
"page_total": 0,
"page_size": 0,
"data": [
{
"count": 9,
"game_id": 10270,
"game_name": "The Witcher 3: Wild Hunt",
"game_name_date": 0,
"game_alias": "The Witcher III: Wild Hunt",
"game_type": "game",
"game_image": "10270_The_Witcher_3_Wild_Hunt.jpg",
"comp_lvl_combine": 0,
"comp_lvl_sp": 1,
"comp_lvl_co": 0,
"comp_lvl_mp": 0,
"comp_lvl_spd": 1,
"comp_main": 184978,
"comp_plus": 371370,
"comp_100": 624261,
"comp_all": 369324,
"comp_main_count": 2316,
"comp_plus_count": 5663,
"comp_100_count": 1939,
"comp_all_count": 9918,
"invested_co": 0,
"invested_mp": 0,
"invested_co_count": 0,
"invested_mp_count": 0,
"count_comp": 18133,
"count_speedrun": 16,
"count_backlog": 18719,
"count_review": 4609,
"review_score": 94,
"count_playing": 426,
"count_retired": 1059,
"profile_dev": "CD Projekt RED",
"profile_popular": 1805,
"profile_steam": 292030,
"profile_platform": "Nintendo Switch, PC, PlayStation 4, PlayStation 5, Xbox One, Xbox Series X/S",
"release_world": 2015,
"similarity": 0.33
}
// ...
]
}SearchSimple allows you to search for games by their name. It returns a list of search results with a simplified structure, omitting data which is not usually needed.
| Name | Type | Description |
|---|---|---|
query |
string |
The title of the game or DLC. |
modifier |
SearchModifier |
The search modifier to use. Possible values are:SearchModifierNone for the default behaviour returning both games as well as DLCsSearchModifierOnlyDLC to only get DLCs matching the search term or compatible with the gameSearchModiferHideDLC to only get games |
// ...
searchResults, err := hltb.SearchSimple(context.TODO(), "The Witcher 3", SearchModifierNone)
if err != nil {
// error handling
}
// ...[
{
"game_id": 10270,
"game_name": "The Witcher 3: Wild Hunt",
"profile_platform": "Nintendo Switch, PC, PlayStation 4, PlayStation 5, Xbox One, Xbox Series X/S",
"game_image": "10270_The_Witcher_3_Wild_Hunt.jpg",
"comp_main": 51,
"comp_plus": 103,
"comp_all": 103,
"similarity": 0.33
}
// ...
]Detail allows you to get raw detailed information about a game or DLC by its ID.
| Name | Type | Description |
|---|---|---|
gameID |
int |
The ID of the game or DLC. Can be found as GameID by the search result or in the search bar of your browser when visiting the howlongtobeat.com |
// ...
game, err := hltb.Detail(context.TODO(), 10270)
if err != nil {
// error handling
}
// ...See response in example here.
DetailSimple allows you to get detailed information about a game or DLC by its ID. It returns a simplified structure (
similar to SearchSimple), omitting data which is not usually needed.
| Name | Type | Description |
|---|---|---|
gameID |
int |
The ID of the game or DLC. Can be found as GameID by the search result or in the search bar of your browser when visiting the howlongtobeat.com |
// ...
game, err := hltb.DetailSimple(context.TODO(), 10270)
if err != nil {
// error handling
}
// ...{
"game_id": 10270,
"game_name": "The Witcher 3: Wild Hunt",
"profile_platform": "Nintendo Switch, PC, PlayStation 4, PlayStation 5, Xbox One, Xbox Series X/S",
"game_image": "10270_The_Witcher_3_Wild_Hunt.jpg",
"comp_main": 51,
"comp_plus": 103,
"comp_all": 103
}If you used the Search or Detail function, you can call Reduce on the result variable to reduce the data in the
same way as SearchSimple andDetailSimple would do.
// ...
game, err := hltb.Detail(context.TODO(), 10270)
if err != nil {
// error handling
}
simpleGame := game.Reduce()
// ...| Project | Language |
|---|---|
| ckatzorke/howlongtobeat | TypeScript |
| ScrappyCocco/HowLongToBeat-PythonAPI | Python |
| ivankayzer/howlongtobeat | PHP |
| jameslieu/howlongtobeat | C# |
| saturnavt/howlongtobeat-api | Rust |
For help with common problems, please see TROUBLESHOOTING.md. If you encounter any other issues, feel free to open an issue.
We'd love your help in making this library better. Please review our contribution guidelines.
This project is licensed under the terms of the BSD-3 License. See the LICENSE for more details.