Python

This guide uses only the Python standard library (Python 3.8 and later), so there is nothing to install. It runs on a computer or a server; see Calling the API from a browser for why it is not meant to run in a visitor’s browser.

A helper

import json
import urllib.error
import urllib.parse
import urllib.request

BASE = "https://bazoodle.com/api/v1"
USER_AGENT = "MyGameList/1.0 (contact: you@example.com)"


def api(path, **params):
    query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
    url = BASE + path + ("?" + query if query else "")
    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
    try:
        with urllib.request.urlopen(request, timeout=20) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        if error.code == 429:
            wait = error.headers.get("Retry-After", "60")
            raise RuntimeError("Slow down: try again in " + wait + " seconds")
        try:
            message = json.load(error).get("error", {}).get("message", "")
        except ValueError:
            message = ""
        raise RuntimeError(str(error.code) + " " + message)

Change USER_AGENT to describe your own tool. The timeout (20 seconds) stops a slow network from hanging your program. The other Python examples use this api helper.

List games

page = api("/catalog/browse", sort="new", limit=5)
for game in page["games"]:
    players = game["players"]
    print(game["title"], str(players["min"]) + "-" + str(players["max"]), "players", "https://bazoodle.com/game/" + game["id"])
print("next page starts at:", page["next_offset"])

Search

found = api("/catalog/search", q="coin")
print([game["title"] for game in found["games"]])

One game

game = api("/catalog/games/coins")
print(game["title"], "-", game["description"])
print("similar:", [g["title"] for g in game["similar"]])

Times and missing values

Times in responses are whole seconds since 1 January 1970 UTC, and some fields are None (JSON null) when there is nothing to show. Convert and check them before use:

from datetime import datetime, timezone

game = api("/catalog/games/coins")
updated = datetime.fromtimestamp(game["updated_at"], tz=timezone.utc)
print("updated", updated.date(), "version", game["version"])
rating = "not rated yet" if game["like_pct"] is None else str(game["like_pct"]) + "% liked"
print(rating)

like_pct is None until a game has at least five votes, and thumbnail_url is None for a game without a picture: always check before you use them. See Making requests for the full list of response rules.

Handling a mistake

try:
    api("/catalog/browse", sort="best")
except RuntimeError as error:
    print(error)  # 400 sort must be popular, new or top

Tips

• Cache results; see Limits and caching.
• If you use the requests library instead, the calls are the same: requests.get(BASE + path, params=params, headers=...).
• To list more than one page, or to download pictures, see Be resilient and Show a game page.