Search

GET

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/basketball/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/basketball/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/basketball/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/basketball/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

Endpoint

GET https://api.sportsapipro.com/v1/football/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://api.sportsapipro.com/v1/football/search?query=Messi&filter=athletes" \
  -H "x-api-key: YOUR_API_KEY"

# Team → competitors[0].id
curl "https://api.sportsapipro.com/v1/football/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://api.sportsapipro.com/v1/football/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 -X GET "https://api.sportsapipro.com/v1/football/search?query=barcelona&filter=all" \
  -H "x-api-key: YOUR_API_KEY"

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

response = requests.get(
    "https://api.sportsapipro.com/v1/football/search",
    params={
        "query": "barcelona",
        "filter": "all"
    },
    headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()

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 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://api.sportsapipro.com/v1/football/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://api.sportsapipro.com/v1/football/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

Last modified on June 29, 2026

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/basketball/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/basketball/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/basketball/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/basketball/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Endpoint

Description

Parameters

Request Examples

Response

Response Fields

Root Object

Competitor Object

Competition Object

Athlete Object

Country Object

Use Cases

Typeahead Search

Team Lookup

Player Search

Error Responses

Authorizations

Query Parameters

Response

​Endpoint

​Description

​Parameters

​Request Examples

​Response

​Response Fields

​Root Object

​Competitor Object

​Competition Object

​Athlete Object

​Country Object

​Filter Options

​Use Cases

​Typeahead Search

​Team Lookup

​Player Search

​Error Responses

Authorizations

Query Parameters

Response

Endpoint

Description

Parameters

Request Examples

Response

Response Fields

Root Object

Competitor Object

Competition Object

Athlete Object

Country Object

Filter Options

Use Cases

Typeahead Search

Team Lookup

Player Search

Error Responses