Images & Assets

Access team logos, country flags, competition badges, and player photos

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

JavaScript (fetch)

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

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

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://v2.football.sportsapipro.com/images/teams/131
https://v2.basketball.sportsapipro.com/images/teams/3427
https://v2.tennis.sportsapipro.com/images/players/12345
https://v2.hockey.sportsapipro.com/images/teams/1234
https://v2.cricket.sportsapipro.com/images/teams/5678
https://v2.mma.sportsapipro.com/images/players/9012

---

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

HTML

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

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

Now reserved for genuine upstream pipeline failures, which are rare. Recommended action: retry once after ~2 seconds. If it persists, contact support — it indicates an actual infrastructure issue, not a bad ID.

Troubleshooting checklist

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

1. 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.
2. Find the correct ID via search.
   curl "https://v1.football.sportsapipro.com/search?query=Messi&filter=athletes" \
     -H "x-api-key: YOUR_API_KEY"
   # → athletes[0].id is the canonical SportsAPI Pro player ID
   
3. 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.
4. 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?query=Messi&filter=athletes	athletes[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