openapi: 3.1.0
info:
  title: LottoLens PH Public PCSO Data API
  version: 1.0.0
  description: >-
    Read-only static JSON access to a fixed, independently compiled snapshot of
    13,457 Philippine PCSO draw-result rows and the normal schedule for nine
    games. No authentication is required. These immutable JSON files are served
    through GitHub Pages and CDN caching; clients should cache responses and
    avoid high-frequency polling. No application-level rate-limit headers are
    exposed. This is not an official PCSO database or a prediction service.
  contact:
    name: LottoLens PH
    url: https://lottolensph.com/research/pcso-results-data-coverage
  license:
    name: CC BY 4.0 for original documentation and compiled metadata
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://remo65588-boop.github.io/lottolens-ph-public-data
    description: Public GitHub Pages endpoint
security: []
externalDocs:
  description: Dataset documentation and endpoint index
  url: https://remo65588-boop.github.io/lottolens-ph-public-data/api/
tags:
  - name: Metadata
    description: API version, dataset version, counts, coverage, and checksums.
  - name: Results
    description: Fixed historical draw-result rows with source provenance.
  - name: Schedule
    description: Normal draw days, Philippine-time windows, and result formats.
paths:
  /api/v1/metadata.json:
    get:
      operationId: getSnapshotMetadata
      summary: Get API and fixed-snapshot metadata
      description: >-
        Returns dataset version, coverage, record counts, endpoint URLs, and
        SHA-256 checksums for the immutable snapshot. Cache this response rather
        than polling it frequently.
      tags: [Metadata]
      responses:
        "200":
          description: Snapshot counts, coverage, checksums, and endpoint URLs
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MetadataResponse" }
              example:
                apiVersion: 1.0.0
                datasetVersion: 2.1.0
                fixedSnapshot: true
                snapshotDate: "2026-08-12"
                resultRecordCount: 13457
                scheduleRecordCount: 9
                coverage: { start: "2022-01-02", end: "2026-07-20" }
                games: [2d-lotto, 3d-lotto, 4d-lotto, 6d-lotto, grand-lotto-655, lotto-642, mega-lotto-645, super-lotto-649, ultra-lotto-658]
                endpoints:
                  results: https://remo65588-boop.github.io/lottolens-ph-public-data/api/v1/results.json
                  schedule: https://remo65588-boop.github.io/lottolens-ph-public-data/api/v1/schedule.json
                  openapi: https://remo65588-boop.github.io/lottolens-ph-public-data/api/openapi.yaml
                sha256:
                  resultsJson: bd5473914c74a23fbde983343b5ad9b9b11784236e2edfeb36e256006c0297e3
                documentation: https://remo65588-boop.github.io/lottolens-ph-public-data/api/
                methodology: https://lottolensph.com/research/pcso-results-data-coverage
                license: https://creativecommons.org/licenses/by/4.0/
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/results.json:
    get:
      operationId: getHistoricalResultsSnapshot
      summary: Get all 13,457 historical result rows in the fixed snapshot
      description: >-
        Downloads the complete immutable result snapshot. The response is about
        5 MB, so clients should download once, verify the published checksum,
        and reuse it locally instead of polling.
      tags: [Results]
      responses:
        "200":
          description: Fixed historical result snapshot with row-level provenance
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResultsResponse" }
              example:
                apiVersion: 1.0.0
                datasetVersion: 2.1.0
                fixedSnapshot: true
                snapshotDate: "2026-08-12"
                recordCount: 13457
                coverage: { start: "2022-01-02", end: "2026-07-20" }
                disclaimer: Independent historical snapshot; not an official PCSO database and not a prediction service.
                methodology: https://lottolensph.com/research/pcso-results-data-coverage
                results:
                  - lottery_slug: 2d-lotto
                    draw_date: "2026-07-20"
                    draw_time: "9PM"
                    winning_numbers: "31-08"
                    jackpot_amount: ""
                    status: published
                    published_at: "2026-07-20T21:30:00+08:00"
                    source_name: PhilNews EZ2 Result Today
                    source_url: https://philnews.ph/2026/07/20/ez2-result-today-monday-july-20-2026/
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/schedule.json:
    get:
      operationId: getNormalDrawSchedule
      summary: Get normal draw days, times, and result formats for nine games
      description: >-
        Returns the normal Philippine-time schedule reference. Holidays,
        special draws, and current PCSO advisories can override these rows.
      tags: [Schedule]
      responses:
        "200":
          description: Normal schedule reference; official advisories take precedence
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ScheduleResponse" }
              example:
                apiVersion: 1.0.0
                datasetVersion: 2.1.0
                fixedSnapshot: true
                snapshotDate: "2026-08-12"
                recordCount: 9
                disclaimer: Normal draw windows only; holidays, special draws, and official advisories can change the schedule.
                officialSource: https://www.pcso.gov.ph/
                schedule:
                  - game_slug: 2d-lotto
                    game_name: 2D Lotto
                    game_type: digit
                    result_format: 2 digits
                    normal_draw_days: Daily
                    normal_draw_times_pht: "2:00 PM; 5:00 PM; 9:00 PM"
                    timezone: Asia/Manila
                    official_source: https://www.pcso.gov.ph/
                    reference_page: https://lottolensph.com/lottery/2d-lotto
        "404": { $ref: "#/components/responses/NotFound" }
components:
  responses:
    NotFound:
      description: Static endpoint not found
      content:
        text/html:
          schema: { type: string }
          example: "404: Not Found"
  schemas:
    MetadataResponse:
      type: object
      required: [apiVersion, datasetVersion, fixedSnapshot, snapshotDate, resultRecordCount, scheduleRecordCount, coverage, games, endpoints, sha256, documentation, methodology, license]
      properties:
        apiVersion: { type: string, example: 1.0.0 }
        datasetVersion: { type: string, example: 2.1.0 }
        fixedSnapshot: { type: boolean, const: true }
        snapshotDate: { type: string, format: date, example: 2026-08-12 }
        resultRecordCount: { type: integer, const: 13457 }
        scheduleRecordCount: { type: integer, const: 9 }
        coverage: { $ref: "#/components/schemas/Coverage" }
        games:
          type: array
          items: { type: string }
          example: [2d-lotto, 3d-lotto, 4d-lotto, 6d-lotto, grand-lotto-655, lotto-642, mega-lotto-645, super-lotto-649, ultra-lotto-658]
        endpoints: { type: object, additionalProperties: { type: string, format: uri } }
        sha256: { type: object, additionalProperties: { type: string } }
        documentation: { type: string, format: uri }
        methodology: { type: string, format: uri }
        license: { type: string, format: uri }
    Coverage:
      type: object
      required: [start, end]
      properties:
        start: { type: string, format: date, example: "2022-01-02" }
        end: { type: string, format: date, example: "2026-07-20" }
    ResultsResponse:
      type: object
      required: [apiVersion, datasetVersion, fixedSnapshot, snapshotDate, recordCount, coverage, disclaimer, methodology, results]
      properties:
        apiVersion: { type: string }
        datasetVersion: { type: string }
        fixedSnapshot: { type: boolean, const: true }
        snapshotDate: { type: string, format: date }
        recordCount: { type: integer, const: 13457 }
        coverage: { $ref: "#/components/schemas/Coverage" }
        disclaimer: { type: string }
        methodology: { type: string, format: uri }
        results:
          type: array
          items: { $ref: "#/components/schemas/DrawResult" }
    DrawResult:
      type: object
      required: [lottery_slug, draw_date, draw_time, winning_numbers, jackpot_amount, source_name, source_url, status, published_at]
      properties:
        lottery_slug: { type: string, example: 2d-lotto }
        draw_date: { type: string, format: date, example: "2026-07-20" }
        draw_time: { type: string, example: "9PM" }
        winning_numbers: { type: string, example: "31-08" }
        jackpot_amount:
          type: string
          description: Decimal jackpot amount for jackpot games; empty for digit games.
          example: ""
        source_name: { type: string, example: PhilNews EZ2 Result Today }
        source_url: { type: string, format: uri, example: "https://philnews.ph/2026/07/20/ez2-result-today-monday-july-20-2026/" }
        status: { type: string, const: published }
        published_at: { type: string, format: date-time, example: "2026-07-20T21:30:00+08:00" }
    ScheduleResponse:
      type: object
      required: [apiVersion, datasetVersion, fixedSnapshot, snapshotDate, recordCount, disclaimer, officialSource, schedule]
      properties:
        apiVersion: { type: string }
        datasetVersion: { type: string }
        fixedSnapshot: { type: boolean, const: true }
        snapshotDate: { type: string, format: date }
        recordCount: { type: integer, const: 9 }
        disclaimer: { type: string }
        officialSource: { type: string, format: uri }
        schedule:
          type: array
          items: { $ref: "#/components/schemas/ScheduleRow" }
    ScheduleRow:
      type: object
      additionalProperties: false
      required: [game_slug, game_name, game_type, result_format, normal_draw_days, normal_draw_times_pht, timezone, official_source, reference_page]
      properties:
        game_slug: { type: string, example: 2d-lotto }
        game_name: { type: string, example: 2D Lotto }
        game_type: { type: string, enum: [digit, jackpot], example: digit }
        result_format: { type: string, example: 2 digits }
        normal_draw_days: { type: string, example: Daily }
        normal_draw_times_pht: { type: string, example: "2:00 PM; 5:00 PM; 9:00 PM" }
        timezone: { type: string, example: Asia/Manila }
        official_source: { type: string, format: uri, example: "https://www.pcso.gov.ph/" }
        reference_page: { type: string, format: uri, example: "https://lottolensph.com/lottery/2d-lotto" }