Search

Search for competitions, competitors, and athletes by name

GET /search

Search

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/search \
  --header 'x-api-key: <api-key>'

Endpoint

GET https://v1.football.sportsapipro.com/search

Description

Search across competitions, competitors (teams), and athletes (players) by name. This is the primary endpoint for implementing search functionality in your application, supporting typeahead/autocomplete experiences.

Built-in TTL: 60 seconds. Results are cached for efficient repeated queries.

Finding correct entity IDs. /search is the canonical way to discover IDs when migrating from another provider, or when an image / data endpoint returns 404 for an ID you thought was valid. Three quick examples:

# Player → athletes[0].id = 12994
curl "https://v1.football.sportsapipro.com/search?query=Messi&filter=athletes" \
  -H "x-api-key: YOUR_API_KEY"

# Team → competitors[0].id
curl "https://v1.football.sportsapipro.com/search?query=Manchester%20United&filter=competitors" \
  -H "x-api-key: YOUR_API_KEY"

# Competition → competitions[0].id (this is the canonical league ID,
# equivalent to V2's uniqueTournament.id — see Canonical IDs)
curl "https://v1.football.sportsapipro.com/search?query=Bundesliga&filter=competitions" \
  -H "x-api-key: YOUR_API_KEY"

For common names like “Barcelona” or “Manchester”, multiple matches will be returned — disambiguate by sorting on popularityRank (descending) or by filtering on countryId. For a full migration playbook see the One-Time ID Migration Guide; for tournament ID semantics see Canonical IDs.

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query (minimum 2 characters recommended)
filter	string	No	all	Filter type: all, competitions, competitors, athletes
sports	number	No	-	Sport ID to filter results (1 = Football)

Parameters like appTypeId, langId, timezoneName, and userCountryId are auto-resolved based on request context.

Request Examples

cURL

curl -X GET "https://v1.football.sportsapipro.com/search?query=barcelona&filter=all" \
  -H "x-api-key: YOUR_API_KEY"

Typeahead Implementation: For autocomplete/typeahead search, debounce user input by 300ms and only trigger searches when the query is 2+ characters. This reduces API calls and provides a smoother user experience.

Response

{
  "lastUpdateId": 5494796687,
  "requestedUpdateId": -1,
  "ttl": 60,
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 2,
      "name": "Spain",
      "nameForURL": "spain",
      "imageVersion": 1
    },
    {
      "id": 19,
      "name": "Europe",
      "nameForURL": "europe",
      "imageVersion": 1,
      "isInternational": true
    }
  ],
  "competitions": [
    {
      "id": 7,
      "countryId": 2,
      "sportId": 1,
      "name": "La Liga",
      "shortName": "La Liga",
      "hasStandings": true,
      "hasLiveStandings": true,
      "hasBrackets": false,
      "nameForURL": "la-liga",
      "popularityRank": 12500000,
      "imageVersion": 4,
      "color": "#EE8707",
      "isTop": true
    }
  ],
  "competitors": [
    {
      "id": 131,
      "countryId": 2,
      "sportId": 1,
      "name": "Barcelona",
      "shortName": "Barcelona",
      "symbolicName": "BAR",
      "nameForURL": "barcelona",
      "type": 1,
      "popularityRank": 98500000,
      "imageVersion": 2,
      "color": "#A50044",
      "awayColor": "#EDBB00",
      "mainCompetitionId": 7,
      "hasSquad": true,
      "hasTransfers": true
    },
    {
      "id": 5432,
      "countryId": 35,
      "sportId": 1,
      "name": "Barcelona SC",
      "shortName": "Barcelona SC",
      "symbolicName": "BSC",
      "nameForURL": "barcelona-sc",
      "type": 1,
      "popularityRank": 125000,
      "imageVersion": 1,
      "color": "#FFD700",
      "mainCompetitionId": 1245,
      "hasSquad": true,
      "hasTransfers": false
    }
  ],
  "athletes": [
    {
      "id": 45231,
      "name": "Marc Bartra",
      "shortName": "Bartra",
      "nameForURL": "marc-bartra",
      "countryId": 2,
      "sportId": 1,
      "position": "Defender",
      "imageVersion": 2
    }
  ]
}

Response Fields

Root Object

Field	Type	Description
lastUpdateId	number	Internal versioning ID for incremental updates
requestedUpdateId	number	Requested update ID (-1 = latest)
ttl	number	Cache TTL in seconds (60 for this endpoint)
sports	array	Sports definitions for matched entities
countries	array	Countries referenced by matched entities
competitions	array	Matching competitions (when filter includes)
competitors	array	Matching competitors/teams (when filter includes)
athletes	array	Matching athletes/players (when filter includes)

Competitor Object

Field	Type	Description
id	number	Unique competitor ID
countryId	number	Country ID
sportId	number	Sport ID (1 = Football)
name	string	Full team name
shortName	string	Short display name
symbolicName	string	3-letter code (e.g., “BAR”)
nameForURL	string	URL-friendly slug
type	number	Type (1=club, 2=national team)
popularityRank	number	Popularity ranking (higher = more popular)
imageVersion	number	Logo image version for cache busting
color	string	Primary brand color (hex)
awayColor	string	Away kit color (hex)
mainCompetitionId	number	Primary competition ID
hasSquad	boolean	Whether squad data is available
hasTransfers	boolean	Whether transfer data is available

Competition Object

Field	Type	Description
id	number	Unique competition ID
countryId	number	Country ID
sportId	number	Sport ID
name	string	Full competition name
shortName	string	Short display name
hasStandings	boolean	Whether standings are available
hasLiveStandings	boolean	Whether live standings are supported
hasBrackets	boolean	Whether bracket view is available
nameForURL	string	URL-friendly slug
popularityRank	number	Popularity ranking
imageVersion	number	Logo image version
color	string	Brand color (hex)
isTop	boolean	Whether this is a top/featured competition

Athlete Object

Field	Type	Description
id	number	Unique athlete ID
name	string	Full player name
shortName	string	Short display name
nameForURL	string	URL-friendly slug
countryId	number	Nationality country ID
sportId	number	Sport ID
position	string	Playing position
imageVersion	number	Photo image version

Country Object

Field	Type	Description
id	number	Country ID
name	string	Country name
nameForURL	string	URL-friendly name
imageVersion	number	Flag image version
isInternational	boolean	Whether international (e.g., Europe, World)

Filter Options

Filter Value	Description
all	Returns matches from all entity types
competitions	Only returns matching competitions
competitors	Only returns matching teams/clubs
athletes	Only returns matching players

Use Cases

Typeahead Search

// Debounced search implementation
const [query, setQuery] = useState('');
const [debouncedQuery, setDebouncedQuery] = useState('');

useEffect(() => {
  const timer = setTimeout(() => setDebouncedQuery(query), 300);
  return () => clearTimeout(timer);
}, [query]);

// Only search with 2+ characters
const { data } = useSearch(debouncedQuery, 'all');

Team Lookup

// Search only for teams
const response = await fetch(
  `https://v1.football.sportsapipro.com/search?query=manchester&filter=competitors`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);

// Returns Manchester United, Manchester City, etc.

Player Search

// Search only for players
const response = await fetch(
  `https://v1.football.sportsapipro.com/search?query=messi&filter=athletes`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);

Error Responses

Status	Description
400	Missing required query parameter
401	Invalid or missing API key
429	Rate limit exceeded
500	Internal server error

{
  "error": "Missing required parameter: query"
}

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

query · string · required

Search query

Example:

"Lakers"

filter · enum<string> · default: all

Filter type: all, competitions, competitors, athletes

Available options: all, competitions, competitors, athletes

Response

200

Search results retrieved successfully