Install and make a request
Install the package from PyPI. No API key is needed.
pip install gzw-datafrom gzw_data import GzwDataClient
client = GzwDataClient()
weapon = client.get("weapons", "ak-12")
print(weapon["name"], weapon["caliber"])
page = client.list("weapons", per_page=5)
print(page["total"], [w["name"] for w in page["data"]])Every method returns plain dictionaries and lists, exactly as the API sends them.
Datasets and records
datasets() maps every dataset name to its record count. get() returns one record, or None when the id does not exist. iterate() walks every page for you.
names = client.datasets() # {'ammo': 79, 'weapons': 44, ...}
print(len(names), "datasets")
record = client.get("weapons", "does-not-exist") # None
for ammo in client.iterate("ammo"): # every record, page by page
print(ammo["name"])list() returns one page with the full response envelope: data, page, perPage, total and totalPages.
Search and filters
Search inside one dataset with search=, or across all datasets with search(). Extra keyword arguments become query filters.
# Inside one dataset
for gun in client.iterate("weapons", search="AK"):
print(gun["name"])
# Across every dataset: {dataset name: [records]}
results = client.search("AK-12")
print(list(results))
# Filter by any string field
keycards = client.list("keys", type="Keycard", per_page=25)Errors and retries
Failures raise GzwApiError with status, a stable code, the request url and, for rate limits, retry_after in seconds. Rate-limit (429) and server (5xx) responses are retried with backoff, and a Retry-After header is honoured up to max_retry_wait. Client errors such as 404 or 400 are not retried.
from gzw_data import GzwApiError, GzwDataClient
client = GzwDataClient()
try:
client.list("not_a_dataset")
except GzwApiError as error:
print(error.status, error.code) # 404 ENDPOINT_NOT_FOUNDConfiguration
All options are keyword arguments of GzwDataClient.
client = GzwDataClient(
base_url="https://gzw-data.dev/api/v1", # default
timeout=10.0, # seconds per request
retries=2, # extra attempts after the first
max_retry_wait=65.0, # longest Retry-After to wait for
user_agent="my-bot/1.0",
)For tests, pass opener= with a function that behaves like urllib.request.urlopen; the client's own test suite does this.
Rate limit
- The API allows about 100 requests per minute per IP address, on a best-effort basis.
iterate()reads 100 records per request. Walking all 90 datasets takes roughly 90 requests, so cache results in a long-running bot instead of scanning on every command.- The client waits and retries when the limit is hit, which can make a large scan pause for up to a minute.
For endpoint behaviour, query parameters and response envelopes, see the API reference. For JavaScript and TypeScript, see the SDK guide.
Ask the right project
Report client behaviour to the Python client repository. Report missing or wrong game data through the feedback desk.