If you’re here, you’re probably familiar with my Itch recommendation engine. This is the documentation for the API related to that engine. If you’re interested, here are the details of how the recommendation engine works.
The API is available here: https://liverealproductions.com/gamesearch/api.php. Currently, there is no need for an API key, but that will change if this is abused.
First, there are 2 global arguments.
- result. If this is omitted, the results will be json. Set this to “result=xml” to get xml results.
- limit. For any API call that returns multiple records, this is how many records are returned. This affects search, bundles, and random games. If this is omitted, the default value is 10. It maxes out at 200 records. (limit=200)
For the most part, the API takes the same parameters as the gamesearch page, so you can look in the url bar there for syntax.
Functions
Default/Random Recommendations
The default function is to return a random game and games that are similar to that game. If you follow @notjwalberg4 on Twitter, you’ve seen this in action. That’s a bot that says “If you like game X, you may like game Y.”
Examples:
https://liverealproductions.com/gamesearch/api.php?limit=5
https://liverealproductions.com/gamesearch/api.php?limit=3&result=xml
Game Details
This retrieves the details of a specific game, based on the game ID from Itch. The argument is “game”. It also retrieves games that are similar to this game in the retrieve child object. This is using the Games Similar To function below.
Example: https://liverealproductions.com/gamesearch/api.php?game=1313603
Search
This is a functional search. It uses all of the data points available to match what you are looking for to the physical games available on itch. The argument is “search=”.
Example: https://liverealproductions.com/gamesearch/api.php?search=eternity
Bundles
This returns games included in specific bundles. The argument is “bundle”.
As of 2022/11/08, the implemented bundles are “solo but not alone 2022”, “trans rights texas”, “ukraine”, “reproductive2”, and “reproductive”, which respectively represent the “Solo But Not Alone 2”, “TTRPGs for Trans Rights in Texas!”, “Bundle for Ukraine”, “TTRPGs for Reproductive Rights”, and “Reproductive Rights Bundle” bundles.
Example: https://liverealproductions.com/gamesearch/api.php?bundle=ukraine
Authors
This returns all of the games for a given author, by author name. The argument is “author=”.
Example: https://liverealproductions.com/gamesearch/api.php?author=Live%20Real%20Press&result=xml
Stats
This returns the statistics on the games that have been included in the recommendation engine. The argument is “show=stats”. As of this writing, there are 20,697 games matched across 736,581 comparison points.
Example: https://liverealproductions.com/gamesearch/api.php?show=stats
Tags
This returns games using a specific tag. The argument is “tags”. Leaving this blank will return untagged games.
Example: https://liverealproductions.com/gamesearch/api.php?tags=lumen
Tag Cloud
This returns the data that drives the tag cloud on the gamesearch page. It is a list of used tags and the frequency they are used. The frequency is not an actual count. The argument is “tagcloud”.
Example: https://liverealproductions.com/gamesearch/api.php?tagcloud
Games Similar To
This retrieves a random list of games that are similar to the game ID you pass in. The argument is “likethis”. This uses a proprietary AI-driven comparison algorithm.
Example: https://liverealproductions.com/gamesearch/api.php?likethis=1313603
This Game is Similar To
This retrieves a random list of games that this game is similar to. The argument is “thislike”. Depending on the game, this may have a lot of overlap with “likethis”.
Example: https://liverealproductions.com/gamesearch/api.php?thislike=1313603