{"openapi":"3.1.0","info":{"title":"4D Result Asia API","version":"1.0.0","description":"Public REST API for live and historical 4D lottery results across Malaysia and Singapore. Supports Magnum 4D, Sports Toto, Da Ma Cai, Singapore Pools, Sabah 88, Sandakan STC, and CashSweep. Provides latest draw winning numbers, archives, 4-digit number analytics, ticket checking, and provider metadata.","contact":{"name":"4dresult.asia API Support","url":"https://4dresult.asia/en/about"},"license":{"name":"Public Domain / Best-effort aggregator","url":"https://4dresult.asia/en/about"}},"servers":[{"url":"https://4dresult.asia","description":"Production server"}],"paths":{"/api/health":{"get":{"summary":"Health check","description":"Returns API operational status and database connection state.","operationId":"getHealth","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","required":["status","dbStatus"],"properties":{"status":{"type":"string","example":"ok"},"dbStatus":{"type":"string","enum":["connected","disconnected","unknown"],"example":"connected"}}}}}}}}},"/api/providers":{"get":{"summary":"List all lottery operators","description":"Returns all supported 4D lottery providers grouped by country (Malaysia & Singapore).","operationId":"getAllProviders","responses":{"200":{"description":"List of providers grouped by country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvidersResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/providers/{country_code}":{"get":{"summary":"List providers by country","description":"Returns 4D lottery operators available in a specific country (MY for Malaysia, SG for Singapore).","operationId":"getProvidersByCountry","parameters":[{"name":"country_code","in":"path","required":true,"description":"Two-letter uppercase country code (MY or SG)","schema":{"type":"string","enum":["MY","SG"],"example":"MY"}}],"responses":{"200":{"description":"List of providers for the given country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryProviders"}}}},"400":{"description":"Invalid country code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No providers found for country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/latest/{country_code}":{"get":{"summary":"Get latest draw results","description":"Returns winning numbers from the most recent draw date for all operators in the specified country (MY or SG).","operationId":"getLatestResults","parameters":[{"name":"country_code","in":"path","required":true,"description":"Two-letter country code (MY or SG)","schema":{"type":"string","enum":["MY","SG"],"example":"MY"}}],"responses":{"200":{"description":"Latest draw results and prize boards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestResultsResponse"}}}},"400":{"description":"Invalid country code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No results found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/by-date/{country_code}/{date}":{"get":{"summary":"Get draw results by date","description":"Returns winning numbers for all operators in a country on a specific draw date (YYYY-MM-DD).","operationId":"getResultsByDate","parameters":[{"name":"country_code","in":"path","required":true,"description":"Two-letter country code (MY or SG)","schema":{"type":"string","enum":["MY","SG"],"example":"MY"}},{"name":"date","in":"path","required":true,"description":"Draw date in ISO format (YYYY-MM-DD)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-06"}}],"responses":{"200":{"description":"Draw results for the requested date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestResultsResponse"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No results found for date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/search/{number}":{"get":{"summary":"Search number winning history","description":"Returns all historical draw dates, operators, and prize tiers where the 4-digit number won.","operationId":"searchNumberHistory","parameters":[{"name":"number","in":"path","required":true,"description":"4-digit number to check (0000-9999)","schema":{"type":"string","pattern":"^\\d{4}$","example":"1234"}},{"name":"provider_code","in":"query","required":false,"description":"Optional filter by operator code (magnum, toto, damacai, singapore, sabah88, sandakan, cashsweep)","schema":{"type":"string","example":"magnum"}}],"responses":{"200":{"description":"Historical winning records for the number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid 4-digit number or provider code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/number-stats/{number}":{"get":{"summary":"Get 4D number statistics","description":"Returns comprehensive statistical insights for a 4-digit number: total hit count, prize tier breakdown (1st, 2nd, 3rd, Special, Consolation), and last seen details.","operationId":"getNumberStats","parameters":[{"name":"number","in":"path","required":true,"description":"4-digit number to analyze (0000-9999)","schema":{"type":"string","pattern":"^\\d{4}$","example":"1234"}},{"name":"provider_code","in":"query","required":false,"description":"Optional filter by operator code","schema":{"type":"string","example":"toto"}}],"responses":{"200":{"description":"Statistical summary for the 4-digit number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberStats"}}}},"400":{"description":"Invalid 4-digit number or provider code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/hot-numbers":{"get":{"summary":"Get frequently winning numbers","description":"Returns the top most frequently drawn 4-digit numbers over a specified number of days.","operationId":"getHotNumbers","parameters":[{"name":"country_code","in":"query","required":false,"description":"Filter by country (MY or SG)","schema":{"type":"string","enum":["MY","SG"]}},{"name":"provider_code","in":"query","required":false,"description":"Filter by provider code","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Number of past days to examine (7 to 365, default 30)","schema":{"type":"integer","minimum":7,"maximum":365,"default":30}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return (1 to 50, default 10)","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"List of frequently winning numbers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HotNumbersResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/suggestions":{"get":{"summary":"Prefix search suggestions","description":"Returns autocomplete suggestions for 4-digit number searches.","operationId":"getSearchSuggestions","parameters":[{"name":"prefix","in":"query","required":true,"description":"1 to 4 digit prefix string","schema":{"type":"string","pattern":"^\\d{1,4}$","example":"12"}},{"name":"limit","in":"query","required":false,"description":"Number of suggestions (1 to 20, default 10)","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"List of matching suggestions","content":{"application/json":{"schema":{"type":"object","required":["suggestions"],"properties":{"suggestions":{"type":"array","items":{"type":"string","pattern":"^\\d{4}$"},"example":["1200","1234","1288"]}}}}}},"400":{"description":"Invalid prefix parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/archive":{"get":{"summary":"Browse draw date archives","description":"Returns a paginated list of historical draw dates with participating operators and top prizes.","operationId":"getArchiveDates","parameters":[{"name":"country_code","in":"query","required":false,"schema":{"type":"string","enum":["MY","SG"]}},{"name":"provider_code","in":"query","required":false,"schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"4-digit year filter (e.g. 2026)","schema":{"type":"string","pattern":"^\\d{4}$"}},{"name":"month","in":"query","required":false,"description":"Month filter (1-12)","schema":{"type":"string","pattern":"^\\d{1,2}$"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated draw dates list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveDatesResponse"}}}},"400":{"description":"Invalid archive parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/adjacent-date":{"get":{"summary":"Get adjacent draw date","description":"Finds the previous or next published draw date relative to a reference date.","operationId":"getAdjacentDate","parameters":[{"name":"country_code","in":"query","required":true,"schema":{"type":"string","enum":["MY","SG"],"example":"MY"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-06"}},{"name":"direction","in":"query","required":true,"schema":{"type":"string","enum":["prev","next"],"example":"prev"}}],"responses":{"200":{"description":"Adjacent draw date found","content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Adjacent date not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/results/adjacent-dates":{"get":{"summary":"Get previous and next draw dates","description":"Returns both the previous and next published draw dates relative to a reference date in one call.","operationId":"getAdjacentDatesWindow","parameters":[{"name":"country_code","in":"query","required":true,"schema":{"type":"string","enum":["MY","SG"],"example":"MY"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-06"}}],"responses":{"200":{"description":"Adjacent date window","content":{"application/json":{"schema":{"type":"object","properties":{"prev_date":{"type":"string","nullable":true,"format":"date"},"next_date":{"type":"string","nullable":true,"format":"date"}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error","code","message"],"properties":{"error":{"type":"string","description":"Human-readable error category or title","example":"Not Found"},"code":{"type":"string","description":"Machine-readable error code","example":"RESULTS_NOT_FOUND"},"message":{"type":"string","description":"Detailed explanation of the error condition","example":"No draw results available for country code: SG on 2026-05-06"},"hint":{"type":"string","description":"Actionable guidance on how an agent or user can resolve this error","example":"Verify the draw date or check /api/results/archive for available draw dates."},"details":{"description":"Optional validation errors or context"}}},"ProviderItem":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","example":"magnum"},"name":{"type":"string","example":"Magnum 4D"},"logo_url":{"type":"string","nullable":true,"example":"https://4dresult.asia/providers/magnum-4d.webp"},"draw_days":{"type":"array","items":{"type":"string"},"example":["Wed","Sat","Sun"]}}},"CountryProviders":{"type":"object","required":["country_code","providers"],"properties":{"country_code":{"type":"string","example":"MY"},"country_name":{"type":"string","example":"Malaysia"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/ProviderItem"}}}},"ProvidersResponse":{"type":"object","required":["countries"],"properties":{"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryProviders"}}}},"TopPrizeItem":{"type":"object","required":["prize","number"],"properties":{"prize":{"type":"string","example":"1st Prize"},"number":{"type":"string","pattern":"^\\d{4}$","example":"4589"}}},"PrizeStructure":{"type":"object","required":["top","special","consolation"],"properties":{"top":{"type":"array","items":{"$ref":"#/components/schemas/TopPrizeItem"}},"special":{"type":"array","items":{"type":"string","pattern":"^\\d{4}$"},"example":["1234","5678","9012"]},"consolation":{"type":"array","items":{"type":"string","pattern":"^\\d{4}$"},"example":["3456","7890","2345"]}}},"ProviderResult":{"type":"object","required":["provider_code","provider_name","draw_number","prizes"],"properties":{"provider_code":{"type":"string","example":"magnum"},"provider_name":{"type":"string","example":"Magnum 4D"},"draw_number":{"type":"string","example":"123/26"},"updated_at":{"type":"string","format":"date-time"},"prizes":{"$ref":"#/components/schemas/PrizeStructure"}}},"LatestResultsResponse":{"type":"object","required":["draw_date","results"],"properties":{"draw_date":{"type":"string","format":"date","example":"2026-05-06"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ProviderResult"}}}},"SearchHistoryItem":{"type":"object","required":["draw_date","draw_number","provider_code","provider_name","country_code","category"],"properties":{"draw_date":{"type":"string","format":"date","example":"2026-05-06"},"draw_number":{"type":"string","example":"123/26"},"provider_code":{"type":"string","example":"magnum"},"provider_name":{"type":"string","example":"Magnum 4D"},"country_code":{"type":"string","example":"MY"},"category":{"type":"string","enum":["1st Prize","2nd Prize","3rd Prize","Special","Consolation"],"example":"1st Prize"}}},"SearchResponse":{"type":"object","required":["number","history"],"properties":{"number":{"type":"string","pattern":"^\\d{4}$","example":"1234"},"history":{"type":"array","items":{"$ref":"#/components/schemas/SearchHistoryItem"}}}},"NumberStats":{"type":"object","required":["number","total_wins","first_prize_count","second_prize_count","third_prize_count","special_count","consolation_count","last_won_date","last_won_provider","last_won_category"],"properties":{"number":{"type":"string","pattern":"^\\d{4}$","example":"1234"},"total_wins":{"type":"integer","example":14},"first_prize_count":{"type":"integer","example":2},"second_prize_count":{"type":"integer","example":1},"third_prize_count":{"type":"integer","example":3},"special_count":{"type":"integer","example":5},"consolation_count":{"type":"integer","example":3},"last_won_date":{"type":"string","format":"date","nullable":true,"example":"2026-05-06"},"last_won_provider":{"type":"string","nullable":true,"example":"Magnum 4D"},"last_won_category":{"type":"string","nullable":true,"example":"1st Prize"}}},"HotNumberItem":{"type":"object","required":["number","win_count","providers"],"properties":{"number":{"type":"string","pattern":"^\\d{4}$","example":"8888"},"win_count":{"type":"integer","example":6},"providers":{"type":"array","items":{"type":"string"},"example":["Magnum 4D","Sports Toto"]}}},"HotNumbersResponse":{"type":"object","required":["period_days","numbers"],"properties":{"period_days":{"type":"integer","example":30},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/HotNumberItem"}}}},"ArchiveDateItem":{"type":"object","required":["date","providers"],"properties":{"date":{"type":"string","format":"date","example":"2026-05-06"},"providers":{"type":"array","items":{"type":"string"},"example":["magnum","toto","damacai"]},"first_prizes":{"type":"object","additionalProperties":{"type":"string","pattern":"^\\d{4}$"},"example":{"magnum":"1234","toto":"5678"}}}},"ArchiveDatesResponse":{"type":"object","required":["dates","total","has_more"],"properties":{"dates":{"type":"array","items":{"$ref":"#/components/schemas/ArchiveDateItem"}},"total":{"type":"integer","example":450},"has_more":{"type":"boolean","example":true}}}}}}