regions#

GET /api/v1/regions API key required

List of region codes marking the cultural affinity of each question. A question is tagged with a region if residents of that country, or members of that cultural/religious group, are statistically more likely to know the answer. This is not a tag for “the question is about country X” — the Mona Lisa is universally known (regions: []), but a question requiring NFL knowledge has regions: ["us"].

Pair with /v1/questions{,/random}?regions=... to fetch matching questions.

Requires X-API-Key (or Authorization: Bearer …). Cached for 1h server-side (Cache-Control: public, s-maxage=3600).

Values#

Two kinds of codes appear in this catalog:

country — lowercase ISO 3166-1 alpha-2 (e.g. us, pl, gb, de, jp). ~150 distinct country codes in the dataset; some legacy/composite (eu, un, yu, su) are also present.
cultural — religious/cultural identifiers where ISO geography doesn’t capture the affinity:
- jewish — Talmud, orthodox practice, Jewish holidays
- christian-catholic — Catholic doctrine, popes, canon law
- islam — Islamic practice, hadiths, Quran

Empty array on a question (regions: []) means universally accessible — no cultural advantage assumed.

Filter input is case-insensitive. When you call /v1/questions?regions=PL the server normalizes to lowercase. Output is always lowercase.

Parameters#

Parameter	Type	Default	Description
lang	enum	en	Display language for `label` and per-language `count`. Supported: `en`, `pl`. Other values return `400`.
q	string	—	Substring search across code and label (case-insensitive, 1–64 chars). e.g. `q=pol` matches `pl` (label "Poland") and `q=jew` matches `jewish`.
kind	enum	—	Filter to a single kind: `country` or `cultural`. Omit for both.
cursor	string	—	Code of the last item from the previous page. Use `_links.next` to navigate.
limit	int	100	Page size, 1–500.

Examples#

Response#

{
  "data": [
    { "code": "us", "kind": "country", "label": "United States", "count": 309090 },
    { "code": "gb", "kind": "country", "label": "United Kingdom", "count": 91708 },
    { "code": "pl", "kind": "country", "label": "Poland", "count": 7388 },
    { "code": "jewish", "kind": "cultural", "label": "Jewish (cultural/religious)", "count": 2698 },
    { "code": "christian-catholic", "kind": "cultural", "label": "Catholic Christian (cultural/religious)", "count": 2859 }
  ],
  "meta": {
    "count": 5,
    "total": 152,
    "language": "en",
    "requestId": "req_..."
  },
  "_links": {
    "next": "/api/v1/regions?lang=en&limit=5&cursor=..."
  }
}

Sort: count DESC, code ASC. Pagination via _links.next when available. With ?lang=pl country labels use the native name where available (e.g. pl → "Polska", jp → "日本").

Filtering questions by region#

# AND logic — question must have ALL these codes in its regions array
curl "https://quizbase.runriva.com/api/v1/questions/random?regions=pl,jewish&amount=10" 
  -H "X-API-Key: qb_pk_..."

# Single cultural code — questions requiring Catholic knowledge
curl "https://quizbase.runriva.com/api/v1/questions/random?regions=christian-catholic&amount=10" 
  -H "X-API-Key: qb_pk_..."

# US-relevant questions (NFL, US presidents, Super Bowl, etc.)
curl "https://quizbase.runriva.com/api/v1/questions/random?regions=us&amount=10" 
  -H "X-API-Key: qb_pk_..."

Performance#

p50 (warm): ~110ms
p95: ~120ms
Last measured: 2026-05-27
SLO: p95 < 500ms, error rate < 1%
Backed by a pre-aggregated counts table (~150 codes per language) + 1h response cache.