Skip to content
Tutorials/Build a football productIntermediate9 min read

Deliver team crests and player portraits fast

Decode supplied football images, save team crests and player portraits by ID, and serve fast public visuals without exposing customer API keys.

Flow / Authenticated import, fast public image delivery
  1. Step 1: Discover IDs

    Fixtures, teams and squads

  2. Step 2: Import image

    Authenticated JSON or media route

  3. Step 3: Save asset

    Team/player ID and content type

  4. Step 4: Deliver

    Your image host and browser cache

Use supplied images with your football content

Image lookups and authenticated media routes require Growth or Pro and are not included in Starter. With the applicable access, you may display and cache supplied team logos, club crests, player portraits and venue images with related football content on your own website or application. Ordinary display does not require separate display approval.

League and competition logos use a separate account-activated image service. A competition ID is not a team image ID. Image and trademark ownership stays with the respective owners, and a crest does not imply endorsement.

Choose an authenticated lookup then save the result

The team-images and player-images endpoints return JSON including id, base64 image, encoding and contentType. Import these server-side, or use the documented authenticated binary media routes. Never insert a private REST key into a public image tag. Both image routes accept relevant identities beyond the widget's competition list. Discover IDs from fixtures, squads and profiles; there is no single download-all-images endpoint.

For binary downloads, use /api/football/media/teams/{teamId}, /api/football/media/players/{playerId} or /api/football/media/venues/{teamId}. Venue lookup takes a team ID. These return PNG, JPEG or WebP bytes, not a JSON envelope. The binary route limits each client IP to 60 requests per minute; respect Retry-After and reuse assets you already saved. Successful image requests, including cached ones, count towards account usage.

The following Node.js module exports a saveImage function for an already parsed successful JSON image response. Save it as save-image.mjs, import it in your server-side collector, and call await saveImage(payload, 'team') for a team crest or await saveImage(payload, 'player') for a portrait. It writes a correctly suffixed file locally; use durable object storage and record contentType for production delivery.

javascript
import { writeFile } from 'node:fs/promises';
export async function saveImage(payload, kind) {
  if (!['team', 'player'].includes(kind)) throw new Error('Choose team or player');
  const image = payload?.data;
  const extension = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' }[image?.contentType];
  if (image?.encoding !== 'base64' || !extension || typeof image.image !== 'string') {
    throw new Error('Unexpected raster image response');
  }
  if (!/^[1-9]\d*$/.test(String(image.id))) throw new Error('Missing image identity');
  const bytes = Buffer.from(image.image, 'base64');
  if (!bytes.length || bytes.length > 2000000) throw new Error('Unexpected image size');
  const filename = `${kind}-${image.id}.${extension}`;
  await writeFile(filename, bytes);
  return { filename, id: String(image.id), contentType: image.contentType };
}

Make the ID the image join key

Team crests belong to team IDs; player portraits belong to player IDs. Names, translated spellings and shirt numbers are not reliable keys. Use separate namespaces so that team 193 and player 193 cannot collide.

Deduplicate import jobs across fixtures and record successful, missing and failed outcomes separately. Do not keep requesting a known missing portrait for every page impression, and do not permanently classify a temporary transport failure as a missing image.

Optimise your own browser delivery

Give rendered images fixed dimensions, preserve transparency where appropriate and serve them from a stable URL on your own image host. Cache immutable versions for long periods and change the version when the actual asset changes.

A saved database record does not automatically make an image fast. Check image bytes, asset hosting latency, duplicate browser requests and cache headers. Avoid a chain where the browser opens your image route, which then fetches the external image again on every hit.

Separate asset refresh from live-score refresh

A crest does not need to be downloaded whenever a goal is scored. Refresh identity metadata and image assets on their own schedules and reuse them across live scores, standings, predictions and lineups.

For player portraits, prioritise the competitions and squads your product actually displays. Keep IDs and storage metadata so additional pages can reuse existing assets without a fresh authenticated image request.

All 51 tutorials