Logo Endpoint

Unified API: One endpoint that handles league logos, team logos, and matchup logos.

Endpoints:

  • /:league/logo[.png] - League logo (raw from provider)
  • /:league/:team/logo[.png] - Team logo (raw from provider)
  • /:league/:team1/:team2/logo[.png] - Matchup logo (1024x1024, transparent)

Parameters

  • league - Sport league code (see Supported Leagues)
  • team / team1 / team2 - Team identifier (name, city, or abbreviation)
    • Athlete Sports (Tennis, MMA): Use athlete names (e.g., djokovic, serena-williams)
    • Doubles/Teams: Use + to combine multiple athletes (e.g., djokovic+federer)

Query Parameters

Parameter Type Default Description
variant string light Logo variant: light or dark (league/team only, without style)
style integer 1 Visual style 1-6 (matchup). For league/team logos, style=1 generates a compact diagonal split image
size integer 1024 Output size: 256, 512, 1024, or 2048 (matchup, or league/team with style=1)
logo boolean false Include league logo (matchup only)
trim boolean true Trim whitespace (matchup, or league/team with style=1)
badge string - Add quality badge overlay: ALT, 4K, HD, FHD, or UHD (matchup only)
winner string - Winning team identifier - displays losing team in greyscale (matchup only)
fallback boolean false Single team: Return league logo. Matchup: Use greyscale league logo for missing teams (or skipLogos mode for configured leagues)

Matchup Styles

Applies to: /:league/:team1/:team2/logo only

Styles 3-6 include logo=true to display the league logo. Styles 1-2 have transparent backgrounds.

Style Description Preview
1: Compact Diagonal Split Thumbnail style 1 compressed into logo footprint with transparent background. Style 1
2: Side by Side Team logos placed side by side with transparent background. Style 2
3: Circle Badges Circular badges with team colors, league logo overlays bottom. Style 3
4: Square Badges Square badges with team colors, league logo overlays bottom. Style 4
5: Circle with League Logo Left Circular badges with league logo on left side (white background, requires league logo). Style 5
6: Square with League Logo Left Square badges with league logo on left side (white background, requires league logo). Style 6

Examples

League Logos

Raw league logo from provider. Add style=1 for a compact diagonal split with mood color derived from the league logo.

League Preview URL
NHL NHL Logo /nhl/logo
NBA NBA Logo /nba/logo
MLB (Dark) MLB Logo /mlb/logo?variant=dark
NHL (Style 1) NHL Style 1 /nhl/logo?style=1

Team Logos

Raw team logo from provider. Add style=1 for a solid rectangle in the team’s primary color with the team logo centered.

Team Preview URL
Leafs Leafs Logo /nhl/leafs/logo
Raptors Raptors Logo /nba/raptors/logo
Blue Jays Blue Jays Logo /mlb/bluejays/logo
Leafs (Style 1) Leafs Style 1 /nhl/leafs/logo?style=1

Matchup Logos

Basic:

GET /nhl/leafs/canadiens/logo
GET /nba/raptors/lakers/logo?style=3
GET /mlb/bluejays/redsox/logo?size=2048
GET /nhl/oilers/flames/logo?badge=4K
GET /mls/toronto-fc/montreal/logo?badge=ALT&style=2

Fallback Behavior

When fallback=true is set, the API gracefully handles missing data instead of returning errors.

Unsupported League Fallback

If a league is not configured but exists in ESPN’s API, automatically uses ESPN provider.

Request Behavior
/eng.w.1/team1/team2/logo?fallback=true Detects unconfigured league → creates temporary config → resolves teams normally

This enables support for 100+ ESPN leagues (e.g., WSL, Brazilian Serie A, J-League, Liga MX lower divisions) without manual configuration.

Single Team Fallback

If a team is not found, returns the league logo instead.

Request Preview Behavior
/nba/invalidteam/logo?fallback=true Single Team Fallback Returns NBA league logo

Matchup Fallback

If one or both teams are not found, uses greyscale league logo for missing teams.

Request Preview Behavior
/nhl/leafs/invalidteam/logo?fallback=true&style=2 Matchup Fallback Valid team + greyscale NHL logo
/mlb/invalidteam1/invalidteam2/logo?fallback=true&style=3 Both Teams Fallback Both sides use greyscale MLB logo

skipLogos Fallback

Leagues configured with skipLogos: true (e.g., Olympics, F1, NASCAR, IndyCar) use a different fallback style. Instead of greyscale logos, the matchup renders colored rectangles with the league logo centered. The background color is automatically derived from the league logo’s dominant color.

Request Preview Behavior
/f1/any/any/logo?fallback=true F1 Fallback Mood-colored rectangles + F1 league logo

See Customization → skipLogos Mode for how to enable this on custom leagues.

Winner Effect

The winner parameter displays the losing team in greyscale (35% opacity with grey colors), making the winner stand out in full color.

Team Matching: Uses the same flexible matching as team parameters - accepts team names, cities, or abbreviations.

Basic Usage:

GET /nhl/leafs/canadiens/logo?winner=leafs
GET /nba/lakers/celtics/logo?winner=lakers&style=2
GET /mlb/yankees/redsox/logo?winner=yankees&size=2048
Request Preview Result
/nhl/leafs/canadiens/logo?winner=leafs Winner Leafs Leafs in color, Canadiens greyscale
/nhl/leafs/canadiens/logo?winner=canadiens&style=2 Winner Canadiens Canadiens in color, Leafs greyscale

Combined with Other Parameters:

GET /nfl/chiefs/49ers/logo?winner=chiefs&badge=4K
GET /nba/warriors/cavaliers/logo?winner=warriors&style=3&logo=true

Flexible Team Matching:

GET /nhl/leafs/canadiens/logo?winner=toronto      # City name
GET /nba/lakers/celtics/logo?winner=lal           # Abbreviation
GET /mlb/yankees/redsox/logo?winner=new-york      # Partial match

If the winner doesn’t match either team, both teams display in full color (no error returned).

Athlete Sports 

GET /tennis/djokovic/federer/logo
GET /tennis/djokovic+federer/nadal+murray/logo?style=2
GET /ufc/jon-jones/stipe-miocic/logo?style=3

Output

  • League/Team: PNG image (original resolution from provider)
  • Matchup: PNG image (1024x1024 by default, transparent background)

Deprecated Endpoints

  • /:league/leaguelogo → Use /:league/logo
  • /:league/:team/teamlogo → Use /:league/:team/logo