Team crests, player photos and venue images

The media paths are /api/football/media/teams/{id}, /api/football/media/players/{id} and /api/football/media/venues/{teamId}. Venue images use a team identifier, not a separate venue ID. These customer routes require authentication and entitlement: fetch them on your server with X-API-Key or a bearer header. A bare image tag cannot add that header, and placing a key in the image URL would expose it to readers.

That last point catches people out. If you hold a venue identifier from a squad response, do not put it in the venue route. Use the team identifier of the club whose ground you want to show.

The routes validate identifiers, fetch from the upstream source, check that the result is a real image and cache it. Upstream URLs are never exposed to your visitors.

Serving images through our own route has three benefits. It keeps upstream locations private, which matters for licensing and stability. It lets us validate content, so a broken or unexpected response becomes a clean error rather than a corrupt image on your page. And it lets us cache, so popular crests load quickly without repeated upstream fetches.

It also gives you a stable URL pattern. If the upstream source changes how it stores images, your code does not change.

Not every player has a photo and not every venue has an image. When an image fails to load, show a fallback that is clearly a placeholder: initials on a tinted background for players, a simple shield shape with the club's short name for teams, and a neutral panel for venues. Never substitute a different person's photo or a generic stadium that could be mistaken for the real one.

Handle the error event on the image element and swap in the fallback. Reserve the image's space with fixed width and height so the layout does not jump when the swap happens.

Crests appear many times on a page: in fixtures, tables and squad lists. Set explicit dimensions, use lazy loading for images below the fold, and let the browser cache them. A league table with twenty crests should not block the first paint while the images download.

Avoid enormous display sizes. A crest shown at thirty-two pixels does not need a high-resolution source on every row, and requesting fewer large images keeps pages fast on mobile networks.

Images are subject to the same display terms as the rest of the data. Show them on your own product, through our route, and do not copy them into a public bucket or redistribute them as a set. If your use case needs something else, such as print, ask first.

Club crests are trademarks. Use them to identify the club in context, as football sites routinely do, and avoid altering them, combining them into new logos or implying endorsement.

League logos were not verified during qualification, so the media route does not offer them. Design competition headers that work with text: the competition name in a confident typeface, perhaps with a country label, is clean and avoids the risk of showing an outdated or incorrect mark.

If league logos qualify later, the coverage page will say so before any route appears.

Give each crest an alt text that names the club, for example the club's name followed by crest. For player photos, use the player's name. Where an image sits beside the same name in text, an empty alt attribute avoids repetition for screen reader users. Decorative venue backgrounds can also use empty alt text if the venue is named nearby.

On a squad page for team 9260, the header shows the crest from the teams route and a wide venue image from the venues route, both with the same team identifier. Each player row shows a small photo from the players route with an initials fallback. All images have fixed dimensions, and rows below the fold load lazily.

If the venue image fails, the header falls back to a tinted panel with the venue name in text. The page remains complete and honest, and no visitor sees a broken image icon.

Before launch, render every team in your competitions and every player in their squads in a single test page. Count how many images load and how many fall back. If a whole club's photos fail, investigate before going live rather than discovering it from readers. Repeat the test after each transfer window, when new players arrive without photos and fallbacks become more common for a while.

Check the page on a slow mobile connection too. A squad page with thirty photos should remain usable while images arrive, with text visible immediately and photos filling in without moving anything.