openapi.yaml

openapi: 3.0.3
info:
  title: The Reep Register
  description: |
    The football entity register. Resolve player, team, coach, competition, season, and match IDs across
    Transfermarkt, FBref, Sofascore, Understat, WhoScored, and 40+ data providers.

    638,000+ entities (400K+ players, 144K+ matches, 45K+ teams, 43K+ coaches,
    3K+ seasons, 200+ competitions) with cross-provider ID mappings sourced from
    Wikidata and custom verified sources. Updated weekly.

    Every entity has a stable Reep ID (`reep_<type_prefix><8hex>`) as the canonical
    identifier. Wikidata QIDs are available as a convenience field where the entity
    exists in Wikidata.

    Reep IDs are immutable: once shipped to prod, an ID keeps resolving to the same
    real-world entity forever. When an entity is re-canonicalised or merged, its old
    `reep_id` redirects to the canonical entity via `_deprecated` / `_canonical_id`
    meta fields on the `/lookup` response — so cached IDs never break.

    People who are both players and coaches (e.g. Pep Guardiola) have separate
    records with type-specific Reep IDs. The unique key is `reep_id`.

    All data is open source: https://github.com/withqwerty/reep
  version: 2.7.0
  contact:
    name: withqwerty
    url: https://github.com/withqwerty/reep

servers:
  - url: https://reep-api.rahulkeerthi2-95d.workers.dev

paths:
  /search:
    get:
      operationId: searchEntities
      summary: Search entities by name
      description: |
        Full-text search across players, teams, coaches, and competitions by name or alias.
        Seasons and matches are excluded from default search to avoid noise; use `type=season`
        or `type=match` explicitly when you want those entity classes.
        Uses prefix matching with BM25 relevance ranking (e.g. "Cole Palm" matches "Cole Palmer").
        Diacritics-insensitive ("Muller" matches "Müller").
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
          example: Cole Palmer
          description: Name to search for (prefix matching on name and aliases)
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [player, team, coach, competition, season, match]
          description: Filter by entity type
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
            maximum: 100
          description: Maximum results to return
        - name: targets
          in: query
          required: false
          schema:
            type: string
          example: wyscout,fbref
          description: |
            Comma-separated list of provider names to include in `external_ids`.
            When omitted, the full cross-provider ID map is returned.
            When set, only the named providers appear in `external_ids`, and the `qid`
            convenience field is populated only if `wikidata` is in the list.
            Unknown provider names are silently ignored. Useful for trimming response
            size when you only need one or two target IDs per match.
      responses:
        "200":
          description: Search results ranked by relevance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
              example:
                results:
                  - reep_id: reep_p2804f5db
                    qid: Q99760796
                    type: player
                    name_en: Cole Palmer
                    aliases_en: Cole Jermaine Palmer
                    date_of_birth: "2002-05-06"
                    nationality: United Kingdom
                    position: midfielder
                    position_detail: Attacking Midfield
                    external_ids:
                      wikidata: Q99760796
                      transfermarkt: "568177"
                      fbref: dc7f8a28
                      sofascore: "982780"
                      soccerway: "525801"
                count: 1
        "400":
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /lookup:
    get:
      operationId: lookupById
      deprecated: true
      summary: Look up entity by Reep ID or Wikidata QID
      description: |
        **Deprecated.** Prefer `POST /batch/resolve` with a one-element `items` array, or
        `GET /search` when you only have a name. This endpoint remains functional but is
        not the recommended path for new integrations.

        Exact lookup by Reep ID or Wikidata QID. The ID type is auto-detected:
        - `reep_p...` / `reep_t...` / `reep_c...` / `reep_l...` / `reep_s...` / `reep_m...` → Reep ID lookup
        - `Q...` → Wikidata QID lookup (may return multiple records for dual-role people)

        Also accepts the legacy `?qid=` parameter for backwards compatibility.
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
          example: reep_p2804f5db
          description: Reep ID (reep_p...) or Wikidata QID (Q...)
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [player, team, coach, competition, season, match]
          description: Filter by entity type (only needed for QID lookups with dual-role people)
      responses:
        "200":
          description: |
            Entity details. When the client asked for a retired `reep_id`
            that has a canonical successor, the response body carries the
            canonical entity's fields with `_deprecated`, `_canonical_id`,
            and `_deprecated_at` attached. Provider-id lookups (QIDs)
            redirect silently — no deprecation meta.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LookupResponse"
        "400":
          description: Missing id parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: |
            The requested `reep_id` was retired with no canonical successor.
            Body contains `_deprecated: true`, `_canonical_id: null`, and
            `_deprecated_reason`. Applies only to direct `reep_id` lookups;
            provider-id paths surface retirement as 200 with empty results.
          content:
            application/json:
              schema:
                type: object
                required: [_deprecated, _canonical_id, _deprecated_at, _deprecated_reason]
                properties:
                  _deprecated:
                    type: boolean
                    enum: [true]
                  _canonical_id:
                    type: string
                    nullable: true
                    enum: [null]
                  _deprecated_at:
                    type: string
                  _deprecated_reason:
                    type: string
                    enum: [retired, chain_depth_exceeded, canonical_missing]

  /resolve:
    get:
      operationId: resolveProviderId
      deprecated: true
      summary: Resolve a provider ID to all other IDs
      description: |
        **Deprecated.** Prefer `POST /batch/resolve` — it accepts a one-element `items`
        array and supports the `targets` parameter for response narrowing. This endpoint
        remains functional but is not the recommended path for new integrations.

        Given a provider name and ID, find the entity and return all cross-provider IDs.
        Provider namespaces are not globally type-unique, so `type` is available when you
        need to disambiguate IDs that exist across multiple entity classes.
      parameters:
        - name: provider
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/ProviderName"
          example: transfermarkt
          description: Source provider name
        - name: id
          in: query
          required: true
          schema:
            type: string
          example: "568177"
          description: ID from the source provider
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [player, team, coach, competition, season, match]
          description: Optional entity type disambiguator for provider IDs reused across types
      responses:
        "200":
          description: Resolved entity with all provider IDs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LookupResponse"
        "400":
          description: Missing provider or id parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Multiple entities share the same provider ID across different types
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /batch/lookup:
    post:
      operationId: batchLookup
      deprecated: true
      summary: Look up multiple IDs in one request
      description: |
        **Deprecated.** Prefer `POST /batch/resolve` for all bulk lookups — it is
        provider-aware, supports the `targets` parameter for response narrowing,
        and echoes each input back in the `from` field for easy correlation.

        Batch lookup by Reep IDs or Wikidata QIDs. Accepts a mix of both.
        A single QID may return multiple records if the person is both a player and coach.
        Results are flattened into a single array, so the response `count` may exceed
        the number of `ids` in the request. Maximum 100 IDs per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ids]
              properties:
                ids:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                  description: Array of Reep IDs or Wikidata QIDs
            example:
              ids: ["reep_p2804f5db", "Q11893"]
      responses:
        "200":
          description: Batch lookup results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchLookupResponse"
        "400":
          description: Invalid body, empty ids array, or exceeds 100 ID limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /batch/resolve:
    post:
      operationId: batchResolve
      summary: Resolve one or more provider IDs to entities (primary endpoint)
      description: |
        The primary bulk translation endpoint. Given a list of `(provider, id, type?)` items,
        returns the matching entities. Use this both for single lookups (one-element array)
        and bulk translation (up to 100 per request).

        **Translation workflow** — to translate N Opta IDs into Wyscout IDs in one call:
        ```
        POST /batch/resolve
        { "items": [{"provider": "opta", "id": "..."}, ...],
          "targets": ["wyscout"] }
        ```
        Each result's `external_ids` will contain only the requested target providers,
        dramatically reducing payload size. The `from` field on every result echoes
        the input so callers can correlate regardless of array order or `not_found` gaps.

        **Error handling** — malformed items return inline errors (`missing_fields`,
        `unknown_provider`, `not_found`) rather than failing the whole batch. The
        response `count` always equals `items.length`; position is preserved.

        Maximum 100 items per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  items:
                    type: object
                    required: [provider, id]
                    properties:
                      provider:
                        $ref: "#/components/schemas/ProviderName"
                      id:
                        type: string
                      type:
                        type: string
                        enum: [player, team, coach, competition, season, match]
                        description: Optional entity type disambiguator for reused provider IDs
                  minItems: 1
                  maxItems: 100
                targets:
                  type: array
                  items:
                    $ref: "#/components/schemas/ProviderName"
                  description: |
                    Optional filter on response `external_ids`. When provided, each
                    matched entity's `external_ids` will contain only the named providers,
                    and the `qid` convenience field is populated only if `wikidata` is in
                    the list. Unknown provider names are silently ignored. Useful for
                    trimming response size when you only need one or two target IDs per
                    translation.
            example:
              items:
                - provider: transfermarkt
                  id: "568177"
                - provider: fbref
                  id: dea698d9
              targets: ["wyscout", "sofascore"]
      responses:
        "200":
          description: Batch resolve results. Position is preserved, `count` equals `items.length`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchResolveResponse"
              example:
                results:
                  - from: {provider: transfermarkt, id: "568177"}
                    reep_id: reep_p2804f5db
                    type: player
                    name_en: Cole Palmer
                    external_ids:
                      wyscout: "569823"
                      sofascore: "982780"
                  - from: {provider: fbref, id: dea698d9}
                    error: not_found
                count: 2
        "400":
          description: Invalid body, empty items array, or exceeds 100 item limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /stats:
    get:
      operationId: getStats
      summary: Database statistics
      description: Returns entity counts by type and ID coverage by provider.
      responses:
        "200":
          description: Statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatsResponse"

components:
  schemas:
    ProviderName:
      type: string
      description: |
        Name of a supported data provider. Sourced from `VALID_PROVIDERS` in the worker.
        Update this list whenever a new provider is added.
      enum:
        - wikidata
        - transfermarkt
        - transfermarkt_manager
        - fbref
        - fbref_verified
        - soccerway
        - sofascore
        - flashscore
        - opta
        - opta_numeric
        - optacore
        - premier_league
        - 11v11
        - espn
        - national_football_teams
        - worldfootball
        - soccerbase
        - kicker
        - uefa
        - lequipe
        - fff_fr
        - serie_a
        - besoccer
        - footballdatabase_eu
        - eu_football_info
        - hugman
        - german_fa
        - statmuse_pl
        - sofifa
        - soccerdonna
        - dongqiudi
        - playmakerstats
        - understat
        - whoscored
        - clubelo
        - sportmonks
        - api_football
        - fotmob
        - thesportsdb
        - impect
        - wyscout
        - skillcorner
        - heimspiel
        - capology

    Entity:
      type: object
      properties:
        reep_id:
          type: string
          description: Universal Reep ID (reep_<type_prefix><8hex>). This is the canonical identifier.
        qid:
          type: string
          nullable: true
          description: Wikidata QID (convenience field, null for entities not in Wikidata)
        type:
          type: string
          enum: [player, team, coach, competition, season, match]
        name_en:
          type: string
        aliases_en:
          type: string
          nullable: true
        full_name:
          type: string
          nullable: true
        date_of_birth:
          type: string
          nullable: true
        nationality:
          type: string
          nullable: true
        position:
          type: string
          nullable: true
          description: Coarse position (forward, midfielder, defender, goalkeeper). Players only.
        position_detail:
          type: string
          nullable: true
          description: Granular position from Transfermarkt (e.g. Centre-Back, Attacking Midfield, Right Winger). Players only.
        current_team_reep_id:
          type: string
          nullable: true
          description: Reep ID of current team (players only)
        height_cm:
          type: number
          nullable: true
        country:
          type: string
          nullable: true
          description: For teams only
        founded:
          type: string
          nullable: true
          description: For teams only
        stadium:
          type: string
          nullable: true
          description: For teams only
        competition_reep_id:
          type: string
          nullable: true
          description: For seasons only — Reep ID of the parent competition
        match_date:
          type: string
          nullable: true
          description: For matches only — ISO date of the fixture
        kickoff_utc:
          type: string
          nullable: true
          description: For matches only — ISO kickoff timestamp when known
        home_team_reep_id:
          type: string
          nullable: true
          description: For matches only — Reep ID of the home team
        away_team_reep_id:
          type: string
          nullable: true
          description: For matches only — Reep ID of the away team
        home_score:
          type: integer
          nullable: true
          description: For matches only — final home score when known
        away_score:
          type: integer
          nullable: true
          description: For matches only — final away score when known
        round_label:
          type: string
          nullable: true
          description: For matches only — provider round label
        referee:
          type: string
          nullable: true
          description: For matches only
        attendance:
          type: integer
          nullable: true
          description: For matches only
        season_label:
          type: string
          nullable: true
          description: For matches only — provider-native season label when no canonical season mapping exists
        source:
          type: string
          description: Provenance (wikidata, opta, etc.)
        external_ids:
          type: object
          additionalProperties:
            type: string
          description: Map of provider name to external ID (includes wikidata QID)
        _deprecated:
          type: boolean
          description: |
            Present and `true` when the client asked for a `reep_id` that has
            been retired. The body carries the canonical entity's fields; the
            `_canonical_id` meta tells the client the underlying `reep_id` has
            moved. Provider-id paths (e.g. `?id=Q42`) redirect silently and do
            NOT set this field.
        _canonical_id:
          type: string
          nullable: true
          description: |
            When `_deprecated=true`, the canonical successor `reep_id`. Null on
            a retirement (entity removed with no successor — a 410 Gone body).
        _deprecated_at:
          type: string
          description: ISO timestamp when the retired `reep_id` was soft-deleted.
        _deprecated_reason:
          type: string
          enum: [retired, chain_depth_exceeded, canonical_missing]
          description: |
            Present on error-shape deprecation responses (410 Gone body). `retired`
            = no successor. The other two are defensive fallbacks that should not
            surface in normal operation.

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        count:
          type: integer

    LookupResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        count:
          type: integer

    BatchLookupResponse:
      type: object
      properties:
        results:
          type: array
          description: |
            Flattened list. A single QID input may expand to multiple entities
            (e.g. dual-role player/coach), so `count` can exceed the number of
            input ids.
          items:
            oneOf:
              - $ref: "#/components/schemas/Entity"
              - type: object
                description: Error for a reep_id that was not found
                required: [id, error]
                properties:
                  id:
                    type: string
                  error:
                    type: string
                    enum: [not_found]
              - type: object
                description: |
                  Gone marker for a reep_id that was retired without a
                  canonical successor. Mirrors the /lookup 410 body shape
                  but lives inline in the batch results array.
                required: [id, error, _deprecated, _canonical_id, _deprecated_at, _deprecated_reason]
                properties:
                  id:
                    type: string
                  error:
                    type: string
                    enum: [gone]
                  _deprecated:
                    type: boolean
                    enum: [true]
                  _canonical_id:
                    type: string
                    nullable: true
                    enum: [null]
                  _deprecated_at:
                    type: string
                  _deprecated_reason:
                    type: string
                    enum: [retired, chain_depth_exceeded, canonical_missing]
              - type: object
                description: Error for a Wikidata QID that was not found
                required: [qid, error]
                properties:
                  qid:
                    type: string
                  error:
                    type: string
                    enum: [not_found]
        count:
          type: integer

    BatchResolveResponse:
      type: object
      properties:
        results:
          type: array
          description: |
            Position-preserved, one result per input item. `count` always equals
            the input `items.length`. Every result — success or error — includes
            a `from` field echoing the input for correlation.
          items:
            oneOf:
              - allOf:
                  - type: object
                    required: [from]
                    properties:
                      from:
                        $ref: "#/components/schemas/FromEcho"
                  - $ref: "#/components/schemas/Entity"
              - type: object
                description: Error variant
                required: [from, error]
                properties:
                  from:
                    $ref: "#/components/schemas/FromEcho"
                  error:
                    type: string
                    enum: [not_found, missing_fields, unknown_provider, unknown_type, ambiguous]
                  types:
                    type: array
                    items:
                      type: string
                    description: Present on `ambiguous` results to show the matching entity classes
        count:
          type: integer

    FromEcho:
      type: object
      description: Echo of the input `(provider, id)` pair so callers can correlate results.
      required: [provider, id]
      properties:
        provider:
          type: string
        id:
          type: string
        type:
          type: string
          nullable: true

    StatsResponse:
      type: object
      properties:
        total_entities:
          type: integer
        by_type:
          type: object
          additionalProperties:
            type: integer
        by_provider:
          type: object
          additionalProperties:
            type: integer
        custom_ids_count:
          type: integer

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message