Search

Resolve names to IDs across competitions, teams, countries, and sports.

Search is the fastest way to map a human name to an ID. Results are cross-sport and ranked by popularity.

Endpoint

GET /api/v1/search?q={query}

Param	Notes
q	Search string (required).
sportId	Restrict to one sport.
filter	Comma-separated entity types: sports,countries,competitions,competitors.

Sample

curl -H "x-api-key: YOUR_API_KEY" \
  "https://v1.football.sportsapipro.com/api/v1/search?q=barcelona"

{
  "success": true,
  "type": "search",
  "data": {
    "sports": [
      { "id": 1, "name": "Football", "nameForURL": "football" },
      { "id": 2, "name": "Basketball", "nameForURL": "basketball" }
    ],
    "countries": [
      { "id": 2, "name": "Spain", "nameForURL": "spain", "sportTypes": [1, 2, 5, 8, 9] }
    ],
    "competitions": [
      { "id": 11, "name": "LaLiga", "sportType": 1, "countryId": 2 }
    ],
    "competitors": [
      { "id": 132, "name": "FC Barcelona", "sportId": 1, "countryId": 2, "symbolicName": "BAR" }
    ]
  }
}

Filtering

# Only teams
curl -H "x-api-key: YOUR_API_KEY" \
  "https://v1.basketball.sportsapipro.com/api/v1/search?q=lakers&filter=competitors"

# Only competitions, only football
curl -H "x-api-key: YOUR_API_KEY" \
  "https://v1.football.sportsapipro.com/api/v1/search?q=premier&sportId=1&filter=competitions"

Build an autocomplete

let timer;
input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(async () => {
    const r = await fetch(
      `https://v1.football.sportsapipro.com/api/v1/search?q=${encodeURIComponent(input.value)}&filter=competitors`,
      { headers: { 'x-api-key': KEY } }
    );
    const { data } = await r.json();
    render(data.competitors.slice(0, 8));
  }, 200);
});

30-second cache TTL keeps repeat queries free. Add a 200ms debounce on the client to stay polite to user devices.

Related

• Teams, Competitions, Head-to-Head — places to use the IDs you just resolved.