TheWoWDB public API

Free JSON for WoW Forever and retail: items, spells, quests, NPCs, zones and sounds, with paging, search and rendered tooltips. No key needed.

Base URL and shape

https://thewowdb.com/api/v1/ answers with the list of versions, kinds and endpoints. Versions are forever (WoW Forever, listed first) and retail.

/api/v1/<version>/<kind>/?page=1&per_page=50&q= a page of results
/api/v1/<version>/<kind>/<id> one record
/api/v1/<version>/search/?q= a few hits of every kind
/api/v1/tooltip/<version>/<kind>/<id> the rendered tooltip HTML plus its plain fields

Every record carries links.html, the TheWoWDB page it came from, and an attribution object.

Kinds and ids

Kind	forever id	retail id
`item`	item id (beta client data)	item id
`spell`	spell id (beta client data)	spell id
`quest`	quest id (text the beta server sent)	quest id
`npc`	creature id, as in /wow-forever/npc/	journal boss id, as in /npc/
`zone`	top-level area id	area id, as in /zone/
`sound`	sound slug, as in /sounds/	sound slug, as in /sounds/

The id is always the id in our page URL for that version, so the link you build from it resolves.

Examples

List Forever quests, page 2

curl -s 'https://thewowdb.com/api/v1/forever/quest/?page=2&per_page=50'

Search Forever items

curl -s 'https://thewowdb.com/api/v1/forever/item/?q=lionheart'

One Forever spell

curl -s 'https://thewowdb.com/api/v1/forever/spell/133'

One retail item with its live AH price

curl -s 'https://thewowdb.com/api/v1/retail/item/2589'

Search every kind at once

curl -s 'https://thewowdb.com/api/v1/forever/search/?q=defias'

A rendered tooltip (HTML + fields)

curl -s 'https://thewowdb.com/api/v1/tooltip/forever/item/12640'

Revalidate with the ETag (answers 304)

curl -s -o /dev/null -w '%{http_code}' -H 'If-None-Match: W/"<etag>"' 'https://thewowdb.com/api/v1/forever/spell/133'

Sample response

{
  "id": 133, "kind": "spell", "version": "forever", "name": "Fireball", "rank": "Rank 1",
  "cast_time": {"ms": 1500, "seconds": 1.5, "instant": false},
  "costs": [{"name": "Mana", "cost": 30, "per_second": null}],
  "description": "Hurls a fiery ball that causes ...",
  "links": {"html": "https://thewowdb.com/wow-forever/spell/fireball-133/",
            "api": "https://thewowdb.com/api/v1/forever/spell/133",
            "tooltip": "https://thewowdb.com/api/v1/tooltip/forever/spell/133"},
  "attribution": {"text": "Data from TheWoWDB (thewowdb.com)", "required": true,
                  "url": "https://thewowdb.com/wow-forever/spell/fireball-133/", "terms": "..."},
  "build": "wow_classic_beta-1.60.1.70058"
}

Paging and search

per_page is 1 to 100 (default 50); page is 1 to 200. Large lists report has_more and a links.next URL instead of a total; small lists also give total. q is a case-insensitive name match of up to 64 characters.

Caching, CORS and rate limits

Responses are public and cacheable for an hour (item tooltips five minutes, because they carry a live Auction House price) and carry an ETag; send If-None-Match and an unchanged answer is a 304 with no body. CORS is open (Access-Control-Allow-Origin: *) and never accepts credentials, so call it straight from a browser.

Each IP gets a burst of 120 requests that refills at 2 per second on each server worker. Past that the API answers 429 with Retry-After; X-RateLimit-Remaining shows what is left. Cache what you fetch.

Terms

Free for any project, commercial or not, with a visible link to TheWoWDB (or the record's links.html) wherever the data is shown. Do not resell the raw data as a dataset. Game data and names belong to Blizzard Entertainment; TheWoWDB is a fan site and is not affiliated with Blizzard. The API may change; breaking changes ship under a new /api/v2/.

Also available

Embeddable tooltips: one script tag for your site. Discord bot: the same data as slash commands.