Skip to main content

​
Overview

The Trivia API integration provides a client for interacting with the Open Trivia Database (OpenTDB) API. It handles fetching trivia questions with various parameters and retrieving available categories. Base URL: https://opentdb.com Package: internal/trivia_api/trivia_api.go

​
TriviaClient

​
Creating a Client

func NewTriviaClient() *triviaClient
Creates a new trivia client configured with the OpenTDB base URL. Example: 
client := triviaapi.NewTriviaClient()

​
API Methods

​
GetQuestions

Fetches trivia questions from the Open Trivia Database API. 
func (t *triviaClient) GetQuestions(amount int, category int) ([]entities.Question, error)
​
amount
int
required
Number of questions to fetch
​
category
int
required
Category ID for the questions (use GetCategories to retrieve valid IDs)
Returns: Array of Question entities with shuffled answer options Implementation Details:
  • Constructs API URL: {baseURL}/api.php?amount={amount}&type=multiple&category={category}
  • Only fetches multiple-choice questions
  • Automatically shuffles answer options to randomize correct answer position
  • Converts API response format to internal Question entities
Example: 
// Fetch 10 questions from category 9 (General Knowledge)
questions, err := client.GetQuestions(10, 9)
if err != nil {
    log.Fatal(err)
}

​
GetCategories

Retrieves all available trivia categories from the API. 
func (t *triviaClient) GetCategories() ([]question.Category, error)
Returns: Array of Category objects containing ID and Name Implementation Details:
  • Endpoint: {baseURL}/api_category.php
  • Returns structured list of all available categories
  • Categories can be used as parameters for GetQuestions
Example: 
categories, err := client.GetCategories()
if err != nil {
    log.Fatal(err)
}

for _, cat := range categories {
    fmt.Printf("ID: %d, Name: %s\n", cat.Id, cat.Name)
}

​
API Response Structures

​
Trivia Question Response

The API returns questions in the following format:
​
type
string
Question type (e.g., “multiple”)
​
difficulty
string
Difficulty level (easy, medium, hard)
​
category
string
Category name
​
question
string
The question text
​
correct_answer
string
The correct answer
​
incorrect_answers
[]string
Array of incorrect answer options

​
Category Response

​
trivia_categories
[]Category
Array of category objects with Id and Name fields

​
Error Handling

​
APIError

Custom error type for Open Trivia Database API errors. Source: internal/trivia_api/error.go 
type APIError struct {
    Code int
}
Error Response Codes:
  • 0: Success
  • Non-zero: API error (check OpenTDB documentation for specific codes)
Example Error Message: 
opentdb:API error with code:1 ,check docs for more info

​
Error Handling Pattern

questions, err := client.GetQuestions(10, 9)
if err != nil {
    if apiErr, ok := err.(*triviaapi.APIError); ok {
        // Handle API-specific error
        fmt.Printf("API error code: %d\n", apiErr.Code)
    } else {
        // Handle network or other errors
        log.Fatal(err)
    }
}

​
Data Conversion

​
ConvertToQuestion

Converts API response format to internal Question entity. 
func ConvertToQuestion(triviaQuestionData triviaQuestion) entities.Question
Process:
  1. Extracts question text, correct answer, and incorrect answers
  2. Combines all answers into a single options array
  3. Shuffles options to randomize answer positions
  4. Creates and returns a Question entity

​
Implementation Notes

  • HTTP client uses standard net/http package
  • Response validation checks for HTTP 200 status code
  • JSON decoding uses encoding/json package
  • Answer shuffling uses math/rand with time-based seed for randomization
  • All requests are synchronous and blocking

Build docs developers (and LLMs) love

Get started for freeTalk to us