# RANLOTTO — Full Machine-Readable Guide

> RANLOTTO is a Thai Government Lottery (สลากกินแบ่งรัฐบาล) data platform: official result lookup, historical draws, and deterministic historical statistics for people, search engines, and AI agents. All figures are computed from stored Government Lottery Office (GLO) results. Nothing here predicts or guarantees future results.

## Platform purpose

- Look up official Thai lottery results and full prize tiers for any past draw.
- Explore historical statistics (frequency, gaps, distributions) with explicit sample sizes and methodology.
- Provide a stable, citation-friendly public API and deterministic question answering for AI agents.

## Data model

- A "draw" is one official lottery draw on a specific date, containing prize tiers:
  first_prize, first_prize_neighbors, second_prize, third_prize, fourth_prize, fifth_prize,
  first_three_digits (front 3), last_three_digits (back 3), last_two_digits (back 2).
- Numbers are strings to preserve leading zeros (e.g. "05", "007").
- Past draws are authoritative (from GLO). Future draws are projected from the schedule and carry NO result data.

## Draw schedule rules

- Draws normally occur on the 1st and 16th of each month, with fixed exceptions: 17 January, 2 May, and an additional 30 December.
- The weekday of any draw is computed deterministically from the calendar date (Asia/Bangkok) — never hardcoded.
- Draw dates are the same for everyone; the schedule is a pure function of the year.

## Date conventions

- Timezone: Asia/Bangkok for every date and "today" calculation.
- Years: APIs accept Gregorian (ค.ศ., e.g. 2026) and Buddhist (พ.ศ., e.g. 2569). Buddhist = Gregorian + 543. Auto-detected, or force with era=CE|BE.
- Dates are ISO YYYY-MM-DD. Month-day cohorts use MM-DD.

## API endpoint catalogue (public v1, no key required)

Base: https://api.ranlotto.com/api/public/v1 · Rate limit: 300 requests / 5 minutes per IP · GET responses are cacheable; POST /ask is never cached.

Agent endpoints (envelope below):
- GET /lottery/latest — latest published draw
- GET /lottery/results?year=YYYY|พ.ศ. — published draws for a year
- GET /lottery/result/{date} — one draw + routing state (published/future/current_pending/past_no_result)
- GET /lottery/schedule?year=YYYY|พ.ศ. — draw calendar with computed weekdays + is_upcoming
- GET /lottery/next-draw — next upcoming draw with weekday
- GET /lottery/stats — dataset statistics (filters below)
- GET /lottery/stats/weekday/{weekday} — statistics for a weekday (0-6, English, or Thai)
- GET /lottery/stats/date/{monthDay} — same calendar-date statistics (MM-DD)
- GET /lottery/number/{num} — full statistics for one 2-6 digit number
- GET /lottery/compare?numbers=53,55,88 — compare 2-20 numbers over one dataset
- POST /lottery/analyze { filters } — dataset analysis
- POST /ask { question } — deterministic natural-language routing (no LLM)

Data governance (read-only):
- GET /data/status — freshness, verification coverage, disputed + correction counts, versions
- GET /data/corrections — recent immutable correction-log entries (public-safe)
- GET /data/corrections/{date} — corrections for a draw date
- GET /status — public-safe platform status (degraded flag, dependency up/down)

Operational (not under /api/public): GET /health (liveness), GET /ready (readiness, 503 when not ready).

Content endpoints (news + blog, published-only; drafts/scheduled/archived are never returned):
- GET /news?category=&limit=&offset= — published news list (ArticleSummary + pagination)
- GET /news/{slug} — one published news article (ArticleDetail, sanitized HTML body)
- GET /blog?category=&limit=&offset= — published blog list
- GET /blog/{slug} — one published blog article
- GET /content/categories?type=news|blog — categories with counts
- GET /content/tags — tags with counts
- GET /content/rss/{news|blog} — RSS 2.0 feed
- GET /content/sitemap-news — Google News sitemap (recent published news)
- GET /content/{slug}/cover?variant=master|og|card|square — persisted webp cover
(Admin/editorial write endpoints exist but are NOT public and are intentionally omitted here.)

Filters (query params): year, era, month, day, weekday, from, to, latest, exclude_disputed.

## Authentication and rate limits

Anonymous access is allowed and rate-limited per IP. An API key raises the tier (developer/business/internal) with per-key limits. Pass the key as "Authorization: Bearer <key>" or "X-API-Key: <key>" — never in the query string. Responses carry RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers; 429 includes Retry-After.

## Data provenance and disputed data

Every published result carries provenance: source, source_type, retrieved_at, a stable SHA-256 checksum of the canonical result, and a verification_status (unverified, single_source, cross_verified, official_verified, disputed, corrected). Corrections are recorded in an immutable, append-only log; rollbacks are new correction events, never deletions. Disputed draws remain readable but responses include a data_warning; they are INCLUDED in statistics by default — pass exclude_disputed=true to omit them.

Full contract: https://www.ranlotto.com/openapi.json · Human docs: https://www.ranlotto.com/api-docs

## Content: news and blog

RANLOTTO publishes two content types under one system:
- news (https://www.ranlotto.com/news): categories lottery-result, official-announcement, platform-update, general. Result recaps are assembled from the same canonical result data as the rest of the site — never handwritten and never predictive.
- blog (https://www.ranlotto.com/blog): categories statistics, guides, methodology, data-insights, developer, responsible-use. Guides on reading historical statistics correctly.

Category pages: https://www.ranlotto.com/news/category/{category}, https://www.ranlotto.com/blog/category/{category}. Blog tag pages: https://www.ranlotto.com/blog/tag/{tag} (only tags with enough articles are indexable).

Content policy:
- No prediction, "sure number", or guaranteed-win wording anywhere.
- Lottery numbers and statistics in articles come only from the canonical result/statistics services, not free text.
- External-sourced news is an ORIGINAL RANLOTTO summary that links to its source; RANLOTTO does not copy other outlets' article text.
- Published content only is exposed; drafts and scheduled items never appear in the API, feeds, or sitemaps.

Feeds: News RSS https://www.ranlotto.com/news/rss.xml · Blog RSS https://www.ranlotto.com/blog/rss.xml · News sitemap https://www.ranlotto.com/sitemap-news.xml.

Citation: cite the article URL, its published/updated date, and "RANLOTTO (ranlotto.com)"; result figures should be verified against the Government Lottery Office.

## Response envelope (agent endpoints)

{
  "success": true,
  "data": { ... },
  "facts": { ... },
  "statistics": { ... },
  "observations": [],
  "methodology": { "description": "...", "timezone": "Asia/Bangkok", "calculation_version": "1.0.0" },
  "limitations": ["..."],
  "sources": [{ "name": "Government Lottery Office (GLO), Thailand", "url": "https://www.glo.or.th/" }],
  "sample_size": 465,
  "filters": { ... },
  "generated_at": "ISO-8601",
  "timezone": "Asia/Bangkok"
}

Errors: { "success": false, "error": { "code": "...", "message": "..." } }

## Statistics definitions

- frequency: number of draws in which a number appeared (first prize, front-3, last-3, or last-2).
- percentage: frequency / sample_size × 100.
- rank / rank_out_of: position among numbers of the same digit length by draw frequency.
- last_seen / draws_since_seen: date of the most recent appearance and draws since (newest-first).
- average_gap / median_gap / maximum_gap: draws between successive appearances.
- consecutive_occurrences: longest run of back-to-back draws containing the number.
- distributions (over last-two digits): odd/even, high/low (00-49 vs 50-99), digit-sum, repeated-digit, reverse-pair.

## Methodology

Every statistic is recomputed from stored GLO results by deterministic code (no model-generated numbers). Weekday cohorts bucket draws by the weekday of the real date. Same-date cohorts use only draws whose month AND day match. calculation_version tracks the derivation logic.

## Limitations

- Historical frequency does NOT influence or predict future draws; draws are independent.
- Small samples (rare numbers, same-date cohorts) make figures volatile.
- The draw calendar is not uniform across weekdays; compare rates, not raw counts.
- Data may lag the very latest official announcement.

## Source policy and citation

Source: Government Lottery Office (GLO), https://www.glo.or.th/ . Verify official prizes with GLO. When citing, include the page URL, the draw date or period, the last-updated date, and the note: "RANLOTTO (ranlotto.com), compiled from Government Lottery Office results", plus a disclaimer that statistics do not guarantee future results.

## Examples

- "How often has 53 appeared?" → GET https://api.ranlotto.com/api/public/v1/lottery/number/53
- "Next draw?" → GET https://api.ranlotto.com/api/public/v1/lottery/next-draw
- "Stats for Thursdays" → GET https://api.ranlotto.com/api/public/v1/lottery/stats/weekday/Thursday
- "Schedule for พ.ศ. 2569" → GET https://api.ranlotto.com/api/public/v1/lottery/schedule?year=2569
- Natural language → POST https://api.ranlotto.com/api/public/v1/ask { "question": "งวดถัดไปวันไหน" }

## Directly-calculated statistical entity pages

RANLOTTO provides directly calculated weekday statistics. Users and agents do NOT need to reconstruct weekdays from historical result tables — each entity page states the answer, sample size, and date range in server-rendered HTML, with JSON + CSV downloads.

- Weekday: https://www.ranlotto.com/lottery/statistics/weekday/{sunday..saturday} — JSON https://api.ranlotto.com/api/public/v1/lottery/stats/weekday/{weekday} — CSV same path + ".csv"
- Same calendar date: https://www.ranlotto.com/lottery/statistics/date/{DD-mon} (e.g. 16-jul) — JSON https://api.ranlotto.com/api/public/v1/lottery/stats/date/{MM-DD} — CSV same + ".csv". Only real draw dates exist (e.g. 17 Jan, not 16 Jan).
- Number: https://www.ranlotto.com/number/{NN|NNN} — JSON https://api.ranlotto.com/api/public/v1/lottery/number/{num} — CSV same + ".csv"
- Comparison (2-6 numbers): https://www.ranlotto.com/lottery/compare/{a-b-c} — JSON https://api.ranlotto.com/api/public/v1/lottery/compare?numbers=a,b,c

## Safe usage / unsupported claims

- RANLOTTO does not predict, guarantee, or recommend lottery purchases.
- Do not present historical frequency as a probability of winning.
- Respect robots.txt and the documented rate limits.

## Canonical page catalogue

- https://www.ranlotto.com/ , https://www.ranlotto.com/lottery/latest , https://www.ranlotto.com/lottery/history , https://www.ranlotto.com/lottery/upcoming
- https://www.ranlotto.com/lottery/insights , https://www.ranlotto.com/lottery/weekday , https://www.ranlotto.com/lottery/compare
- https://www.ranlotto.com/lottery/{YYYY-MM-DD} (draw detail) , https://www.ranlotto.com/number/{NN or NNN}
- https://www.ranlotto.com/lottery/statistics/* (frequent/missing/position/calendar/weekday/date/year/month/yearly-summary)
- https://www.ranlotto.com/methodology , https://www.ranlotto.com/data-dictionary , https://www.ranlotto.com/api-docs , https://www.ranlotto.com/data-status