GZW Data
Gray Zone Warfare — Comprehensive fan-made game data repository & API.
Automatically scraped from the GZW Fandom Wiki — covers a growing set of game datasets with automatic discovery of new ones.
Free Gray Zone Warfare API for weapons, missions, loot, armor and game data. No API key required.
The API is intended for community tools, Discord bots, dashboards and other Gray Zone Warfare projects. Data is refreshed by the public scraper workflow and exposes both collection and single-record routes.
Quick Start
# Raw data (no API needed)
curl https://raw.githubusercontent.com/ZoniBoy00/gzw-data/main/data/weapons.json
# Or via the API (auto-deployed)
curl https://gzw-data.dev/api/v1/weapons
curl https://gzw-data.dev/api/v1/weapons/ak-12
curl https://gzw-data.dev/api/v1/keys?type=Keycard
curl https://gzw-data.dev/api/v1/medical
Web Console & Documentation
The API includes a dark, responsive developer console for exploring live datasets and copying request examples:
Local development
The API and web console can be exercised locally with the built-in Node HTTP server:
npm install
npm run dev:server
This serves the docs site at http://127.0.0.1:4173/, the Playground at /playground/, the Feedback desk at /feedback/, and the local API at /api/v1/health.
The site is static HTML generated from site-src/pages.js (page content), site-src/legal/ (Privacy Policy and Terms text) and site-src/icons/ (Lucide icons, ISC). After editing any of them, run npm run build:site to regenerate web/**/index.html, 404.html and the static search index (datasets are added to the search palette at runtime from /api/v1/stats); npm test fails when the generated files are stale. Styles and scripts live in web/assets/ and must stay CSP-safe (no inline scripts or styles).
Every dataset also gets its own reference page at /datasets/{dataset}/ (fields, types, coverage, filters and example requests). All of them share one template, web/dataset/index.html, which web/assets/dataset.js fills from /api/v1/metadata/{dataset}, so a dataset the scraper discovers is documented, listed and searchable without rebuilding the site.
The console includes a live dataset explorer, search, pagination, dataset counts, endpoint catalog, query examples and responsive mobile navigation. No API key is required. The published @zoniboy/gzw-data-client 0.9.0 requires Node.js 22+ and supports modern browsers; 0.7.3 remains the last Node.js 18+-compatible release. New API data remains available at runtime without an npm release.
Unknown routes use a matching custom 404 page with direct links back to the console, Quick start and API root.
Changelog
v4.6.0 — numeric projections, ID aliases, and data monitoring
- Adds optional
numeric_values projections without changing scraped source fields.
- Resolves explicitly reviewed legacy record IDs through a validated registry.
- Adds daily full-scrape freshness monitoring and stale-data issue recovery.
- Moves CI and the API runtime floor to Node.js 22+; CI verifies Node 22 and 24.
v4.5.0 — dataset freshness and source provenance
- Exposes per-dataset
lastScrapedAt timestamps and source-page revisions in metadata.
- Adds and preserves
lastFullScrapeAt across metadata summary and single-dataset routes.
- Retires the singular
plate_carrier dataset; plate_carriers is canonical.
v4.4.0 — API contract documentation
- Documented collection, pagination, single-record, metadata, schema and error response envelopes.
- Added the canonical API response contract and linked it from the web reference.
- Kept the public API line at
v1; this release only clarifies and documents the existing contract.
API v4
Base URLs:
- Legacy-compatible:
https://gzw-data.dev/api
- Versioned:
https://gzw-data.dev/api/v1
Both prefixes currently expose the same API contract. New integrations should prefer /api/v1.
Endpoints
| Endpoint | Description |
|---|
/api/v1 | API root — lists all endpoints |
/api/v1/<dataset> | Any dataset by name (auto-discovered) |
/api/v1/<dataset>/<id> | One dataset record by canonical ID or a reviewed legacy alias |
/api/v1/metadata | Dataset schema registry (field names and counts) |
/api/v1/metadata/<dataset> | Detailed schema metadata for one dataset |
/api/v1/schema/<dataset> | Machine-readable schema for one dataset |
/api/v1/metadata?full=true | Detailed schema metadata for all datasets |
/api/v1/health | Lightweight API liveness check |
/api/v1/ready | Lightweight readiness probe; returns 503 until datasets are loaded |
/api/v1/version | API version, data version and available dataset names |
/api/v1/changes | Dataset count changes since the latest stored snapshot |
/api/v1/stats | Item counts for every stored dataset (combined smart-route views excluded) plus the latest scrape timestamp |
/api/v1/search?q= | Cross-dataset search; supports dataset, fields, fuzzy and limit |
/api/v1/spec | OpenAPI 3.0 spec |
/api/v1/images | All item images (400+) |
/api/v1/export/<dataset> | Bounded JSON export for one dataset (maximum 500 records) |
/api/v1/items/<id>/context | Item plus current vendor and dataset references |
/api/v1/armor | Smart route: vests + helmets + glasses |
/api/v1/weapon_parts | Smart route: all weapon parts combined |
/api/v1/helmet_mods | Smart route: night vision + mounts |
Project documentation
The scraper publishes a _manifest.json file with per-dataset record counts and SHA-256 checksums. CI validates dataset JSON and generated metadata before changes can be merged.
API examples
JavaScript
const response = await fetch('https://gzw-data.dev/api/v1/weapons?per_page=5');
const payload = await response.json();
console.log(payload.data, payload.total);
Python
import requests
payload = requests.get(
'https://gzw-data.dev/api/v1/search',
params={'q': 'ak-12'},
timeout=10,
).json()
print(payload['data'])
Versioning
GZW Data exposes three separate version concepts:
apiVersion: public route contract, currently v1; only changes for breaking API changes.implementationVersion: deployed API implementation release, currently 4.6.0; follows semantic versioning for compatible features and fixes.dataVersion: timestamp of the published scraper dataset; changes when data is refreshed.lastFullScrapeAt: most recent completed full scrape; individual dataset freshness and MediaWiki revisions are available from /api/v1/metadata.
Use /api/v1/version when an integration needs these values. A data refresh does not require an API-version change.
Bounded dataset exports
Export one dataset as a downloadable JSON response:
curl -OJ 'https://gzw-data.dev/api/v1/export/weapons'
curl -OJ 'https://gzw-data.dev/api/v1/export/tasks?search=airfield&limit=25'
Exports are limited to 500 matching records. Use search, string-field filters, sort, and limit to narrow a larger dataset. Requests over the limit return 413 EXPORT_TOO_LARGE. Each export includes Content-Disposition, X-Export-Record-Limit, normal API cache headers, and an export metadata object.
The API and CDN also support conditional requests. Cache a response's ETag and send it in If-None-Match; unchanged responses return 304 Not Modified. The application publishes dataVersion so consumers can identify the underlying dataset snapshot.
Version and changes
curl https://gzw-data.dev/api/v1/version
curl https://gzw-data.dev/api/v1/changes
The version response identifies the current API and data snapshot. The changes response compares dataset record counts against the latest stored snapshot. It reports hasHistory: false until a second snapshot is available; it never invents changes without a previous snapshot.
After a scraper update, record a new snapshot with:
npm run snapshot:record
The repository retains the 30 most recent snapshots in data/_history.json.
Capabilities metadata
/api/v1/metadata and /api/v1/metadata/{dataset} expose a capabilities object for each dataset. It describes the supported operations, filter fields, sortable fields and directions, and count fields returned by collection responses. Clients should use this metadata instead of guessing which query parameters a dataset supports.
The current contract advertises list, get, filter, sort, and paginate. Counts include the total matching record count and page count where pagination is used. A capability describes a supported operation; it does not promise that a particular value exists in the current snapshot.
Dataset field deprecation and breaking changes
Dataset additions are backward-compatible. Existing fields are not removed or silently renamed in the v1 API. When a field is planned for removal or semantic change, it is first documented as deprecated, clients are given a migration path, and the change is announced in release notes. The old field remains available for a compatibility window before removal.
The implementation version follows semantic versioning:
- Patch: correction of incorrect data without changing the field contract, or an internal fix.
- Minor: additive dataset fields, new datasets, or new optional metadata/capabilities.
- Major/API version: removing or renaming a field, changing its type or meaning incompatibly, changing response envelopes, or removing a documented operation.
Breaking public contract changes require a new API line (for example v2), updated OpenAPI and SDK contract tests, migration notes, and a documented compatibility window. A routine scraper refresh changes dataVersion, not apiVersion.
Query Parameters
| Param | Example | Description |
|---|
?field=value | ?type=Keycard | Filter by any string field |
?search= | ?search=ak | Free text search across all fields |
?sort= | ?sort=name:asc | Sort results by field |
?page= | ?page=2 | Page number (default: 1) |
?per_page= | ?per_page=10 | Items per page (default: 50, max: 500) |
?all=true | ?all=true | Disable pagination, return all results |
?limit= | ?limit=5 | Cap results (applied after filters) |
Rate Limiting
The API advertises a best-effort limit of 100 requests/minute/IP. The current sliding-window limiter keeps counters in the memory of each warm serverless function instance. Because Vercel can run multiple instances that do not share memory, this is not a strict global quota and should not be treated as an abuse-prevention guarantee.
- Headers:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- Returns
429 with Retry-After header when the active instance limit is exceeded
- Clients should cache responses, respect
Retry-After, and avoid unnecessary polling
- A shared datastore such as Upstash Redis or Vercel KV would be required for a strict global quota
Identifying your app (X-Client)
The API keeps anonymous daily request counters per endpoint, status code and client name. No IP addresses, full URLs or query strings are stored, and counts are kept for 90 days. Please send an X-Client header with a short name for your app or bot (for example X-Client: my-gzw-tool) so your traffic is not lumped in with generic node or curl requests. It is optional. Without it, the first word of your User-Agent is used.
Caching
All data endpoints include Cache-Control: public, max-age=300 headers. CDN and browser caching are encouraged.
Paginated Response
{
"data": [ ... ],
"count": 10,
"page": 2,
"perPage": 10,
"total": 44,
"totalPages": 5,
"source": "GZW Data API",
"timestamp": "2026-07-28T12:00:00.000Z",
"dataVersion": "2026-08-25T11:12:54.629187Z"
}
Unpaginated responses omit page, perPage, total, totalPages.
Error Response
All HTTP errors use the same response envelope and a stable error.code:
{
"error": {
"code": "DATASET_NOT_FOUND",
"message": "Dataset data not found",
"dataset": "foo"
},
"source": "GZW Data API",
"timestamp": "2026-08-26T12:00:00.000Z"
}
Common codes are DATASET_NOT_FOUND, RECORD_NOT_FOUND, ENDPOINT_NOT_FOUND, INVALID_REQUEST, METHOD_NOT_ALLOWED, RATE_LIMITED and INTERNAL_ERROR. Rate-limited responses also include retryAfter inside error and the Retry-After HTTP header.
For the complete list of envelopes, metadata semantics, schema responses and
error codes, see the API response contract.
Single-record Response
GET /api/weapons/ak-12
The response uses the same data envelope as collection routes, with one record instead of an array:
{
"data": {
"id": "ak-12",
"name": "AK-12"
},
"source": "GZW Data API",
"timestamp": "2026-07-28T12:00:00.000Z",
"dataVersion": "2026-08-25T11:12:54.629187Z"
}
Unknown IDs return 404 with the dataset and requested ID in the response.
Data Files
Every non-underscore dataset .json file in data/ is auto-discovered and becomes an API endpoint. New categories appear automatically — no code changes needed. Dataset names and counts are intentionally read from the live API instead of being copied into a static table.
| Category | Example files |
|---|
| Weapons and ammunition | weapons.json, ammo.json |
| Armor and equipment | vests.json, helmets.json, backpacks.json |
| Keys and tasks | keys.json, keycards.json, tasks.json |
| Weapon parts and wearables | barrels.json, stocks.json, magazines.json, glasses.json |
| Loot and supplies | loot_items.json, medical.json |
Original source values remain unchanged. Where a field is an unambiguous number with a recognized unit, records may also include numeric_values.<field> = { value, unit }. Ambiguous comma-decimal strings, ranges, unitless text, and unrecognized units are not normalized. Metadata describes the actual API response shape.
Record id values remain canonical. A renamed record's former ID is kept only when maintainers add a reviewed old-ID-to-current-ID entry in data/_id_aliases.json; aliases are not inferred from name similarity. The API resolves a registered alias to the canonical record.
Data and code have separate licensing scope; see Data sources and licensing.
Automation
The scraper runs every Monday at 06:17 UTC via GitHub Actions. It validates the generated data and API tests, then opens a reviewable pull request against gzw-data (reusing the scrape/data-update branch) rather than pushing scraped output directly to main. The cross-repository handoff requires the GH_PAT Actions secret in the scraper repository.
A separate daily workflow (08:00 UTC) checks the published lastFullScrapeAt timestamp and opens a stale-data issue if no full scrape has completed recently; the issue is closed automatically after recovery. Dependabot proposes npm updates weekly and GitHub Actions updates monthly.
Response Format
All endpoints return consistent JSON:
{
"data": [ ... ],
"count": 44,
"source": "GZW Data API",
"timestamp": "2026-07-28T12:00:00.000Z",
"dataVersion": "2026-08-25T11:12:54.629187Z"
}
Browser, API and CDN regression tests
npm run test:security runs the local Playwright security suite in Chromium and Firefox, plus real OpenAPI contract and CDN/header regression checks. See security testing for local runs, Vercel previews, protected-preview setup and report artifacts.
