---
title: "Search entities by name"
method: GET
path: "/search"
---

# Search entities by name

`GET /search`

## Request

- Base URL: `https://reep-api.rahulkeerthi2-95d.workers.dev`
- URL: `https://reep-api.rahulkeerthi2-95d.workers.dev/search`
- Auth: none declared

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").

## Query parameters

- `name` string, required
- `type` 'player' | 'team' | 'coach' | 'competition' | 'season' | 'match'
- `limit` integer
- `targets` string

## Response `200`

Search results ranked by relevance

- SearchResponse
  - `results` Entity[]
    - `reep_id` string: Universal Reep ID (reep_<type_prefix><8hex>). This is the canonical identifier.
    - `qid` string, nullable: Wikidata QID (convenience field, null for entities not in Wikidata)
    - `type` 'player' | 'team' | 'coach' | 'competition' | 'season' | 'match'
    - `name_en` string
    - `aliases_en` string, nullable
    - `full_name` string, nullable
    - `date_of_birth` string, nullable
    - `nationality` string, nullable
    - `position` string, nullable: Coarse position (forward, midfielder, defender, goalkeeper). Players only.
    - `position_detail` string, nullable: Granular position from Transfermarkt (e.g. Centre-Back, Attacking Midfield, Right Winger). Players only.
    - `current_team_reep_id` string, nullable: Reep ID of current team (players only)
    - `height_cm` number, nullable
    - `country` string, nullable: For teams only
    - `founded` string, nullable: For teams only
    - `stadium` string, nullable: For teams only
    - `competition_reep_id` string, nullable: For seasons only — Reep ID of the parent competition
    - `match_date` string, nullable: For matches only — ISO date of the fixture
    - `kickoff_utc` string, nullable: For matches only — ISO kickoff timestamp when known
    - `home_team_reep_id` string, nullable: For matches only — Reep ID of the home team
    - `away_team_reep_id` string, nullable: For matches only — Reep ID of the away team
    - `home_score` integer, nullable: For matches only — final home score when known
    - `away_score` integer, nullable: For matches only — final away score when known
    - `round_label` string, nullable: For matches only — provider round label
    - `referee` string, nullable: For matches only
    - `attendance` integer, nullable: For matches only
    - `season_label` string, nullable: For matches only — provider-native season label when no canonical season mapping exists
    - `source` string: Provenance (wikidata, opta, etc.)
    - `external_ids` object: Map of provider name to external ID (includes wikidata QID)
    - `_deprecated` boolean: 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` string, nullable: When `_deprecated=true`, the canonical successor `reep_id`. Null on a retirement (entity removed with no successor — a 410 Gone body).
    - `_deprecated_at` string: ISO timestamp when the retired `reep_id` was soft-deleted.
    - `_deprecated_reason` 'retired' | 'chain_depth_exceeded' | 'canonical_missing': 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.
  - `count` integer

## Other responses

- `400`: Missing or invalid parameters

## Changes

- **2026-04-24** `89950e8aa0a9`: 1 warning, 15 info
  - added the new `match` enum value to the `results/items/type` response property for the response status `200`
  - added the new enum value `match` to the `query` request parameter `type`
  - added the optional property `results/items/_canonical_id` to the response with the `200` status
  - added the optional property `results/items/_deprecated` to the response with the `200` status
  - …12 more
- **2026-04-11** `55ab7497b8ea`: 2 warning, 1 info
  - added the new `competition` enum value to the `results/items/type` response property for the response status `200`
  - added the new `season` enum value to the `results/items/type` response property for the response status `200`
  - added the new optional `query` request parameter `targets`
- **2026-04-07** `22d8e0823925`: 1 info
  - added the optional property `results/items/position_detail` to the response with the `200` status
- **2026-04-04** `fd744bd7afe2`: 3 info
  - added the new enum value `competition` to the `query` request parameter `type`
  - added the new enum value `season` to the `query` request parameter `type`
  - added the optional property `results/items/competition_reep_id` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/withqwerty/apis/the-reep-register/changes/search/get.md)

---

[API](https://skmtc.dev/withqwerty/apis/the-reep-register.md) - [All operations](https://skmtc.dev/withqwerty/apis/the-reep-register/llms.txt) - [OpenAPI document](https://skmtc.dev/withqwerty/apis/the-reep-register/revisions/82844e1c9405?raw)