Migrate from Open Trivia DB

If your app gets its questions from Open Trivia DB, moving to The Trivia API mostly means changing a URL and some field names. You can also delete the code that decodes HTML entities, since questions come back as plain text.

This guide maps each part of Open Trivia DB's API to its equivalent here.

Requests

Open Trivia DB's api.php becomes /v2/questions:

# Open Trivia DB
curl "https://opentdb.com/api.php?amount=10&category=23&difficulty=medium&type=multiple"
 
# The Trivia API
curl "https://the-trivia-api.com/v2/questions?limit=10&categories=history&difficulties=medium"

Then the parameters:

• amount becomes limit. It's up to 50 without an API key, and defaults to 10, so you can leave it out.
• category becomes categories. It takes names instead of numeric ids, and you can pass several, separated by commas. See categories.
• difficulty becomes difficulties. The values are the same (easy, medium, hard), and you can pass several.
• type=multiple can go. Multiple choice is the default.
• type=boolean has no equivalent, as there are no true/false questions.
• encode can go. Text is plain UTF-8, so there's nothing to decode.
• token becomes session, which needs an API key. See session tokens.

Responses

Open Trivia DB wraps the questions in an object with a response_code:

{
  "response_code": 0,
  "results": [
    {
      "type": "multiple",
      "difficulty": "medium",
      "category": "History",
      "question": "How old was the famous King Tutankhamen (Tut) when he died?",
      "correct_answer": "19",
      "incorrect_answers": ["21", "15", "30"]
    }
  ]
}

The Trivia API returns the array itself, and uses HTTP status codes for errors:

[
  {
    "id": "622a1c3c7cc59eab6f9517b2",
    "type": "text_choice",
    "difficulty": "medium",
    "category": "history",
    "question": { "text": "Which former British prime minister returned to power in 1951?" },
    "correctAnswer": "Winston Churchill",
    "incorrectAnswers": ["Clement Atlee", "Tony Blair", "Neville Chamberlain"],
    "tags": ["uk", "politics", "history", "leaders"],
    "regions": [],
    "isNiche": false
  }
]

Each question also has an id, which you can use to report a problem with it, and tags.

Updating your code

Most apps convert the response into their own question shape in one place. That's the only function that needs to change:

// Before: Open Trivia DB
const decodeHtml = (text) => new DOMParser().parseFromString(text, "text/html").body.textContent;
 
async function getQuestions() {
  const response = await fetch(
    "https://opentdb.com/api.php?amount=10&category=23&difficulty=medium&type=multiple"
  );
  const { response_code, results } = await response.json();
  if (response_code !== 0) {
    throw new Error(`Open Trivia DB responded with code ${response_code}`);
  }
 
  return results.map((question) => ({
    text: decodeHtml(question.question),
    correctAnswer: decodeHtml(question.correct_answer),
    incorrectAnswers: question.incorrect_answers.map(decodeHtml),
  }));
}

// After: The Trivia API
async function getQuestions() {
  const response = await fetch(
    "https://the-trivia-api.com/v2/questions?limit=10&categories=history&difficulties=medium"
  );
  if (!response.ok) {
    throw new Error(`The Trivia API responded with ${response.status}`);
  }
 
  const questions = await response.json();
  return questions.map((question) => ({
    text: question.question.text,
    correctAnswer: question.correctAnswer,
    incorrectAnswers: question.incorrectAnswers,
  }));
}

You still need to shuffle the correct answer in with the incorrect ones before showing them, as before. If you use TypeScript, the SDK has types for all of this, so you can drop your own response types too.

Categories

Open Trivia DB has 24 numeric categories, and The Trivia API has 10 broader ones plus over 1,500 tags. Most Open Trivia DB categories map to one or the other:

Some of those tags only have a few dozen questions. Before you build a whole quiz on one, check how many questions it has. The filtering guide covers categories and tags in more detail.

Category names have to match exactly. /v2/questions/count returns the filters it applied in appliedFilters, which is a quick way to check your mapping.

Response codes

Open Trivia DB returns 200 with a response_code. Here's where each one ends up:

Session tokens

Open Trivia DB's session tokens and The Trivia API's sessions do the same job: they stop a question coming up twice.

Sessions need an API key on a Regular or Complete plan, which also means making those requests from your server rather than the browser. The sessions guide has the details.

Without a key, you can get close by keeping the ids of questions you've already shown and skipping them when they come round again.

Limits and licensing

Without a key, Open Trivia DB allows one request every 5 seconds per IP address. The Trivia API allows 20 requests every 5 seconds, with up to 50 questions in each.

Both are free for non-commercial use. Open Trivia DB's questions are licensed under CC BY-SA 4.0, and The Trivia API's under CC BY-NC 4.0, so commercial apps need a subscription.