You need to ship a sports integration this week: list supported sports for a filter menu, search teams/leagues by name, and show country flags next to clubs and national teams. By the end of this article you’ll know how to do that with the SofaScore - Live API on Zyla API Hub, including a working curl call, a Python snippet, and notes for using the same API from an AI agent via MCP.
What this API does and when to use it
The SofaScore - Live API exposes endpoints to explore sports metadata and search entities across SofaScore’s catalog. With it, you can:
- Fetch the catalog of available sports (e.g., Football, Tennis, Basketball) to power filters, onboarding flows, or dataset discovery.
- Search across all entities (teams, etc.) by a query string to resolve user input like “real madrid” to a canonical entity with IDs and image paths.
- Retrieve a country flag as raw image bytes when you need to render flags alongside clubs, national teams, or player profiles.
Typical applications: live score dashboards, betting and fantasy tools, content and preview pages, admin back offices for tagging content by sport, and AI agents that need to resolve sports entity names reliably.
Getting started on Zyla API Hub
All calls go through Zyla API Hub with one API key and a subscription + quota model (not pay-per-call). The first API includes a 7-day trial or 50 requests so you can validate quickly. To begin:
- Open the SofaScore - Live API page and start the trial: Start 7-day trial on SofaScore - Live API.
- Copy your API key from the dashboard.
- Send requests to the documented Zyla Hub URLs with the header Authorization: Bearer YOUR_API_KEY.
You can discover more than 10,000 public APIs and manage them from a single account at zylalabs.com. If you plan to add more sports features later, the unified key and subscription make it straightforward.
Available endpoints
Below are the documented endpoints for this API. Only the listed methods, URLs, and parameters are available; implement exactly as shown.
1) Get all sports
- Method: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Parameters: none documented
- Use cases: populate dropdowns and filters, validate sport slugs, pre-seed your DB with sport IDs/slugs.
curl example (copy-paste ready):
curl -s -X GET "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports" \
-H "Authorization: Bearer YOUR_API_KEY"
Official sample JSON response:
[
{
"id": 1,
"name": "Football",
"slug": "football"
},
{
"id": 5,
"name": "Tennis",
"slug": "tennis"
},
{
"id": 2,
"name": "Basketball",
"slug": "basketball"
},
{
"id": 64,
"name": "Baseball",
"slug": "baseball"
},
{
"id": 23,
"name": "Volleyball",
"slug": "volleyball"
},
{
"id": 63,
"name": "American football",
"slug": "american-football"
},
{
"id": 6,
"name": "Handball",
"slug": "handball"
},
{
"id": 20,
"name": "Table tennis",
"slug": "table-tennis"
},
{
"id": 4,
"name": "Ice hockey",
"slug": "ice-hockey"
},
{
"id": 22,
"name": "Darts",
"slug": "darts"
},
{
"id": 72,
"name": "E-sports",
"slug": "esports"
},
{
"id": 11,
"name": "Motorsport",
"slug": "motorsport"
},
{
"id": 65,
"name": "Cycling",
"slug": "cycling"
},
{
"id": 62,
"name": "Cricket",
"slug": "cricket"
},
{
"id": 76,
"name": "Mixed Martial Arts",
"slug": "mma"
},
{
"id": 12,
"name": "Rugby",
"slug": "rugby"
},
{
"id": 29,
"name": "Futsal",
"slug": "futsal"
},
{
"id": 31,
"name": "Badminton",
"slug": "badminton"
},
{
"id": 26,
"name": "Waterpolo",
"slug": "waterpolo"
},
{
"id": 19,
"name": "Snooker",
"slug": "snooker"
},
{
"id": 13,
"name": "Aussie rules",
"slug": "aussie-rules"
},
{
"id": 34,
"name": "Beach volley",
"slug": "beach-volley"
},
{
"id": 109,
"name": "Minifootball",
"slug": "minifootball"
},
{
"id": 7,
"name": "Floorball",
"slug": "floorball"
},
{
"id": 15,
"name": "Bandy",
"slug": "bandy"
},
{
"id": 110,
"name": "Padel",
"slug": "padel"
}
]
Fields you’ll actually use:
- id: numeric identifier for the sport. Store it for lookups and joins in your system.
- name: display name you can show in UI.
- slug: stable identifier suitable for URLs and filters (e.g., “football”, “basketball”).
2) Search all entities
- Method: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Parameters:
- q (string, required): search query, for example real madrid
- What it does: searches all SofaScore entities by the query string. Useful for typeahead, resolving user input to canonical IDs, or auto-linking content to teams.
Example request URL with params (authorization header required):
https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities?q=real+madrid
3) Get country flag
- Method: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Parameters:
- country_code (string, required): an alpha-2 style code, for example EN
- What it does: returns the country flag image bytes. Embed or persist as needed for flag badges.
Example request URL with params (authorization header required):
https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag?country_code=EN
Python example: fetch and use the sports catalog
This Python snippet calls Get all sports, parses the few fields you’ll commonly need, and demonstrates simple caching to avoid refetching repeatedly during the day.
import os
import time
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# Very simple cache: refresh every 6 hours
CACHE_FILE = "/tmp/sofascore_sports.json"
CACHE_TTL_SECONDS = 6 * 60 * 60
def should_refresh(path, ttl):
try:
mtime = os.path.getmtime(path)
except FileNotFoundError:
return True
return (time.time() - mtime) > ttl
def load_cached(path):
import json
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def save_cache(path, data):
import json
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f)
def get_all_sports():
if not should_refresh(CACHE_FILE, CACHE_TTL_SECONDS):
return load_cached(CACHE_FILE)
resp = requests.get(URL, headers=HEADERS, timeout=15)
resp.raise_for_status()
data = resp.json() # Expecting a list of {id, name, slug}
save_cache(CACHE_FILE, data)
return data
if __name__ == "__main__":
sports = get_all_sports()
# Build a lookup: slug -> id
slug_to_id = {s["slug"]: s["id"] for s in sports}
# Keep an ordered list of names for a dropdown
sport_names = [s["name"] for s in sports]
print("Sport slugs -> ids:", slug_to_id)
print("Dropdown options:", sport_names)
Practical implementation notes
- Authentication: all endpoints require the header Authorization: Bearer YOUR_API_KEY.
- Response formats:
- Get all sports returns JSON array items with id, name, slug.
- Search all entities returns JSON with entity metadata matching the query. Use this to map user input to IDs and image paths.
- Get country flag returns image bytes. Treat the body as binary when storing or serving it. Set an appropriate image content-type when you re-serve.
- Caching:
- Sports catalog changes infrequently. Cache the response (e.g., 6–24h) to save quota and reduce startup time.
- Search results are user-driven and vary; you may memoize common queries like club names.
- Country flags are static; store once keyed by country code.
- Error handling: handle non-2xx status codes and timeouts. For search, fall back to showing suggestions or ask the user to refine the query.
- Quotas and trial: the first API includes a 7-day trial or 50 requests. For current access options and pricing beyond the trial, check the API page.
Concrete sports use cases you can ship this week
1) Onboarding flow: pick your sport
Call Get all sports to populate an initial interest selection or to scope your application’s coverage. Persist the sport id and slug so downstream features (e.g., feeds, competitions) can stay within those sports.
2) Team search and resolve
Use Search all entities with q equal to the user’s input. For example, a user types “real madrid”: call the search endpoint and present the top results. Store the returned entity.id and entity.slug for routing or database relations. Use entity.imagePath if you need a crest in your UI.
3) Country flags in lists and match headers
When rendering team lists or international fixtures, fetch country flags by alpha-style code via Get country flag. Cache the image bytes (e.g., S3 or your CDN) keyed by the code so you don’t repeatedly fetch the same asset.
4) Admin tagging and content management
Editorial teams can use the sports catalog to tag articles and videos by sport. Search all entities can power a typeahead to ensure consistent entity IDs in your CMS, preventing duplicate team records.
5) AI assistants that know sports entities
When an AI agent receives a user request referencing a team, call Search all entities to resolve ambiguity and get canonical IDs and image paths before composing a response or fetching more details elsewhere in your stack.
Endpoint details and integration tips
Get all sports
Since there are no request parameters, your integration is straightforward: send a GET to the URL with the authorization header and parse the JSON array. Normalize slugs to lowercase for consistent keys. If your app supports only a subset of sports, filter the array once and keep a local list.
Search all entities
- Parameter q is required and should be URL-encoded. Keep user input trimming and normalization (e.g., collapse multiple spaces).
- The response includes entity metadata; store the returned IDs to link user selections with your internal records. Many systems create a local mapping table: external_id (SofaScore) -> internal_id.
- Typeahead: debounce requests in the UI to avoid overfetching while users type; only call when the query has length ≥ 2–3.
Get country flag
- Parameter country_code is required. The example uses EN. Validate the codes you plan to request and handle missing ones gracefully.
- Since the response is an image’s bytes, persist the raw bytes or convert to base64 for storage where convenient. When serving to browsers, set a correct Content-Type (e.g., image/png) based on the image format you detect.
- For performance, store flags in your static assets or a CDN after the first fetch to keep UI latency low.
Call the API from AI agents via MCP
If you use MCP-compatible clients (Claude Code, Cursor, Windsurf, etc.), you can route calls through the MCP endpoint and your Zyla API key. Point your tool to MCP with apikey=YOUR_API_KEY. Your agent can then invoke the same documented Hub URLs for SofaScore - Live API. This is useful for assistants that need to:
- List sports and propose configuration steps to a developer.
- Resolve entity names (via search) during a chat session.
- Fetch flags to embed in generated UI code or documentation.
Keep the same Authorization header in your tool’s HTTP calls. Log calls and responses during development so you can tune prompt logic or fallback behavior when searches are ambiguous.
Security, deploy, and testing checklist
- Environment variables: store YOUR_API_KEY in your secret manager or CI/CD variables.
- Timeouts and retries: use conservative timeouts (10–15s) and consider a single retry for idempotent GETs.
- Input validation: sanitize q for search and validate country_code before calling.
- Monitoring: log status codes and latencies; alert on elevated 4xx/5xx rates.
- Cache strategy:
- Sports catalog: refresh daily or on deploy.
- Search: memoize common queries or cache per-session to reduce churn.
- Flags: persistent cache/CDN storage; invalidate rarely.
Quick reference
- Get all sports:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Headers: Authorization: Bearer YOUR_API_KEY
- Params: none
- Search all entities:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Headers: Authorization: Bearer YOUR_API_KEY
- Params: q (string, required), e.g., real madrid
- Get country flag:
- GET https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Headers: Authorization: Bearer YOUR_API_KEY
- Params: country_code (string, required), e.g., EN
FAQ
How do I authenticate requests?
Send the header Authorization: Bearer YOUR_API_KEY with every request to the Zyla Hub URLs.
What does “Get country flag” return?
The response body is the flag image bytes. Treat it as binary data. If you proxy or store it, set an appropriate image content-type when serving to clients.
Can I cache the sports list?
Yes. The list doesn’t change often. Cache it in your app (e.g., daily) to speed up startup and save quota.
What query should I pass to Search all entities?
Pass the user’s search string via the q parameter (URL-encoded), for example q=real+madrid. Use the returned entity ids and slugs for stable references in your system.
Is there a free plan?
The first API includes a 7-day trial or 50 requests so you can evaluate quickly. For current access options and pricing after the trial, check the API page.
Ship it
You now have the endpoints and code you need to power sports filters, entity search, and country flags. Create your account and start the 7-day trial directly on the listing: Start 7-day trial on SofaScore - Live API. You can manage everything in one place at zylalabs.com and call the same endpoints from your AI tooling via MCP.