Odds-API.io Dropping Odds API

openapi: 3.2.0
info:
  description: 'Odds-API.io is a powerful sports betting odds comparison API, providing real-time data from 450+ bookmakers across 34 sports with near zero latency.


    - 450+ bookmakers supported

    - 34 sports including Football, Basketball, Tennis, Esports and more

    - Real-time odds with close to zero latency

    - Pre-match & In-play odds coverage

    - 99.9% uptime for reliability'
  title: Odds-API.io - Real-Time Sports Betting Odds API (v3)…
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Dropping Odds
paths:
  /dropping-odds:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns odds that have dropped significantly from their opening values. Data is pre-computed and updated every ~30 seconds. Results are sorted by `sort`: the selected time window''s drop percentage (default), the latest movement (`recent`) or the soonest kickoff (`kickoff`). Pagination metadata is returned in response headers (X-Total-Count, X-Page, X-Per-Page, X-Updated-At).


        **Data source selection:**

        - If both `sport` and `league` are provided → reads league-specific data (all entries for that league)

        - If only `sport` is provided → reads sport-level data (top 200 per sport)

        - If neither → reads global data (top 500 across all sports)


        **Note:** This endpoint requires a paid plan (Starter or above). Other keys receive a 403 error.


        **Note:** `leagues` and `league` are mutually exclusive. `leagues` fetches from the sport- or global-level dataset and filters server-side.'
      tags:
      - Dropping Odds
      summary: Get Dropping Odds
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: football
        description: Sport name or slug (e.g. Football or football)
        name: sport
        in: query
        schema:
          type: string
      - example: england-premier-league
        description: League slug (e.g. england-premier-league). Requires sport param. Mutually exclusive with leagues.
        name: league
        in: query
        schema:
          type: string
      - example: england-premier-league,spain-laliga
        description: Comma-separated league slugs to filter by multiple leagues at once (e.g. england-premier-league,spain-laliga). Mutually exclusive with league.
        name: leagues
        in: query
        required: false
        schema:
          type: string
      - example: Spread,Totals
        description: 'Comma-separated market names to filter by (case-insensitive). Supported: ML, Spread, Totals, Spread HT, Totals HT, Totals 1Q, Spread 1Q, Team Total Home, Team Total Away, First 5 Innings ML, First 5 Innings Spread, First 5 Innings Totals, Corners Spread, Corners Totals, Corners Spread HT, Corners Totals HT, Bookings Spread, Bookings Totals, Player Props'
        name: markets
        in: query
        schema:
          type: string
      - example: opening
        description: 'Time window for drop filtering and sorting. Default: opening'
        name: timeWindow
        in: query
        schema:
          type: string
          enum:
          - opening
          - 12h
          - 24h
          - 48h
          default: opening
      - example: drop
        description: 'Sort order: `drop` (highest drop % for the selected time window), `recent` (latest movement first) or `kickoff` (soonest event first). Default: drop'
        name: sort
        in: query
        schema:
          type: string
          enum:
          - drop
          - recent
          - kickoff
          default: drop
      - example: 5
        description: 'Minimum drop percentage for the selected time window. Default: 0'
        name: minDrop
        in: query
        schema:
          type: number
          default: 0
      - example: 50
        description: Maximum results per page (default 50, max 200)
        name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - example: 1
        description: Page number, 1-indexed (default 1)
        name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - example: true
        description: 'Include event details (home, away, date, sport, league). Default: false'
        name: includeEventDetails
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          headers:
            X-Total-Count:
              description: Total number of entries matching the filters
              schema:
                type: integer
            X-Page:
              description: Current page number
              schema:
                type: integer
            X-Per-Page:
              description: Number of results per page
              schema:
                type: integer
            X-Updated-At:
              description: Timestamp of the last pipeline run (unix milliseconds)
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.DroppingOddsEntry'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get odds that dropped sharply from their opening price, sorted by drop percentage for the chosen time window and refreshed about every 30 seconds.
      operationId: getDroppingOdds
      x-operation-id-source: derived
components:
  schemas:
    dto.OddsDrop:
      type: object
      properties:
        sinceOpening:
          type: number
          description: Percentage drop since opening
          example: 25.9
        12h:
          type:
          - number
          - 'null'
          description: Percentage drop in last 12 hours
          example: 8.4
        24h:
          type:
          - number
          - 'null'
          description: Percentage drop in last 24 hours
          example: 12.3
        48h:
          type:
          - number
          - 'null'
          description: Percentage drop in last 48 hours
          example: null
    dto.DroppingOddsMovement:
      type: object
      properties:
        opening:
          type: number
          description: Opening odds value
          example: 2.05
        current:
          type: number
          description: Current odds value
          example: 1.52
        drop:
          $ref: '#/components/schemas/dto.OddsDrop'
    dto.DroppingOddsEvent:
      type: object
      properties:
        home:
          type: string
          example: Arsenal
        away:
          type: string
          example: Bournemouth
        date:
          type: string
          description: ISO 8601 date
          example: '2026-04-12T15:00:00.000Z'
        sport:
          $ref: '#/components/schemas/dto.Sport'
        league:
          $ref: '#/components/schemas/dto.League'
    dto.Sport:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    dto.Market:
      type: object
      properties:
        hdp:
          type: number
        label:
          type: string
          description: Player name for player prop markets (e.g. "Carlos Baleba"). Only present on player prop entries.
        name:
          type: string
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    dto.DroppingOddsEntry:
      type: object
      properties:
        eventId:
          type: integer
          example: 69455182
        event:
          $ref: '#/components/schemas/dto.DroppingOddsEvent'
        market:
          $ref: '#/components/schemas/dto.Market'
        betSide:
          type: string
          enum:
          - home
          - away
          - over
          - under
          example: home
        odds:
          $ref: '#/components/schemas/dto.DroppingOddsMovement'
        lastMovedAt:
          type:
          - integer
          - 'null'
          description: Unix milliseconds timestamp of last odds movement
          example: 1775851240182
        updatedAt:
          type: integer
          description: Unix milliseconds timestamp of last pipeline update
          example: 1775854172851
    dto.League:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: Your Odds-API.io API key, sent as the apiKey query parameter. Get one at https://odds-api.io/pricing.
x-origin:
- url: https://api.odds-api.io/v3/docs/doc.json
  format: swagger
  version: '2.0'
  converter:
    url: https://github.com/mermade/oas-kit
    version: 7.0.8