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';
  }}
/>

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