SportStatsAPI Golf API

openapi: 3.2.0
info:
  contact:
    name: SportStatsAPI
    url: https://sportstatsapi.com
  description: 'Every public endpoint of SportStatsAPI. Endpoints marked with x-x402 can also be paid per call by an AI agent; the curated list of those is https://api.sportstatsapi.com/api/openapi.agents.json.


    Authentication: an API key (header X-API-Key, or Authorization: Bearer ), or without a key an x402 payment (header PAYMENT-SIGNATURE, USDC on Base). Prices and payment offers: https://api.sportstatsapi.com/.well-known/x402. Docs for AI models: https://api.sportstatsapi.com/llms.txt. MCP server: https://mcp.sportstatsapi.com/mcp.'
  summary: Sports data API and x402 pay-per-call endpoints
  title: SportStats Golf API
  version: '1.0'
servers:
- url: https://api.sportstatsapi.com/api/v1
tags:
- name: golf
paths:
  /golf/money:
    get:
      description: 'A tour''s season money list (rank, earnings, events, wins, top 10s, cuts made) computed from the final leaderboards we hold; the provider''s own money list stopped in 2011. LPGA Tour leaderboards are partial (Wikipedia). earnings_complete is false when a finished tournament of the season lacks earnings (listed in incomplete_events; a player''s line says whether it includes one): totals are then short, not wrong.'
      operationId: getGolfMoney
      parameters:
      - description: pga (default) or lpga
        in: query
        name: tour
        schema:
          type: string
      - description: 'Season (default: the latest with a finished tournament)'
        in: query
        name: season
        schema:
          type: integer
      - description: Maximum results (1-100)
        in: query
        name: limit
        schema:
          default: 50
          type: integer
      - description: Results to skip
        in: query
        name: offset
        schema:
          default: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      $ref: '#/components/schemas/dto.GolfMoneyResponse'
                    meta:
                      $ref: '#/components/schemas/middleware.MetaInfo'
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get a golf money list
      tags:
      - golf
  /golf/players:
    get:
      description: Golfers whose name contains q (PGA Tour players and everyone on our leaderboards), those with the most tournaments first
      operationId: getGolfPlayers
      parameters:
      - description: Part of the name (2+ characters)
        in: query
        name: q
        required: true
        schema:
          type: string
      - description: Maximum results (1-100)
        in: query
        name: limit
        schema:
          default: 50
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      items:
                        $ref: '#/components/schemas/dto.GolfPlayerHit'
                      type: array
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Find golfers
      tags:
      - golf
  /golf/players/{id}:
    get:
      description: Profile (country, birth date and place, PGA Tour rank and the provider's season earnings) and the season's tournaments from our leaderboards with a summary (events, wins, top 10s, cuts made, earnings)
      operationId: getGolfPlayersById
      parameters:
      - description: Player ID
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'Season (default: the latest the player has results in)'
        in: query
        name: season
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      $ref: '#/components/schemas/dto.GolfPlayerResponse'
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Unauthorized
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      - x402: []
      summary: Get a golfer
      tags:
      - golf
      x-x402:
        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        currency: USDC
        discovery: https://api.sportstatsapi.com/.well-known/x402
        minSinglePayment: '0.01'
        network: eip155:8453
        price: '0.005'
  /golf/tournaments:
    get:
      description: 'PGA Tour and LPGA tournaments by start date, with the leader or winner from our leaderboards. Only PGA Tour tournaments have leaderboards (the data provider has none for the LPGA: status no_results once over; incomplete: never final upstream).'
      operationId: getGolfTournaments
      parameters:
      - description: pga or lpga
        in: query
        name: tour
        schema:
          type: string
      - description: Season (year)
        in: query
        name: season
        schema:
          type: integer
      - description: scheduled, live, finished, no_results or incomplete
        in: query
        name: status
        schema:
          type: string
      - description: Tournaments ending on or after this date (YYYY-MM-DD)
        in: query
        name: date_from
        schema:
          type: string
      - description: Tournaments starting on or before this date (YYYY-MM-DD)
        in: query
        name: date_to
        schema:
          type: string
      - description: Maximum results (1-100)
        in: query
        name: limit
        schema:
          default: 50
          type: integer
      - description: Results to skip
        in: query
        name: offset
        schema:
          default: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      items:
                        $ref: '#/components/schemas/dto.GolfTournamentResponse'
                      type: array
                    meta:
                      $ref: '#/components/schemas/middleware.MetaInfo'
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List golf tournaments
      tags:
      - golf
  /golf/tournaments/{id}:
    get:
      description: 'A tournament with its leaderboard: position (tied), to par, strokes per round, thru and today while live, earnings, and per-player stats (birdies, eagles, driving distance and accuracy, greens in regulation, putts); hole-by-hole scores with holes=true'
      operationId: getGolfTournamentsById
      parameters:
      - description: Tournament ID
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Include each player's hole-by-hole scores
        in: query
        name: holes
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      $ref: '#/components/schemas/dto.GolfTournamentResponse'
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get a golf tournament's leaderboard
      tags:
      - golf
components:
  schemas:
    dto.GolfSeasonSummary:
      properties:
        cuts_made:
          type: integer
        earnings:
          type: integer
        events:
          type: integer
        top10s:
          type: integer
        wins:
          type: integer
      type: object
    dto.GolfMoneyLine:
      properties:
        cuts_made:
          type: integer
        earnings:
          type: integer
        earnings_complete:
          description: 'EarningsComplete: false when the player played a tournament of

            incomplete_events (the total may be short).'
          type: boolean
        events:
          type: integer
        player:
          $ref: '#/components/schemas/dto.GolfPlayerRef'
        rank:
          type: integer
        top10s:
          type: integer
        wins:
          type: integer
      type: object
    dto.GolfMoneyResponse:
      properties:
        earnings_complete:
          type: boolean
        incomplete_events:
          items:
            $ref: '#/components/schemas/dto.GolfTournamentName'
          type: array
        players:
          items:
            $ref: '#/components/schemas/dto.GolfMoneyLine'
          type: array
        season:
          type: integer
        source:
          type: string
        tour:
          type: string
      type: object
    dto.GolfTournamentName:
      properties:
        id:
          type: integer
        name:
          type: string
      type: object
    middleware.Response:
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/middleware.ErrorInfo'
        meta:
          $ref: '#/components/schemas/middleware.MetaInfo'
        success:
          type: boolean
      type: object
    dto.GolfLineResponse:
      properties:
        earnings:
          type: integer
        holes:
          items:
            type: integer
          type: array
        player:
          $ref: '#/components/schemas/dto.GolfPlayerRef'
        position:
          type: integer
        rounds:
          items:
            type: integer
          type: array
        stats:
          description: birdies, eagles, pars, bogeys, double_bogeys, driving_distance, driving_accuracy_pct, gir_pct, putts_per_gir, saves_pct
          items:
            type: integer
          type: array
        status:
          description: active, finished, cut, wd
          type: string
        thru:
          type: string
        tied:
          type: boolean
        to_par:
          type: integer
        today:
          type: integer
        total:
          type: integer
        tournament:
          $ref: '#/components/schemas/dto.GolfTournamentResponse'
      type: object
    dto.GolfPlayerResponse:
      properties:
        birth_date:
          type: string
        birth_place:
          type: string
        country:
          type: string
        id:
          type: integer
        name:
          type: string
        pga_rank:
          type: integer
        profile_earnings:
          description: The provider's figure
          type: integer
        results:
          items:
            $ref: '#/components/schemas/dto.GolfLineResponse'
          type: array
        season:
          type: integer
        season_summary:
          $ref: '#/components/schemas/dto.GolfSeasonSummary'
      type: object
    middleware.SourceInfo:
      properties:
        attribution:
          description: show it with the data
          example: 'Data: nflverse (CC-BY 4.0)'
          type: string
        licence:
          description: the licence or terms the data is served under
          example: CC-BY-4.0
          type: string
        name:
          description: provider = our main licensed feed
          example: nflverse
          type: string
      type: object
    middleware.MetaInfo:
      properties:
        attribution:
          description: Attribution a data source's licence asks for (Cricsheet's history).
          type: string
        has_more:
          description: 'HasMore: the cursor-paged list has more rows now (ask again at once).'
          type: boolean
        limit:
          type: integer
        live:
          description: 'Live: the answer is the live feed''s, kept while the match is played

            (cricket ball by ball before Cricsheet''s file replaces it).'
          type: boolean
        next_cursor:
          description: NextCursor continues a cursor-paged list (GET /changes).
          type: string
        offset:
          type: integer
        sources:
          description: 'Sources: where the answer''s data came from, with each source''s licence

            and the attribution it asks for (docs/source-licences.md).'
          items:
            $ref: '#/components/schemas/middleware.SourceInfo'
          type: array
        total:
          type: integer
        warnings:
          description: 'Warnings: query parameters ignored or changed (a limit above the

            maximum is clamped to it; a from/to that is not a date is ignored).'
          items:
            type: string
          type: array
      type: object
    dto.GolfPlayerRef:
      properties:
        id:
          type: integer
        name:
          type: string
      type: object
    middleware.ErrorInfo:
      properties:
        code:
          type: string
        message:
          type: string
      type: object
    dto.GolfTournamentResponse:
      properties:
        attribution:
          type: string
        country:
          type: string
        course:
          type: string
        current_round:
          type: integer
        earnings_complete:
          description: 'EarningsComplete (finished only): every top-3 line has earnings and

            they add up to 90 % of the purse; false: some are missing upstream.'
          type: boolean
        end_date:
          type: string
        id:
          type: integer
        leaderboard:
          items:
            $ref: '#/components/schemas/dto.GolfLineResponse'
          type: array
        leaders:
          items:
            $ref: '#/components/schemas/dto.GolfPlayerRef'
          type: array
        location:
          type: string
        name:
          type: string
        par:
          type: integer
        par_source:
          description: 'Sources of values not from the data provider: par_source wikipedia (the

            event''s course) or leaderboard (our totals minus to-par), purse_source

            wikipedia, result_source wikipedia (a playoff winner the data provider never

            posted, an LPGA leaderboard, earnings the data provider left empty);

            Attribution is set when one is wikipedia.'
          type: string
        players:
          type: integer
        purse:
          type: integer
        purse_source:
          type: string
        result_source:
          type: string
        rounds:
          type: integer
        season:
          type: integer
        start_date:
          type: string
        status:
          type: string
        status_detail:
          description: '"Round 3 - In Progress"'
          type: string
        tour:
          description: pga, lpga
          type: string
        updated_at:
          type: string
      type: object
    dto.GolfPlayerHit:
      properties:
        country:
          type: string
        events:
          type: integer
        id:
          type: integer
        name:
          type: string
      type: object
  responses:
    PaymentRequired:
      content:
        application/json:
          schema:
            properties:
              accepts:
                items:
                  additionalProperties: true
                  type: object
                type: array
              error:
                type: string
              resource:
                properties:
                  mimeType:
                    type: string
                  url:
                    type: string
                type: object
              x402Version:
                example: 2
                type: integer
            required:
            - x402Version
            - accepts
            type: object
      description: 'Payment Required: no API key and no valid payment. The body and the PAYMENT-REQUIRED header (base64 JSON) carry the x402 offers; pay one and repeat the request with PAYMENT-SIGNATURE. Only a 200 answer is charged.'
      headers:
        PAYMENT-REQUIRED:
          description: Base64 JSON of the x402 offers
          schema:
            type: string
  securitySchemes:
    ApiKeyAuth:
      description: API key
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: The same API key as a bearer token
      scheme: bearer
      type: http
    x402:
      description: x402 v2 payment (USDC on Base, eip155:8453) built from the offers of a 402 answer; see https://api.sportstatsapi.com/.well-known/x402
      in: header
      name: PAYMENT-SIGNATURE
      type: apiKey
externalDocs:
  description: x402 payment offers and prices
  url: https://api.sportstatsapi.com/.well-known/x402