Necesitas implementar una integración deportiva esta semana: listar los deportes soportados para un menú de filtros, buscar equipos/ligas por nombre y mostrar banderas de países junto a clubes y selecciones nacionales. Al final de este artículo sabrás cómo hacerlo con la SofaScore - Live API en Zyla API Hub, incluyendo una llamada curl funcional, un fragmento de Python y notas para usar la misma API desde un agente de IA a través de MCP.
Qué hace esta API y cuándo usarla
La SofaScore - Live API expone endpoints para explorar metadatos deportivos y buscar entidades en el catálogo de SofaScore. Con ella, puedes:
- Obtener el catálogo de deportes disponibles (por ejemplo, Fútbol, Tenis, Baloncesto) para alimentar filtros, flujos de incorporación o descubrimiento de conjuntos de datos.
- Buscar en todas las entidades (equipos, etc.) mediante una cadena de consulta para resolver la entrada del usuario como “real madrid” a una entidad canónica con IDs y rutas de imagen.
- Recuperar una bandera de país como bytes de imagen en bruto cuando necesites renderizar banderas junto a clubes, selecciones nacionales o perfiles de jugadores.
Aplicaciones típicas: paneles de puntuaciones en vivo, herramientas de apuestas y fantasía, páginas de contenido y vista previa, oficinas administrativas para etiquetar contenido por deporte, y agentes de IA que necesitan resolver nombres de entidades deportivas de manera confiable.
Comenzando en Zyla API Hub
Todas las llamadas pasan por Zyla API Hub con una clave API y un modelo de suscripción + cuota (no pago por llamada). La primera API incluye una prueba de 7 días o 50 solicitudes para que puedas validar rápidamente. Para comenzar:
- Abre la página de SofaScore - Live API y comienza la prueba: Comienza la prueba de 7 días en SofaScore - Live API.
- Copia tu clave API desde el panel de control.
- Envía solicitudes a las URL documentadas de Zyla Hub con el encabezado Authorization: Bearer YOUR_API_KEY.
Puedes descubrir más de 10,000 APIs públicas y gestionarlas desde una sola cuenta en zylalabs.com. Si planeas agregar más características deportivas más adelante, la clave unificada y la suscripción lo hacen sencillo.
Endpoints disponibles
A continuación se presentan los endpoints documentados para esta API. Solo los métodos, URLs y parámetros listados están disponibles; implementa exactamente como se muestra.
1) Obtener todos los deportes
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Parámetros: ninguno documentado
- Casos de uso: poblar menús desplegables y filtros, validar slugs de deportes, presembrar tu base de datos con IDs/slugs de deportes.
ejemplo de curl (listo para copiar y pegar):
curl -s -X GET "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports" \
-H "Authorization: Bearer YOUR_API_KEY"
Respuesta JSON de muestra oficial:
[
{
"id": 1,
"name": "Fútbol",
"slug": "football"
},
{
"id": 5,
"name": "Tenis",
"slug": "tennis"
},
{
"id": 2,
"name": "Baloncesto",
"slug": "basketball"
},
{
"id": 64,
"name": "Béisbol",
"slug": "baseball"
},
{
"id": 23,
"name": "Voleibol",
"slug": "volleyball"
},
{
"id": 63,
"name": "Fútbol americano",
"slug": "american-football"
},
{
"id": 6,
"name": "Balonmano",
"slug": "handball"
},
{
"id": 20,
"name": "Tenis de mesa",
"slug": "table-tennis"
},
{
"id": 4,
"name": "Hockey sobre hielo",
"slug": "ice-hockey"
},
{
"id": 22,
"name": "Dardos",
"slug": "darts"
},
{
"id": 72,
"name": "E-sports",
"slug": "esports"
},
{
"id": 11,
"name": "Deportes de motor",
"slug": "motorsport"
},
{
"id": 65,
"name": "Ciclismo",
"slug": "cycling"
},
{
"id": 62,
"name": "Críquet",
"slug": "cricket"
},
{
"id": 76,
"name": "Artes marciales mixtas",
"slug": "mma"
},
{
"id": 12,
"name": "Rugby",
"slug": "rugby"
},
{
"id": 29,
"name": "Futsal",
"slug": "futsal"
},
{
"id": 31,
"name": "Bádminton",
"slug": "badminton"
},
{
"id": 26,
"name": "Waterpolo",
"slug": "waterpolo"
},
{
"id": 19,
"name": "Snooker",
"slug": "snooker"
},
{
"id": 13,
"name": "Reglas australianas",
"slug": "aussie-rules"
},
{
"id": 34,
"name": "Voleibol de playa",
"slug": "beach-volley"
},
{
"id": 109,
"name": "Minifútbol",
"slug": "minifootball"
},
{
"id": 7,
"name": "Floorball",
"slug": "floorball"
},
{
"id": 15,
"name": "Bandy",
"slug": "bandy"
},
{
"id": 110,
"name": "Pádel",
"slug": "padel"
}
]
Campos que realmente usarás:
- id: identificador numérico para el deporte. Almacénalo para búsquedas y uniones en tu sistema.
- name: nombre para mostrar que puedes mostrar en la interfaz de usuario.
- slug: identificador estable adecuado para URLs y filtros (por ejemplo, “football”, “basketball”).
2) Buscar todas las entidades
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Parámetros:
- q (string, requerido): consulta de búsqueda, por ejemplo real madrid
- Qué hace: busca todas las entidades de SofaScore por la cadena de consulta. Útil para autocompletar, resolver la entrada del usuario a IDs canónicos, o enlazar automáticamente contenido a equipos.
Ejemplo de URL de solicitud con parámetros (se requiere encabezado de autorización):
https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities?q=real+madrid
3) Obtener bandera de país
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Parámetros:
- country_code (string, requerido): un código de estilo alfa-2, por ejemplo EN
- Qué hace: devuelve los bytes de imagen de la bandera del país. Incorpora o persiste según sea necesario para las insignias de bandera.
Ejemplo de URL de solicitud con parámetros (se requiere encabezado de autorización):
https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag?country_code=EN
Ejemplo de Python: obtener y usar el catálogo de deportes
Este fragmento de Python llama a Obtener todos los deportes, analiza los pocos campos que comúnmente necesitarás y demuestra un almacenamiento en caché simple para evitar volver a obtener datos repetidamente durante el día.
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}"}
# Caché muy simple: refrescar cada 6 horas
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() # Esperando una lista de {id, name, slug}
save_cache(CACHE_FILE, data)
return data
if __name__ == "__main__":
sports = get_all_sports()
# Construir una búsqueda: slug -> id
slug_to_id = {s["slug"]: s["id"] for s in sports}
# Mantener una lista ordenada de nombres para un menú desplegable
sport_names = [s["name"] for s in sports]
print("Slugs de deportes -> ids:", slug_to_id)
print("Opciones del menú desplegable:", sport_names)
Notas de implementación práctica
- Autenticación: todos los endpoints requieren el encabezado Authorization: Bearer YOUR_API_KEY.
- Formatos de respuesta:
- Obtener todos los deportes devuelve elementos de matriz JSON con id, name, slug.
- Buscar todas las entidades devuelve JSON con metadatos de entidad que coinciden con la consulta. Usa esto para mapear la entrada del usuario a IDs y rutas de imagen.
- Obtener bandera de país devuelve bytes de imagen. Trata el cuerpo como binario al almacenar o servir. Establece un tipo de contenido de imagen apropiado cuando lo vuelvas a servir.
- Caché:
- El catálogo de deportes cambia con poca frecuencia. Almacena en caché la respuesta (por ejemplo, 6–24h) para ahorrar cuota y reducir el tiempo de inicio.
- Los resultados de búsqueda son impulsados por el usuario y varían; puedes memorizar consultas comunes como nombres de clubes.
- Las banderas de países son estáticas; almacena una vez indexadas por código de país.
- Manejo de errores: maneja códigos de estado no 2xx y tiempos de espera. Para la búsqueda, vuelve a mostrar sugerencias o pide al usuario que refine la consulta.
- Cuotas y prueba: la primera API incluye una prueba de 7 días o 50 solicitudes. Para opciones de acceso actuales y precios más allá de la prueba, consulta la página de la API.
Casos de uso deportivos concretos que puedes implementar esta semana
1) Flujo de incorporación: elige tu deporte
Llama a Obtener todos los deportes para poblar una selección inicial de intereses o para definir la cobertura de tu aplicación. Persiste el id y el slug del deporte para que las características posteriores (por ejemplo, feeds, competiciones) puedan mantenerse dentro de esos deportes.
2) Búsqueda y resolución de equipos
Usa Buscar todas las entidades con q igual a la entrada del usuario. Por ejemplo, un usuario escribe “real madrid”: llama al endpoint de búsqueda y presenta los mejores resultados. Almacena el entity.id y entity.slug devueltos para el enrutamiento o relaciones de base de datos. Usa entity.imagePath si necesitas un escudo en tu interfaz de usuario.
3) Banderas de países en listas y encabezados de partidos
Al renderizar listas de equipos o partidos internacionales, obtén banderas de países por código de estilo alfa a través de Obtener bandera de país. Almacena en caché los bytes de imagen (por ejemplo, S3 o tu CDN) indexados por el código para que no vuelvas a obtener el mismo recurso repetidamente.
4) Etiquetado administrativo y gestión de contenido
Los equipos editoriales pueden usar el catálogo de deportes para etiquetar artículos y videos por deporte. Buscar todas las entidades puede alimentar un autocompletado para asegurar IDs de entidad consistentes en tu CMS, previniendo registros duplicados de equipos.
5) Asistentes de IA que conocen entidades deportivas
Cuando un agente de IA recibe una solicitud de un usuario que hace referencia a un equipo, llama a Buscar todas las entidades para resolver ambigüedades y obtener IDs canónicos y rutas de imagen antes de componer una respuesta o buscar más detalles en otra parte de tu pila.
Detalles de los endpoints y consejos de integración
Obtener todos los deportes
Dado que no hay parámetros de solicitud, tu integración es sencilla: envía un GET a la URL con el encabezado de autorización y analiza la matriz JSON. Normaliza los slugs a minúsculas para claves consistentes. Si tu aplicación solo admite un subconjunto de deportes, filtra la matriz una vez y mantén una lista local.
Buscar todas las entidades
- El parámetro q es requerido y debe estar codificado en URL. Mantén la entrada del usuario recortada y normalizada (por ejemplo, colapsa múltiples espacios).
- La respuesta incluye metadatos de entidad; almacena los IDs devueltos para vincular las selecciones del usuario con tus registros internos. Muchos sistemas crean una tabla de mapeo local: external_id (SofaScore) -> internal_id.
- Autocompletar: debilita las solicitudes en la interfaz de usuario para evitar sobrecargas mientras los usuarios escriben; llama solo cuando la consulta tiene una longitud ≥ 2–3.
Obtener bandera de país
- El parámetro country_code es requerido. El ejemplo usa EN. Valida los códigos que planeas solicitar y maneja los que faltan de manera adecuada.
- Dado que la respuesta son los bytes de una imagen, persiste los bytes en bruto o conviértelos a base64 para almacenamiento donde sea conveniente. Al servir a navegadores, establece un Content-Type correcto (por ejemplo, image/png) basado en el formato de imagen que detectes.
- Para rendimiento, almacena banderas en tus activos estáticos o en un CDN después de la primera obtención para mantener baja la latencia de la interfaz de usuario.
Llama a la API desde agentes de IA a través de MCP
Si usas clientes compatibles con MCP (Claude Code, Cursor, Windsurf, etc.), puedes enrutar llamadas a través del endpoint MCP y tu clave API de Zyla. Dirige tu herramienta a MCP con apikey=YOUR_API_KEY. Tu agente puede entonces invocar las mismas URLs documentadas del Hub para SofaScore - Live API. Esto es útil para asistentes que necesitan:
- Listar deportes y proponer pasos de configuración a un desarrollador.
- Resolver nombres de entidades (a través de búsqueda) durante una sesión de chat.
- Obtener banderas para incrustar en el código de interfaz de usuario generado o documentación.
Mantén el mismo encabezado de autorización en las llamadas HTTP de tu herramienta. Registra las llamadas y respuestas durante el desarrollo para que puedas ajustar la lógica de los prompts o el comportamiento de respaldo cuando las búsquedas sean ambiguas.
Lista de verificación de seguridad, implementación y pruebas
- Variables de entorno: almacena YOUR_API_KEY en tu gestor de secretos o variables de CI/CD.
- Timeouts y reintentos: usa timeouts conservadores (10–15s) y considera un solo reintento para GETs idempotentes.
- Validación de entrada: sanitiza q para búsqueda y valida country_code antes de llamar.
- Monitoreo: registra códigos de estado y latencias; alerta sobre tasas elevadas de 4xx/5xx.
- Estrategia de caché:
- Catálogo de deportes: refresca diariamente o al implementar.
- Búsqueda: memoriza consultas comunes o almacena en caché por sesión para reducir la rotación.
- Banderas: almacenamiento en caché/CDN persistente; invalida raramente.
Referencia rápida
- Obtener todos los deportes:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Encabezados: Authorization: Bearer YOUR_API_KEY
- Parámetros: ninguno
- Buscar todas las entidades:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Encabezados: Authorization: Bearer YOUR_API_KEY
- Parámetros: q (string, requerido), por ejemplo, real madrid
- Obtener bandera de país:
- GET https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Encabezados: Authorization: Bearer YOUR_API_KEY
- Parámetros: country_code (string, requerido), por ejemplo, EN
FAQ
¿Cómo autentico las solicitudes?
Envía el encabezado Authorization: Bearer YOUR_API_KEY con cada solicitud a las URLs de Zyla Hub.
¿Qué devuelve “Obtener bandera de país”?
El cuerpo de la respuesta son los bytes de la imagen de la bandera. Trátalo como datos binarios. Si lo proxy o almacenas, establece un tipo de contenido de imagen apropiado al servir a los clientes.
¿Puedo almacenar en caché la lista de deportes?
Sí. La lista no cambia a menudo. Almacénala en caché en tu aplicación (por ejemplo, diariamente) para acelerar el inicio y ahorrar cuota.
¿Qué consulta debo pasar a Buscar todas las entidades?
Pasa la cadena de búsqueda del usuario a través del parámetro q (codificado en URL), por ejemplo q=real+madrid. Usa los IDs y slugs de entidad devueltos para referencias estables en tu sistema.
¿Hay un plan gratuito?
La primera API incluye una prueba de 7 días o 50 solicitudes para que puedas evaluar rápidamente. Para opciones de acceso actuales y precios después de la prueba, consulta la página de la API.
Implementalo
Ahora tienes los endpoints y el código que necesitas para alimentar filtros deportivos, búsqueda de entidades y banderas de países. Crea tu cuenta y comienza la prueba de 7 días directamente en la lista: Comienza la prueba de 7 días en SofaScore - Live API. Puedes gestionar todo en un solo lugar en zylalabs.com y llamar a los mismos endpoints desde tus herramientas de IA a través de MCP.