# GET /v2/search

Group: Search

A single search over teams (individual competitors included), players, managers, referees, leagues, fixtures, venues, racing series and races; each hit’s type names the endpoint family its id is valid for. Those families are /v2/teams, /v2/players, /v2/managers, /v2/referees, /v2/leagues, /v2/fixtures, /v2/series and /v2/races (venue ids are covered in the note). Player hits include the player’s current team; fixture hits include the teams, league, start time and status; venue hits include city, country and capacity.

Plans: Every plan, Free included.

Note: This API models every competitor as a team, so tennis players and other individual-sport athletes are returned with type team. type is a closed set — manager, referee, series and race were added on 2026-10-24, fixture and venue on 2026-11-04 — so ignore any value your client does not recognise. Three fields depend on the type and are null for all others: venue (a Venue), team (the player’s current team, as a TeamRef) and fixture ({ home, away, league, startTime, status }, with status as the coarse StatusType — the score and the rest come from /v2/fixtures/{id}). Venue hit ids work with /v2/venues/{id} and match the id in Fixture.venue and TeamDetail.venue. Since 2026-11-04 team hits include gender (male | female | mixed, matching TeamDetail), which lets you mark a women’s team without a call to /v2/teams/{id}; it is null for every other type. Venue hits come from a separate search at the source and are merged in by relevance. Passing type (since 2026-11-09) restricts the list to that type, returns 20 hits per page and reaches much further than the mixed list: ask for ?q=smith&type=player and pages go up to 50; hasNextPage stays true as long as a page is full. type=series comes from the mixed list and is therefore a single page — the source offers no paged search for series. Managers and referees also get image, a photo on our CDN (since 2026-11-04; null if the source has none); series, races, fixtures and venues always have image null.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `q` | query | yes | text to search for: 2–100 characters once trimmed and free of control characters, otherwise a 400 names q as the problem |
| `type` | query | no | limits hits to one type — team \| player \| league \| manager \| referee \| series \| race \| fixture \| venue — at 20 per page; leave it out for the single-page mixed list |
| `page` | query | no | page number from 0 to 50 (defaults to 0); a page above 0 needs a type other than series |

## Response

- `data`: `SearchResult[]`
- `meta`: query, type, page, count, hasNextPage
- Objects: SearchResult (https://datasportsapi.com/markdown/reference.md#searchresult)

## Errors

- 400 bad_request — q is absent, type is not recognised, page is not within 0–50, or page is above 0 while type is missing or set to series

Plus the common errors (https://datasportsapi.com/markdown/docs.md#errors).

## Request

cURL:

```bash
curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/search?q=…"
```

TypeScript:

```ts
const { data, meta } = await client.search.query({ q });
for await (const page of client.search.queryPages({ q })) { … }
```

Python:

```python
res = client.search.query(q=q)
for page in client.search.query_pages(q=q): ...
```

Go:

```go
res, err := client.Search.Query(ctx, &datasportsapi.SearchQueryParams{Q: q})
for page, err := range client.Search.QueryPages(ctx, &datasportsapi.SearchQueryParams{Q: q}) { … }
```

CLI:

```bash
$ dsa search query <q>
$ dsa search query <q> --all -o csv
```

## Example response

```json
{ "data": [ { "type": "player", "id": 3759, "name": "Bukayo Saka", "slug": "bukayo-saka",
    "sport": "football", "gender": null, "image": "https://cdn.datasportsapi.com/v2/players/3759/photo",
    "team": { "id": 18, "name": "Arsenal", "slug": "arsenal", "shortName": null, "code": "ARS",
      "image": "https://cdn.datasportsapi.com/v2/teams/18/logo" }, "fixture": null, "venue": null },
    { "type": "team", "id": 4021, "name": "Arsenal", "slug": "arsenal", "sport": "football", "gender": "female",
      "image": "https://cdn.datasportsapi.com/v2/teams/4021/logo", "team": null, "fixture": null, "venue": null }, … ],
  "meta": { "query": "saka", "type": null, "page": 0, "count": 20, "hasNextPage": false } }

// ?q=smith&type=player&page=1 — players only, 20 a page
{ "data": [ { "type": "player", "id": 51102, "name": "Emile Smith Rowe", … }, … ],
  "meta": { "query": "smith", "type": "player", "page": 1, "count": 20, "hasNextPage": true } }

// ?q=mourinho
{ "data": [ { "type": "manager", "id": 794950, "name": "José Mourinho", "slug": "jose-mourinho", "sport": "football", "image": null,
    "team": null, "fixture": null, "venue": null }, … ],
  "meta": { "query": "mourinho", "type": null, "page": 0, "count": 3, "hasNextPage": false } }

// ?q=camp nou — venues (/v2/venues/{id}) and fixtures
{ "data": [
    { "type": "venue", "id": 812, "name": "Spotify Camp Nou", "slug": "spotify-camp-nou", "sport": null, "image": null,
      "team": null, "fixture": null,
      "venue": { "id": 812, "name": "Spotify Camp Nou", "city": "Barcelona", "country": { "code": "ES", "name": "Spain" }, "capacity": 62652 } },
    { "type": "fixture", "id": 701233, "name": "Barcelona - Real Madrid", "slug": "barcelona-real-madrid", "sport": "football", "image": null,
      "team": null, "venue": null,
      "fixture": { "home": { "id": 21, "name": "Barcelona", … }, "away": { "id": 19, "name": "Real Madrid", … },
        "league": { "id": 8, "name": "LaLiga", … }, "startTime": "2026-10-26T15:15:00.000Z", "status": "finished" } }, … ],
  "meta": { "query": "camp nou", "type": null, "page": 0, "count": 5, "hasNextPage": false } }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/search/query/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
