Images & Assets

Overview

SportsAPI Pro provides image endpoints for all visual assets across both V1 and V2 APIs.

V2 images require authentication. V2 image endpoints require an x-api-key header and count against your daily rate limit, just like data endpoints. V1 image endpoints remain free and publicly accessible.

V2 Images (Recommended)

All 25 V2 sport APIs serve images at the same path pattern. Replace {sport} with the sport subdomain (e.g., football, basketball, tennis). V2 image requests require an x-api-key header and count against your daily usage quota.

Base URL Pattern

https://v2.{sport}.sportsapipro.com/images/{type}/{id}

Available Image Types

Type	URL Pattern	Example
Team/Club logos	`/images/teams/{teamId}`	`/images/teams/131`
Player photos	`/images/players/{playerId}`	`/images/players/5045`
Country flags	`/images/countries/{countryCode}`	`/images/countries/GB`
Tournament logos	`/images/tournaments/{tournamentId}`	`/images/tournaments/17`
Referee photos	`/images/referees/{refereeId}`	`/images/referees/1234`
Manager photos	`/images/managers/{managerId}`	`/images/managers/5678`

V2 Examples

// Team logo — API key required
const teamLogoUrl = 'https://api.sportsapipro.com/v2/football/images/teams/131';

const response = await fetch(teamLogoUrl, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const blob = await response.blob();

<!-- V2 images require authentication, so serve them via your backend -->
<!-- Your backend fetches the image with the x-api-key header and returns it -->
<img 
  src="/api/proxy-image?sport=football&type=teams&id=131" 
  alt="Manchester United"
  width="64"
  height="64"
/>

function TeamLogo({ sport, teamId, name, apiKey }) {
  const [src, setSrc] = useState('');

  useEffect(() => {
    fetch(`https://v2.${sport}.sportsapipro.com/images/teams/${teamId}`, {
      headers: { 'x-api-key': apiKey }
    })
      .then(res => res.blob())
      .then(blob => setSrc(URL.createObjectURL(blob)))
      .catch(() => {});
  }, [sport, teamId, apiKey]);

  return src ? <img src={src} alt={name} width={64} height={64} /> : null;
}

import requests

# API key required for V2 images
headers = {"x-api-key": "YOUR_API_KEY"}
team_logo_url = "https://api.sportsapipro.com/v2/football/images/teams/131"
response = requests.get(team_logo_url, headers=headers)

# Save to file
with open("team_logo.png", "wb") as f:
    f.write(response.content)

Rate Limit Headers

V2 image responses include rate limit headers:

Header	Description
`X-RateLimit-Limit`	Your daily request limit
`X-RateLimit-Remaining`	Remaining requests today
`X-RateLimit-Reset`	When your quota resets (UTC)

Cross-Sport Image URLs

The same pattern works for all 25 sports:

https://api.sportsapipro.com/v2/football/images/teams/131
https://api.sportsapipro.com/v2/basketball/images/teams/3427
https://api.sportsapipro.com/v2/tennis/images/players/12345
https://api.sportsapipro.com/v2/hockey/images/teams/1234
https://api.sportsapipro.com/v2/cricket/images/teams/5678
https://api.sportsapipro.com/v2/mma/images/players/9012

Current V2 image status

V2 image delivery is restored. Verified 10 September 2026: the V2 image pipeline is serving real image/* responses again for valid IDs. The error contract below still applies if an upstream issue reoccurs — IMAGE_UPSTREAM_UNAVAILABLE with Retry-After: 60 means retry, not a bad request.

Deep logo coverage — V6 route

The V1 (365scores) crest set is incomplete: teams outside the major leagues frequently have no crest and V1 answers with a generic grey placeholder. The V6 dataset carries crests far deeper, including amateur and regional divisions. V6 responses return logo / image / squareLogo as bare filenames, not URLs. Fetch them from:

GET https://api.sportsapipro.com/v6/{sport}/images/{type}/{filename}
     -H "x-api-key: YOUR_API_KEY"

Asset	Request
Club crest	`/v6/football/images/teams/3e4ab507d5b1007d9932d22ac716be74.png!w80`
Competition logo	`/v6/football/images/competitions/e6b58b5bfee1910ebdf86bb542ab3776.png`
Country flag	`/v6/football/images/countries/{filename}`

Pass the filename exactly as it appears in the response, including any !w80 thumbnail suffix, and use the matching {type} — a competition filename requested under teams returns 404. These requests need x-api-key and count against your quota.

V6 entity IDs are opaque strings and do not match V1 or V2 numeric IDs. Match a team by name plus country once, then store the V6 ID alongside your existing IDs.

Recognising the V1 grey placeholder

When V1 has no crest for a competitor it still answers HTTP 200 with a fixed grey placeholder image — one identical 1,466-byte PNG for every missing team (verified 10 September 2026). Detect it by body size or checksum, not by status code:

resp = requests.get(f"https://api.sportsapipro.com/v1/football/images/competitors/{team_id}")
if len(resp.content) == 1466:          # or compare a stored hash of the placeholder
    missing.append(team_id)            # no V1 crest — try the V6 route

A placeholder means only that the V1 dataset has no crest for that team. A real logo may still exist via V6. imageVersion is optional cache-busting; omitting it never causes a placeholder.

Bulk logo import — recommended order

V1 first (free, unmetered): /v1/football/images/competitors/{id} and /v1/football/images/competitions/{id}. Keep every response that is not the 1,466-byte placeholder.
V2 next (1 request each, restored 10 Sep 2026): /v2/football/images/teams/{id} and /v2/football/images/tournaments/{id} using the V2 IDs you already store.
V6 for the gaps (1 request each): take logo filenames straight from the V6 payloads you already fetch and call /v6/football/images/teams/{filename} or /v6/football/images/competitions/{filename}.
Logos are static — download once, store the bytes in your own storage or CDN, and never re-request them.

V1 Images (Legacy — Free)

V1 image endpoints are free and publicly accessible — no API key required. The V1 image proxy supports cache-busting via the imageVersion parameter returned in API responses.

Base URL

https://api.sportsapipro.com/v1/football/images

V1 Image Types

Type	URL Pattern
Team logos	`/images/competitors/{competitorId}?imageVersion={version}`
Country flags	`/images/countries/{countryId}?imageVersion={version}`
Competition logos	`/images/competitions/{competitionId}?imageVersion={version}`
Athlete photos	`/images/athletes/{athleteId}?imageVersion={version}`
Heat maps	`/images/heatmaps/{token}`

V1 Examples

<!-- No authentication needed for V1 images -->
<img 
  src="https://api.sportsapipro.com/v1/football/images/competitors/131?imageVersion=5" 
  alt="Manchester United"
  width="64"
  height="64"
/>

function TeamLogo({ teamId, imageVersion, name }) {
  return (
    <img 
      src={`https://api.sportsapipro.com/v1/football/images/competitors/${teamId}?imageVersion=${imageVersion}`}
      alt={name}
      onError={(e) => e.target.style.display = 'none'}
    />
  );
}

Image Versions (V1)

The imageVersion parameter is provided in API responses and should be used to ensure you’re displaying the latest image:

{
  "homeCompetitor": {
    "id": 131,
    "name": "Manchester United",
    "imageVersion": 5
  }
}

Heat Maps (V1 Only)

Heat map images are returned from the API with tokenized URLs:

GET /images/heatmaps/{token}

The heatMap field in lineup data from the /game endpoint automatically returns this tokenized format. Simply use the URL as-is — no manual construction needed.

Error Handling

Images that don’t exist return a 404 status. Always include fallback handling:

<img 
  src={imageUrl}
  alt={name}
  onError={(e) => {
    e.target.src = '/fallback-logo.png';
    // or hide the broken image
    e.target.style.display = 'none';
  }}
/>

Error Responses & Troubleshooting

`404 Image not found upstream`

Returned when the requested entity ID does not exist in our system. This replaces the misleading 502 you may have seen previously for invalid IDs.

{
  "error": "Image not found upstream",
  "hint": "Use /api/search?q={name} to find the correct ID for this entity.",
  "status": 404
}

Cached for 5 minutes to avoid repeated upstream calls.

`502 Bad Gateway`

Reserved for genuine upstream pipeline failures in our image delivery layer. The response body identifies the cause and the reply carries Retry-After:

{
  "success": false,
  "error": "Image service temporarily unavailable",
  "code": "IMAGE_UPSTREAM_UNAVAILABLE",
  "message": "The image delivery layer did not respond. Data endpoints are unaffected. Please retry shortly."
}

A 502 here is never caused by a bad ID or a bad key. Data endpoints are served by a separate path and stay available during an image-layer incident. Interim fallback. V1 image routes run on independent infrastructure and are free, so they are the recommended fallback while a V2 image incident is open. They accept the same competitor IDs:

curl "https://v1.badminton.sportsapipro.com/images/competitors/1270381" -o team.png

Valid V1 types are competitors, athletes and competitions. Live status for the image layer is published on status.sportsapipro.com.

Troubleshooting checklist

When an image endpoint returns 404, work through these in order:

Verify the ID exists. Call the corresponding data endpoint first:
- Players → GET /api/players/{id}
- Teams → GET /api/teams/{id}
- Tournaments → GET /api/tournaments/{id}
- If the data endpoint also returns 404, the ID is invalid.

Find the correct ID via search.

curl "https://api.sportsapipro.com/v1/search?q=Messi&filter=athletes&sportId=1" \
  -H "x-api-key: YOUR_API_KEY"
# → athletes[0].id is the canonical SportsAPI Pro player ID

For tournaments, confirm you’re using uniqueTournament.id, not tournament.id. The per-season tournament.id won’t resolve against the image endpoint. See Canonical IDs.
If the data endpoint returns 200 but the image returns 502, that’s a real pipeline issue. Retry once; if it persists, contact support with the request ID.

Worked example

A recent customer migration shipped player IDs from a different provider:

Step	Request	Result
1	`GET /images/players/30981`	`404 Image not found upstream`
2	`GET /api/players/30981`	`404` — confirms the ID isn’t ours
3	`GET /search?q=Messi&filter=athletes&sportId=1`	`competitors[0].id = 12994`
4	`GET /images/players/12994`	`200 OK` — 2.8 KB WebP

The fix in every case was the same: discover the canonical ID via /search and store it. For a step-by-step migration playbook, see the One-Time ID Migration Guide.

Caching

Images are cached at the CDN level
V1: Use imageVersion for cache busting
V2: Images are cached with appropriate Cache-Control headers
Recommended browser cache: 24 hours

Rate Limits

V2 images: Count against your daily API rate limit (same as data endpoints)
V1 images: Do not count against your API rate limit
Excessive automated scraping may be throttled

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

Overview

V2 Images (Recommended)

Base URL Pattern

Available Image Types

V2 Examples

Rate Limit Headers

Cross-Sport Image URLs

Current V2 image status

Deep logo coverage — V6 route

Recognising the V1 grey placeholder

Bulk logo import — recommended order

V1 Images (Legacy — Free)

Base URL

V1 Image Types

V1 Examples

Image Versions (V1)

Heat Maps (V1 Only)

Error Handling

Error Responses & Troubleshooting

`404 Image not found upstream`

`502 Bad Gateway`

Troubleshooting checklist

Worked example

Caching

Rate Limits

​Overview

​V2 Images (Recommended)

​Base URL Pattern

​Available Image Types

​V2 Examples

​Rate Limit Headers

​Cross-Sport Image URLs

​Current V2 image status

​Deep logo coverage — V6 route

​Recognising the V1 grey placeholder

​Bulk logo import — recommended order

​V1 Images (Legacy — Free)

​Base URL

​V1 Image Types

​V1 Examples

​Image Versions (V1)

​Heat Maps (V1 Only)

​Error Handling

​Error Responses & Troubleshooting

​404 Image not found upstream

​502 Bad Gateway

​Troubleshooting checklist

​Worked example

​Caching

​Rate Limits

Overview

V2 Images (Recommended)

Base URL Pattern

Available Image Types

V2 Examples

Rate Limit Headers

Cross-Sport Image URLs

Current V2 image status

Deep logo coverage — V6 route

Recognising the V1 grey placeholder

Bulk logo import — recommended order

V1 Images (Legacy — Free)

Base URL

V1 Image Types

V1 Examples

Image Versions (V1)

Heat Maps (V1 Only)

Error Handling

Error Responses & Troubleshooting

`404 Image not found upstream`

`502 Bad Gateway`

Troubleshooting checklist

Worked example

Caching

Rate Limits