Skip to content
Tutorials/Endpoint tutorialsIntermediate6 min read

Save and display football team crests

Retrieve a football team crest as a base64 JSON image, decode it server-side and cache it by stable team ID for fast website delivery.

Endpoint reference: team-images
Flow / From request to your football product
  1. Step 1: Identify

    Prepare teamId from matching records.

  2. Step 2: Request

    GET /api/v1/football/team-images

  3. Step 3: Validate

    Verify image ID, base64 encoding and raster content type.

  4. Step 4: Reuse

    Save a shared snapshot; this feed's source cache lasts 3600 seconds.

What you will build

Deliver crests from your own saved image store so that a fixture page does not need a fresh authenticated lookup for every badge.

Team logos and club crests by teamId. Returns data.id, validated base64 raster bytes in data.image, encoding='base64' and contentType. Decode server-side or use the authenticated binary media route. You may display and cache supplied crests with football data on your own website or app. Not included in Starter's league-scoped service set.

Check your plan before starting

This endpoint requires Growth or Pro; it is not part of Starter or the Starter trial. A valid Starter key will not unlock it. Use an eligible account with the endpoint enabled, and check the reference for any specialist connection requirements.

The service being published does not guarantee every optional field for every competition or fixture. Check the actual records relevant to the page you are building.

Find identifiers and prepare the request

Supply teamId from the related fixture or profile. Team crests and league logos are distinct resources; do not pass a competition ID as teamId.

Identifiers are strings belonging to specific resources. Keep competition, stage, team, player and static match IDs in separate fields. The code reads identifiers from your environment rather than assuming one sample league is valid for everyone. Growth and Pro customers can discover IDs in the directory; Starter customers should use their saved league IDs from Dashboard → Settings and their permitted fixture or squad records.

  • teamId: required; positive numeric identifier sent as a string.

Make an authenticated server-side request

Set FOOTBALLAPI_KEY to your customer REST key in your server's secret manager. Also set FOOTBALL_TEAM_ID for teamId using the formats above. Save the code as request.mjs and run node request.mjs with Node.js 20 or newer. A widget installation key cannot replace the REST key.

The example makes one request and does not retry automatically. Its 60-second client timeout leaves room for the API's bounded source-read recovery; it is not a promised response time or a browser loading recommendation. Test once in the signed-in playground, then run from a server you control. Visitors should request your own cached delivery route.

After decoding the image, associate it with data.id. Do not embed a customer API key in browser image requests or store the key inside image filenames.

javascript
// Save as request.mjs and run: node request.mjs (Node.js 20+).
// Set the environment variables listed above first. Run only on your server.
const requiredEnv = name => {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`Set ${name} before running this example`);
  return value;
};
const key = requiredEnv("FOOTBALLAPI_KEY");
const url = new URL("https://footballapi.net/api/v1/football/team-images");
url.searchParams.set("teamId", requiredEnv("FOOTBALL_TEAM_ID"));
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
  signal: AbortSignal.timeout(60000)
});
if (!response.ok) {
  const retryAfter = response.headers.get("retry-after");
  throw new Error(`Football API HTTP ${response.status}; Retry-After: ${retryAfter ?? "not supplied"}`);
}
const { data, meta } = await response.json();
console.log({ data, meta });

Interpret and render the response

The JSON image result includes id, image, encoding and contentType. image is base64 content, not an unrestricted public URL.

Decode the base64 image on your server, preserve its content type and serve it from your own media URL. Team images may be displayed and cached with your football content.

This is a flat image object inside data, not a match collection. Append the following excerpt after the request example in the same file. It decodes the supplied raster image in memory; follow the image-storage guide to save and serve it with its content type.

javascript
if (data.encoding !== 'base64' || !data.contentType?.startsWith('image/')) {
  throw new Error('Unexpected image response');
}
const bytes = Buffer.from(data.image, 'base64');
console.log({ id: data.id, contentType: data.contentType, byteLength: bytes.length });

Save requests without losing useful updates

Save crest bytes once under the team ID and serve them through your own browser/CDN cache. Repeated successful JSON or authenticated media lookups can still consume usage.

The published server cache interval for this endpoint is 3600 seconds. This is a server reuse interval, not a guarantee of new data every 3600 seconds and not a promise that requests served from the API cache are free. Your own cache prevents repeat customer API requests.

Include the endpoint, sorted query parameters, account access scope and relevant date or season in your cache key. Coalesce concurrent misses, serve your own saved response while one background refresh runs, and record its fetched time. Apply corrections to stored results without discarding stable IDs.

Date and time fields are retained as supplied. Establish the timezone for the particular feed before converting a kickoff to UTC or a visitor's local time; do not append Z to a timezone-less value just to make it parse.

Check the result before going live

Treat a genuine missing-image response separately from an invalid key. Missing crests need a neutral visual fallback, not an invented club logo.

A 400 response usually needs an input correction, 401 needs a valid key, and 403 needs a plan, saved-league or access check. A disabled endpoint can return 503. Honour Retry-After on 429 responses rather than retrying immediately. Back off on temporary 5xx errors. An empty successful collection is not a reason to launch an unbounded retry loop.

  • Use a known relevant fixture or player for your first comparison.
  • Check that returned competition, season and dates match the page you are building.
  • Keep keys and raw authentication headers out of error logs and support screenshots.
All 51 tutorials