Filter questions by category, difficulty and tag

By default, /v2/questions gives you 10 questions from anywhere in the question bank. Query parameters narrow that down, so you can build a quiz on one subject at the right level for your players.

Pick categories

Every question is in one of 10 categories: arts_and_literature, film_and_tv, food_and_drink, general_knowledge, geography, history, music, science, society_and_culture and sport_and_leisure.

Pass one or more, separated by commas. You get questions from any of them:

curl "https://the-trivia-api.com/v2/questions?categories=history,geography"

Pick difficulties

difficulties takes easy, medium and hard, again separated by commas:

curl "https://the-trivia-api.com/v2/questions?difficulties=easy,medium"

Difficulty is set by the people who review each question, so treat it as a guide to how many players will know the answer rather than an exact score.

Narrow it down with tags

Categories are broad. Tags are specific topics, like dinosaurs or the_beatles, and a question usually has several. They're the way to build a themed quiz:

curl "https://the-trivia-api.com/v2/questions?tags=dinosaurs,space"

Some things to know about tags:

• They're case-sensitive and use underscores, so it's the_beatles. The Beatles matches nothing.
• /v2/tags lists every tag, and /v2/totals-per-tag says how many questions each one has.
• Niche tags only have a handful of questions. Check the count (see below) before you promise anyone a 50-question dinosaur quiz.

Combine filters

Different parameters narrow each other down, while the values within one parameter widen it. This gets hard questions that are about history or geography:

curl "https://the-trivia-api.com/v2/questions?categories=history,geography&difficulties=hard&limit=20"

Check how many questions match

Before you build a quiz on a filter, check there are enough questions behind it. /v2/questions/count takes the same filters and returns a count, with the filters it applied:

curl "https://the-trivia-api.com/v2/questions/count?tags=dinosaurs"

{
  "count": 17,
  "appliedFilters": {
    "categories": ["arts_and_literature", "film_and_tv", "..."],
    "difficulties": ["easy", "medium", "hard"],
    "types": ["text_choice"],
    "tags": ["dinosaurs"]
  }
}

If you ask /v2/questions for more questions than match, you just get fewer back. Your app should handle a short list (or an empty one) rather than assume it got limit questions.

Ask questions that suit your players

A few more filters help when you know who's playing:

Without region, every question should be fair to ask anyone, anywhere. With region=GB you also get questions like "With which sport would you most associate the commentator Ted Lowe?", which are fine in the UK and baffling elsewhere.

From code

With the SDK, the filters are the same names, with multiple values as comma-separated strings:

import { getQuestionCount, getRandomQuestions } from "@trivia-api/sdk";
 
const filters = { tags: "dinosaurs", difficulties: "easy,medium" };
 
const { count } = await getQuestionCount(filters);
const questions = await getRandomQuestions({ ...filters, limit: Math.min(count, 10) });

With fetch, URLSearchParams builds the query string for you:

const params = new URLSearchParams({ tags: "dinosaurs", difficulties: "easy,medium" });
const response = await fetch(`https://the-trivia-api.com/v2/questions?${params}`);
const questions = await response.json();

Every parameter is in the API reference.