Trabalhando com SofaScore - Live API

Seus stakeholders querem contexto esportivo ao vivo em seu produto esta semana: uma lista de esportes suportados para direcionar a navegação, uma caixa de pesquisa universal que encontra equipes e competições, e bandeiras de países para polir a interface do usuário. Ao final deste guia, você chamará a SofaScore - Live API do Zyla API Hub para buscar o catálogo de esportes, pesquisar entidades por consulta e recuperar bytes de imagem de bandeira, com exemplos prontos para produção em curl e Python que você pode colar em seu código.

O que você pode construir com a SofaScore - Live API

A API fornece três capacidades principais para aplicativos esportivos:

• Obtenha todos os esportes: uma lista completa e estruturada de esportes que você pode apresentar em menus, filtros ou fluxos de integração.
• Pesquise todas as entidades: um único endpoint de consulta que pesquisa entre as entidades do SofaScore (por exemplo, equipes), ideal para barras de pesquisa globais.
• Obtenha a bandeira do país: busque bytes de imagem bruta para uma bandeira de país para exibir ao lado de equipes, jogadores ou competições.

Esta API está disponível no Zyla API Hub, que oferece uma conta, uma chave de API e um modelo de assinatura + cota em mais de 10.000 APIs públicas. Você autentica cada solicitação com Authorization: Bearer YOUR_API_KEY.

Começando no Zyla API Hub

Abra a listagem da SofaScore - Live API no Zyla e inscreva-se. A primeira API em sua conta inclui um teste de 7 dias ou 50 solicitações, depois o uso contínuo segue um modelo de assinatura + cota (não pago por chamada). Não há Plano Gratuito. Você receberá uma única chave de API que funciona em todos os endpoints nesta listagem.

Comece aqui: Inicie o teste de 7 dias na SofaScore - Live API

Informações gerais do marketplace e criação de conta: Zyla API Hub.

Visão geral dos endpoints e exemplos

Obtenha todos os esportes

Retorna uma lista de todos os esportes disponíveis. Use isso para alimentar seu seletor de esportes, navegação de nível superior ou para validar slugs de esportes recebidos.

• Método: GET
• URL: https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
• Parâmetros: nenhum
• Auth: Authorization: Bearer YOUR_API_KEY

curl

curl -s -X GET "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports" \
-H "Authorization: Bearer YOUR_API_KEY"

Resposta JSON de exemplo oficial

[
{
"id": 1,
"name": "Futebol",
"slug": "football"
},
{
"id": 5,
"name": "Tênis",
"slug": "tennis"
},
{
"id": 2,
"name": "Basquete",
"slug": "basketball"
},
{
"id": 64,
"name": "Beisebol",
"slug": "baseball"
},
{
"id": 23,
"name": "Voleibol",
"slug": "volleyball"
},
{
"id": 63,
"name": "Futebol americano",
"slug": "american-football"
},
{
"id": 6,
"name": "Handebol",
"slug": "handball"
},
{
"id": 20,
"name": "Tênis de mesa",
"slug": "table-tennis"
},
{
"id": 4,
"name": "Hóquei no gelo",
"slug": "ice-hockey"
},
{
"id": 22,
"name": "Dardos",
"slug": "darts"
},
{
"id": 72,
"name": "E-sports",
"slug": "esports"
},
{
"id": 11,
"name": "Motorsport",
"slug": "motorsport"
},
{
"id": 65,
"name": "Ciclismo",
"slug": "cycling"
},
{
"id": 62,
"name": "Críquete",
"slug": "cricket"
},
{
"id": 76,
"name": "Artes marciais mistas",
"slug": "mma"
},
{
"id": 12,
"name": "Rugby",
"slug": "rugby"
},
{
"id": 29,
"name": "Futsal",
"slug": "futsal"
},
{
"id": 31,
"name": "Badminton",
"slug": "badminton"
},
{
"id": 26,
"name": "Polo aquático",
"slug": "waterpolo"
},
{
"id": 19,
"name": "Sinuca",
"slug": "snooker"
},
{
"id": 13,
"name": "Regras australianas",
"slug": "aussie-rules"
},
{
"id": 34,
"name": "Voleibol de praia",
"slug": "beach-volley"
},
{
"id": 109,
"name": "Minifutebol",
"slug": "minifootball"
},
{
"id": 7,
"name": "Floorball",
"slug": "floorball"
},
{
"id": 15,
"name": "Bandy",
"slug": "bandy"
},
{
"id": 110,
"name": "Padel",
"slug": "padel"
}
]

Campos que você usará:

• id: identificador numérico que você pode armazenar para mapeamento interno.
• name: nome do esporte legível por humanos para rótulos da interface do usuário.
• slug: URL/componente chave estável para roteamento, CSS ou composição de consulta.

Exemplo em Python

import os
import requests

API_KEY = os.environ.get("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}"}

resp = requests.get(url, headers=headers, timeout=10)
resp.raise_for_status()
sports = resp.json()

# Crie uma pesquisa rápida: slug -> id
slug_to_id = {s["slug"]: s["id"] for s in sports}

# Exemplo de uso
print(f"Total de esportes: {len(sports)}")
print(f"id do Futebol: {slug_to_id.get('football')}")
print("Primeiros três esportes:")
for s in sports[:3]:
print(f"- {s["name"]} (id={s["id"]}, slug={s["slug"]})")

Pesquisar todas as entidades

Pesquise entre as entidades do SofaScore por string de consulta. Use isso para uma única caixa de pesquisa que pode encontrar equipes e entidades relacionadas pelo nome.

• Método: GET
• URL: https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
• Parâmetros:
  • q (string, obrigatório)
• Auth: Authorization: Bearer YOUR_API_KEY

curl

A resposta retorna entidades correspondentes para a consulta fornecida. Use campos como id, name, slug e objetos aninhados, como country, onde presentes, para renderizar os resultados da pesquisa. Se você armazenar os resultados da pesquisa, considere o cache para reduzir chamadas repetidas para as mesmas consultas.

Obter bandeira do país

Busque os bytes da imagem para uma bandeira de país pelo código e, em seguida, renderize como uma imagem base64 em sua interface do usuário ou armazene em seu CDN. Isso é útil para equipes nacionais e competições.

• Método: GET
• URL: https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
• Parâmetros:
  • country_code (string, obrigatório)
• Auth: Authorization: Bearer YOUR_API_KEY

curl

Exemplo de resposta (bytes da imagem, codificados em base64):

iVBORw0KGgoAAAANSUhEUgAAAJYAAACWCAMAAAAL34HQAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAJcEhZcwAACxMAAAsTAQCanBgAAAELUExURUdwTN/f37QVJd7e3t3d3d/f39/f39/f39/f397e3t7e3t3d3d3d3d3d3d/f397e3t/f39/f39zc3N7e3rQUJN/f37MUJLUTJd/f39/f3+Hh4d3d3bMUJLUVJbQUJLUVJbUUJLcQKOHh4d3d3bQVJLQUJN/f397e3rQVJbIWI7ITI7QUJLcYKM4RJP///97e3rQUJPv7++Li4v39/ebm5uDg4Orq6vDw8OTk5Pf397sTJPn5+bsUJPPz8/Ly8u7u7rcUJMcSJOzs7PHx8cQSJO/v77gUJLgTJOjo6MoSJMETJL8TJLUUJL4TJOvr680RJMsSJMsRJMQTJL0TJO3t7cwRJLYUJM0SJLwUJL4UJDN2488AAAAsdFJOUwB/38+AMBAg79+fcJBAv3CfYKC/YICfj79vr0AwcGCvIF+Pz8+vsKBQULAgUCRTtgAABilJREFUeNrtnGdX40YUhoWrhA1uGFj6tmQ34VrFKl6vzdqYDrtJNvX//5JMkSU3YWk0kiYn3A/CB3zMc+776s54NHMlKV6cfThp756+zeVUErlcq7XbPj48kjKLYqOel9WAkLf3GsXUkcqVA7mDIwiL/FE+qKSItrWndKZBIR6vrz+TuL6excKhbG6lwyR3/ND/eZiM7r6dz8bdaHL/tzPzJmUz4ZyVKtvePzMtu2fAeUCA0bNvde/N+UaCUBteorp2H0gEYpHo210/ZeVkXL7pMxkwjeexUGgDjywBMA/KufKZwmARMj0ZME++bg/mIwwWip7lgm1wBHtFocyxBsCGhVLmgim8zF+md585r15ULB8szyVhrn6WBhAPywfb4JWqJU8xYSEwan6lzMNV5iUAHywAelfKlTg34B5NlQb8sKZKvikxC5hfkyomLJQwM46QRTJPcDTgjeU6TGEawF+TXP8OwB8L4Ip8OIPBNoiAA0gGCy5NpkpBqPQ+JIXlCrnBQqVBclgsXITKMSBJLDCciFyEqhuGKg5WVC5C9RUgaSyArxG4XhEFIQ0sIDPX16GqaGhfccCiOoaoq2Vc2/WwVHGxwNBDjUMlJWRl4IRF60R+3biN5wxmeKr4WNDH…

Decodifique o base64 para renderizar. Para a web, prepend data:image/png;base64, à string para uma imagem inline; para dispositivos móveis, decodifique para um array de bytes e armazene em cache.

Detalhes de produção que economizam tempo

• Autenticação: envie Authorization: Bearer YOUR_API_KEY em cada solicitação. Chaves ausentes ou inválidas retornam respostas 401/403.
• Idempotência e segurança: todos os endpoints listados são GET. Eles são seguros para chamar de funções de borda ou backends de clientes com o tratamento de autenticação adequado.
• Cache:
  • Obtenha todos os esportes: o catálogo é relativamente estável; faça cache por 24 horas em sua camada de API ou CDN.
  • Pesquise todas as entidades: os resultados mudam com o tempo e o contexto; faça cache por minutos por consulta única para reduzir custo e latência.
  • Obtenha a bandeira do país: a saída em base64 é determinística por código de país; faça cache de forma agressiva ou armazene a imagem decodificada.
• Paginação: não aplicável aos endpoints documentados. Se você precisar de navegação mais granular além do que está aqui, mantenha o endpoint de pesquisa como sua principal ferramenta de descoberta.
• Carimbos de data/hora e fusos horários: os endpoints documentados aqui não emitem carimbos de data/hora. Se você juntar resultados com outros sistemas, trate essas respostas como apenas metadados e adicione seu próprio contexto de tempo.
• Tratamento de erros: implemente tentativas com backoff para 5xx; não tente novamente 4xx, exceto 429 com backoff. Registre URLs de solicitações e parâmetros de consulta para facilitar a depuração.
• Segurança: não incorpore sua chave de API em aplicativos do lado do cliente. Proxie através de seu serviço sem servidor ou backend e imponha cotas por usuário.

Exemplo de ponta a ponta: construa um seletor de esportes com foco em pesquisa

1. Chame Obter todos os esportes na inicialização para renderizar o filtro de esportes. Persista id, name, slug.
2. Conecte sua caixa de pesquisa global a Pesquisar todas as entidades com q definido como a entrada do usuário. Debounce as teclas para evitar chamadas excessivas.
3. Ao renderizar resultados, se um país estiver associado, use Obter bandeira do país com o código correspondente e armazene a string base64 em cache.
4. Registre seleções por id e slug para roteamento estável e enriquecimento posterior.

Chame a API de agentes de IA com MCP

Se você integrar com ferramentas compatíveis com MCP (por exemplo, assistentes de código em seu ambiente de desenvolvimento), pode direcionar as mesmas chamadas HTTP através do endpoint MCP da Zyla usando sua chave existente: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. Isso permite que um agente invoque a SofaScore - Live API sem incorporar segredos em prompts. Para capacidades e configuração do cliente, veja a página MCP.

Dica: exponha apenas os endpoints que você precisa (Obter todos os esportes, Pesquisar todas as entidades, Obter bandeira do país) na configuração da ferramenta do seu agente e registre as invocações do lado do servidor para auditoria.

Padrões de uso no mundo real

• Integração: peça aos usuários que escolham seus esportes favoritos listando a resposta de Obter todos os esportes; armazene os ids dos esportes selecionados para feeds personalizados.
• Barra de pesquisa: use Pesquisar todas as entidades para autocompletar equipes como “Real Madrid” e navegue os usuários diretamente para sua tela de detalhes.
• UI internacional: mostre bandeiras ao lado dos nomes das equipes e classificações com Obter bandeira do país; faça cache do base64 por código no estilo alpha2/alpha3 esperado pelo endpoint.
• Roteamento e SEO: use slug de esporte (por exemplo, futebol, basquete) como parte de seus caminhos de URL para roteamento estável e links mais limpos.

Testes e solução de problemas

• Testes de fumaça: adicione uma verificação de CI que chama Obter todos os esportes e verifica se as chaves esperadas (id, name, slug) existem e se o array não está vazio.
• Observabilidade: registre código de status, latência e tamanho do corpo; sinalize quaisquer aumentos repentinos no tamanho do payload para o endpoint da bandeira para capturar respostas malformadas.
• Preenchimento: se você precisar armazenar bandeiras para países comuns, chame em lote Obter bandeira do país offline e armazene imagens em seu bucket de ativos.

Perguntas frequentes

Como faço para autenticar na SofaScore - Live API?
Envie um cabeçalho de Autorização com sua chave: Authorization: Bearer YOUR_API_KEY em cada solicitação.

Há um plano gratuito?
Não há Plano Gratuito. A primeira API em sua conta Zyla inclui um teste de 7 dias ou 50 solicitações. Verifique a listagem para opções de acesso atuais.

Posso obter logotipos de equipes ou imagens de ligas através desta API?
Os endpoints documentados aqui cobrem listagem de esportes, pesquisa de entidades e bandeiras de países. Para outros ativos, revise a página de listagem para endpoints adicionais; apenas as URLs neste artigo estão documentadas aqui.

Quais códigos de país são suportados para Obter bandeira do país?
Passe o parâmetro country_code esperado pelo endpoint. Valide os códigos em seu modelo de domínio e armazene resultados bem-sucedidos em cache para evitar pesquisas repetidas.

Posso chamar esses endpoints do frontend?
Use um proxy de backend ou de borda para que você não exponha sua chave de API. Estes são endpoints GET, então o proxy é simples.

Implemente sua integração agora: inscreva-se e obtenha sua chave na página de listagem, depois cole o curl acima e itere. Comece aqui: Inicie o teste de 7 dias na SofaScore - Live API. Se você precisar de outros blocos de construção, navegue mais em Zyla API Hub.