Name: Fun & Entertainment API - Trivia, Jokes & History
Brand: quotalink
SKU: api-quotalink-fun-entertainment-api
Availability: InStock
Author: API Market

李乐

## Overview

Fun & Entertainment API bundles three light content sources behind one base URL: multiple-choice trivia questions, Chuck Norris jokes and "on this day" historical events. It is built for the places an app needs a bit of filler content: a loading screen, a daily widget, a chat command or an onboarding flow.

Responses are small, flat JSON and every endpoint works with no parameters at all, so you can wire one up in a single line and refine later.

## Features

- **Trivia questions**: multiple choice with category, difficulty, the correct answer and distractors, ready to render as a quiz.
- **Chuck Norris jokes**: the classic one-liners, optionally filtered by category.
- **On this day**: historical events, births and deaths for any calendar date.
- **Sensible defaults**: call any endpoint bare and get usable content back.
- **Small payloads**: responses are compact enough to serve on a loading screen.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Chat and Discord bots**: a `/joke` or `/trivia` command backed by one HTTP call.
- **Quiz and game apps**: pull ready-made multiple-choice questions with difficulty levels.
- **Daily content widgets**: an "on this day in history" panel for a homepage or newsletter.
- **Loading screens and empty states**: fill dead time with a joke or a fact.
- **Onboarding and engagement**: lightweight interactive moments in a new-user flow.
- **Voice assistants and kiosks**: short, self-contained content that reads well aloud.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/fun-entertainment-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Trailing slashes

The content endpoints are defined with a trailing slash: `/api/trivia/`, `/api/chuck-norris/` and `/api/on-this-day/`. Keep the slash in your request paths.

### Endpoints

#### GET /api/trivia/

Returns multiple-choice trivia questions.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `amount` | query | integer | No | Number of questions, defaults to 1 |

```bash
curl "https://prod.api.market/api/v1/quotalink/fun-entertainment-api/api/trivia/?amount=5" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 1,
  "questions": [
    {
      "category": "Entertainment: Television",
      "type": "multiple",
      "difficulty": "medium",
      "question": "What is the name of the mad scientist who owns Planet Express in Futurama?",
      "correct_answer": "Hubert J. Farnsworth",
      "incorrect_answers": ["Philip J. Fry", "Rick Sanchez", "Ogden Wernstrom"]
    }
  ]
}
```

Question and answer text is HTML-escaped at the source, so you will see entities such as `&amp;` and `&quot;`. Unescape before rendering.

To build a shuffled answer list, combine `correct_answer` with `incorrect_answers` and randomise the order client-side.

The upstream trivia source applies its own rate limiting. Under rapid successive calls a response can come back `"count": 0` with an empty `questions` array and `"success": true`. Check `count` before reading `questions`, and retry after a short pause.

#### GET /api/chuck-norris/

Returns a single Chuck Norris joke.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category` | query | string | No | Restrict to a category, for example `dev` |

```bash
curl "https://prod.api.market/api/v1/quotalink/fun-entertainment-api/api/chuck-norris/?category=dev" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "joke": {
    "id": "KVi1Y2CkTwKX0sI82Jl8og",
    "value": "Chuck Norris' beard is actually made out of liquid metal. He can instantly stab you with it.",
    "categories": ["dev"],
    "created_at": "2020-01-05 13:42:22.089095",
    "updated_at": "2020-01-05 13:42:22.089095"
  }
}
```

Omit `category` for a random joke from the full set; `categories` comes back empty for uncategorised jokes.

#### GET /api/on-this-day/

Historical events, births and deaths for a calendar date. Defaults to today.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `month` | query | integer | No | Month, 1 to 12. Defaults to the current month |
| `day` | query | integer | No | Day of month. Defaults to today |

```bash
curl "https://prod.api.market/api/v1/quotalink/fun-entertainment-api/api/on-this-day/?month=7&day=4" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "date": "07/04",
  "total_events": 91,
  "total_births": 247,
  "total_deaths": 103,
  "events": [
    { "year": 2023, "text": "…", "pages": 2 }
  ],
  "births": [
    { "year": 2000, "text": "Boryana Kaleyn, Bulgarian rhythmic gymnast and Olympic silver medalist" }
  ],
  "deaths": [
    { "year": 2023, "text": "…" }
  ]
}
```

The `total_*` fields report how many entries exist for the date; the arrays themselves are trimmed to a preview of 10 events and 5 births and deaths.

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | The `x-api-market-key` header is missing or malformed | Check the header |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `404` | Path not recognised | Check the trailing slash on the endpoint path |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream content provider error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **Free**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **Pro**: 10,000 API units per month, hard limit.

Every endpoint costs one unit per request.

## Error Handling

These endpoints degrade quietly rather than erroring: a rate-limited upstream returns `200` with `"success": true` and an empty collection. Do not assume a `200` means you got content.

```json
{ "success": true, "count": 0, "questions": [] }
```

Check `count` on trivia and the array length on the other endpoints before rendering, keep a small local pool of previously fetched items as a fallback, and retry `5xx` responses with exponential backoff.

## Implementation Guide

### Example Code

```python
import html
import random
import requests

BASE = "https://prod.api.market/api/v1/quotalink/fun-entertainment-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def quiz(amount=5):
    r = requests.get(f"{BASE}/api/trivia/", params={"amount": amount},
                     headers=HEADERS, timeout=15)
    r.raise_for_status()
    payload = r.json()
    if not payload.get("count"):
        return []
    questions = []
    for q in payload["questions"]:
        answers = q["incorrect_answers"] + [q["correct_answer"]]
        random.shuffle(answers)
        questions.append({
            "question": html.unescape(q["question"]),
            "answers": [html.unescape(a) for a in answers],
            "correct": html.unescape(q["correct_answer"]),
            "difficulty": q["difficulty"],
        })
    return questions

for q in quiz(3):
    print(q["question"])
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/fun-entertainment-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function onThisDay(date = new Date()) {
  const url = `${BASE}/api/on-this-day/?month=${date.getMonth() + 1}&day=${date.getDate()}`;
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`Lookup failed: ${res.status}`);
  const data = await res.json();
  return data.events.map((e) => `${e.year}: ${e.text}`);
}

console.log((await onThisDay()).slice(0, 3));
```

### Performance Optimization

- Fetch trivia in batches with `amount` rather than one question per call. Five questions cost one unit instead of five.
- Cache "on this day" results for the full day. The content for a given date does not change, so one call per day serves every user.
- Keep a small buffer of jokes and questions client-side so a rate-limited empty response never leaves a blank screen.
- Stay within 10 requests per second and avoid tight polling loops, which is what triggers the empty-response behaviour in the first place.

## FAQ

**Do I need an account with QuotaLink to use this API?**

No. Your API.market key is the only credential required.

**Why did I get a 404?**

The content endpoints keep their trailing slash: `/api/trivia/`, `/api/chuck-norris/` and `/api/on-this-day/`.

**Why does trivia sometimes return zero questions?**

The upstream trivia source rate limits rapid requests and answers with an empty set rather than an error. Check `count` and retry after a short pause.

**Why does trivia text contain `&amp;` and `&quot;`?**

The source HTML-escapes its content. Unescape it before rendering, with `html.unescape` in Python or a DOM text node in JavaScript.

**How do I show answers in a random order?**

Merge `correct_answer` into `incorrect_answers` and shuffle the combined list yourself.

**Can I get more events than the API returns?**

The arrays are a preview; `total_events`, `total_births` and `total_deaths` tell you how many exist for that date.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Free entertainment API with trivia questions, Chuck Norris jokes, and historical events. No API key required.