Trivia questions now have a fixed set of tags
Will Fry6 min read
Tags on questions in The Trivia API changed today. Every approved question is now tagged from one fixed list of 1,047 tags, and the old free-form tags are gone.
If you only ever filtered by category, nothing changes for you. If you stored tags like the_beatles or world_war_2, you'll need to swap them for the new ones, because filtering by an old tag now gets you nothing. There's more on that below.
What a question looks like now
Here's a question with its new tags:
{
"id": "622a1c3c7cc59eab6f9517b2",
"question": { "text": "Which former British prime minister returned to power in 1951?" },
"correctAnswer": "Winston Churchill",
"tags": [
"category:history",
"category:society-and-culture",
"place:united-kingdom",
"place:europe",
"place:british-isles",
"era:1950s",
"era:20th-century",
"person:uk-prime-ministers",
"person:winston-churchill",
"topic:politics",
"topic:uk-politics"
]
}That one has more than most. The average is about five or six, and every question has at least one category: tag.
Why the old tags had to go
The old tags were free text, with nothing to say which tags already existed. That was fine with a few of them, and stopped working once there were a lot.
By the end there were 2,173 different tags across the approved questions, and 1,331 of them were on a single question.
The same thing ended up under several names (film was on 1,238 questions and movies on 21), so a filter on one name missed the questions filed under another. Some names meant two different things: football was on questions about the World Cup and on questions about the NFL. And those single-question tags were no use to anyone, since you can't build a quiz from one question. You also couldn't tell how big a tag was without trying it.
Fixing them one at a time wasn't going to work, so we started again.
What the new tags are
There's one list, and every tag on every question comes from it. It's closed, so a tag can't appear on a question unless it's on the list.
Each tag is a prefix, a colon and a name, like place:france or music:the-beatles. There are 13 prefixes: category, topic, music, place, person, work, event, sport, science, food, era, org and animal. The prefix says what kind of thing the tag is, which is what stops names colliding. place:jordan is the country and person:michael-jordan is the basketball player. sport:football-soccer and sport:american-football are different tags, so the NFL and the World Cup don't get mixed up any more.
The tags are flat, with no parents or children. Instead, a question gets the broad tags and the narrow ones together. A question about the Eiffel Tower has place:paris, place:france, place:europe and place:western-europe. A question about a 1969 hit has era:1960s and era:20th-century. So if you want everything about Europe, you filter on place:europe, and that's one request.
We think that's the right call for an API. A hierarchy is nice to look at, but it means every client has to know the tree and expand it before asking for anything. With flat tags, the question already says everything it's about.
The 10 categories are tags too: category:geography, category:film-and-tv and so on. The categories parameter still works exactly as before, but you don't need it if you're filtering by tag. A tag picker can do a category picker's job as well.
Counts, labels and descriptions
The list is public, at /v2/tag-registry. No key needed:
curl "https://the-trivia-api.com/v2/tag-registry"Each tag comes with a label and description for showing to players, and a count of how many questions you can get with it:
{
"slug": "music:the-beatles",
"label": { "en": "The Beatles" },
"description": {
"en": "The Liverpool band, their songs and albums, and the solo careers of John, Paul, George and Ringo."
},
"count": 45
}The labels and descriptions are in English unless you ask for another language with language. We support the same languages as the questions: es, nl, hi, tr, fr, de, ru and pt, as well as en. Like the rest of the registry, it doesn't need a key:
curl "https://the-trivia-api.com/v2/tag-registry?language=de"{
"slug": "music:the-beatles",
"label": { "de": "The Beatles" },
"description": {
"de": "Die Liverpooler Band, ihre Songs und Alben sowie die Solokarrieren von John, Paul, George und Ringo."
},
"count": 45
}You only get the language you asked for. If a tag doesn't have it, its English text comes back under en, so read label[language] ?? label.en.
The counts are there because not every tag is big. The biggest are the categories, with category:society-and-culture on 1,957 questions, then broad tags like topic:film (1,061) and era:20th-century (1,055). At the other end, 499 tags have fewer than 10 multiple choice questions and 59 have none yet.
We kept the small ones. A tag with five questions is too small for a quiz on its own, but it's still useful to know a question is about it, and it'll grow as questions are added. Rather than pick a cut-off for you, the registry tells you the count and you choose. A 10-question quiz needs tags with at least 10; a quick round of five can go lower.
What you can do with it
Filter by topic, place, person, era, sport or anything else on the list, with one parameter:
curl "https://the-trivia-api.com/v2/questions?tags=place:france&limit=10"Or build a picker: fetch the registry once, show the labels, hide anything below your quiz size, group by prefix and let players search. It's about a thousand tags, so searching them in the browser is quick. The tag quiz tutorial goes through it, and there's a finished React app to play or fork.
Load the list from the registry each time rather than copying it into your own code or database. Tags, labels and descriptions can change, and the registry is always the current list.
What can break
This is a breaking change if you stored the old tags. They're gone from every question, so a request like tags=the_beatles now returns an empty array (and a count of 0), rather than an error. Check anywhere you've saved tags, including links people might have bookmarked.
To move across, look up the new slug in the registry. Most map over directly: the_beatles is now music:the-beatles, world_war_2 is event:world-war-ii and capital_cities is place:capital-cities. Searching the labels and descriptions for the old name is usually the quickest way to find it.
/v2/tags and /v2/totals-per-tag still work, and now return the new slugs. For a question count to show players, use the registry's count or /v2/questions/count, since they count the questions /v2/questions would actually give you.
One more thing that catches people out: several tags in one request means questions with any of them, not all of them. tags=place:france gets 94 questions, and tags=place:france,music:rock gets 390. The filtering guide has the details and a workaround.
What isn't there yet
- There's no way to ask for questions that have all of several tags. For now, fetch with one tag and filter the
tagsarray yourself. - Counts are per tag, not split by difficulty.
/v2/questions/countwith a tag and a difficulty gets you that, one request at a time.
Every parameter for the registry and the question endpoints is in the API reference.
Build with The Trivia API
The docs cover every endpoint, parameter and response. No API key is needed to get started.