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.

• Live API: https://gzw-data.dev/api/v1
• API Reference: https://gzw-data.dev/docs/
• JavaScript / TypeScript SDK guide: https://gzw-data.dev/docs/sdk/
• API examples: https://gzw-data.dev/docs/examples/
• OpenAPI spec: https://gzw-data.dev/api/v1/spec
• JavaScript / TypeScript client: @zoniboy/gzw-data-client
• Python client: gzw-data on PyPI (pip install gzw-data), guide, source

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:

• Console: https://gzw-data.dev/
• API Playground: https://gzw-data.dev/playground/
• Feedback desk: https://gzw-data.dev/feedback/
• Quick start & API reference: https://gzw-data.dev/docs/
• JavaScript / TypeScript SDK guide: https://gzw-data.dev/docs/sdk/
• Copyable API & SDK examples: https://gzw-data.dev/docs/examples/
• Python client guide: https://gzw-data.dev/docs/python/
• Python client on PyPI: https://pypi.org/project/gzw-data/
• OpenAPI spec: https://gzw-data.dev/api/v1/spec
• API root: https://gzw-data.dev/api/v1
• JavaScript / TypeScript client: https://www.npmjs.com/package/@zoniboy/gzw-data-client

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

• Roadmap
• Security policy
• Architecture
• API response contract
• Contributing guide
• Data sources and licensing

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.