Check typed answers to trivia questions

Multiple choice is easy to mark: the player picked the right option or they didn't. When players type their answer, it gets harder. Is "beatles" right when the answer is "The Beatles"? What about "Muppet" for "Muppets", or "Shakespere"?

text_input questions are written to be answered without options, and the API checks typed answers for you, the way a fair quiz host would.

Typed answers need an API key on the Complete plan.

Get typed-answer questions

Ask for the text_input type:

curl -H "X-API-Key: $TRIVIA_API_KEY" \
  "https://the-trivia-api.com/v2/questions?types=text_input&limit=5"

They look like multiple choice questions, without the wrong answers and with a couple of extra fields:

[
  {
    "id": "697f30536fd039dfc208333a",
    "type": "text_input",
    "category": "film_and_tv",
    "difficulty": "easy",
    "question": {
      "text": "Which superhero has enemies that include the Joker, the Penguin, and the Riddler?"
    },
    "correctAnswer": "Batman",
    "acceptedAnswers": ["Batman", "batman"],
    "correctAnswerRatio": { "correct": 1, "incorrect": 1 },
    "tags": [],
    "regions": [],
    "isNiche": false
  }
]

acceptedAnswers lists answers that have already been checked and accepted. correctAnswerRatio counts how often players have got the question right, which you could show after they answer ("only 12% of players got this one").

You can mix types too. types=text_choice,text_input gets you both, and each question's type tells you which you've got. All the usual filters work.

Check an answer

Send what the player typed to POST /v2/question/{id}/validate:

curl -X POST -H "X-API-Key: $TRIVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"answer": "batman"}' \
  "https://the-trivia-api.com/v2/question/697f30536fd039dfc208333a/validate"

{
  "isCorrect": true,
  "correctAnswer": "Batman",
  "reason": "",
  "source": "cache"
}

isCorrect is the verdict, and correctAnswer is there so you can show it when the player gets it wrong. When the language model made the decision, reason explains it, which is handy while you're testing. It's empty for a match from the cache like this one. A wrong answer judged by the model looks like this:

{
  "isCorrect": false,
  "correctAnswer": "Batman",
  "reason": "Napoleon Bonaparte is not the superhero; Joker, Penguin, and Riddler are Batman's enemies, so the correct answer is Batman.",
  "source": "llm"
}

With the SDK:

import { validateQuestionAnswer } from "@trivia-api/sdk";
 
const result = await validateQuestionAnswer(
  { id: question.id, requestBody: { answer: playerAnswer } },
  { apiKey: process.env.TRIVIA_API_KEY }
);
 
if (result.isCorrect) {
  score += 1;
} else {
  showAnswer(result.correctAnswer);
}

What counts as correct

The check is generous about how an answer is written, and strict about whether it's the right thing. It accepts:

• different capitalisation and small typos, as long as the typo doesn't turn it into a different answer
• singular and plural forms, and answers with or without "the" (so "Muppet" is right for "Muppets", and "Beatles" for "The Beatles")
• other common names, spellings and abbreviations for the same thing
• shortened names, where a quiz host would accept them

It rejects an answer that's a different thing, even a related one, and an answer that describes the right thing instead of naming it.

Answers that have been checked before are answered from a cache ("source": "cache"), which is quick. A new answer is judged by a language model ("source": "llm"), which takes a little longer, so show the player that you're checking.

Costs and limits

Each check costs 50 credits from your monthly allowance, whether it comes from the cache or not, and each key can make up to 300 checks a minute. Going over either gets you a 429 response.

That makes it worth checking once per answer rather than on every keystroke. Check when the player submits, and don't send empty answers.

Keep the key on your server

The key can't go in browser code, where anyone can read it. Have the browser send the player's answer to your server, check it there, and send back the result. That also stops players from finding the answer in the question data: fetch questions on the server too, and leave correctAnswer and acceptedAnswers out of what you send to the browser until they've answered.

The API reference has the full details, including the language parameter for checking answers to translated questions.