Probabilidades 1X2
Probabilidades local, empate y visitante en formato 0..1.
Beta privada
API Foresportia para desarrolladores
Accede a probabilidades de partido, mercados de goles, badges de estabilidad y señales de contexto para crear tus propias herramientas de fútbol.
SDK Python oficial
La API Foresportia cuenta con un SDK Python oficial disponible en PyPI. Permite llamar a los endpoints beta desde un script, un notebook o un backend sin escribir manualmente las peticiones HTTP. El acceso a la API sigue sujeto a validación de la beta privada: instalar el paquete no da acceso automático a los datos.
Los desarrolladores de Python pueden empezar con la documentación oficial del SDK Python de Foresportia
pip install foresportiafrom foresportia import ForesportiaClient
with ForesportiaClient.from_env() as client:
picks = client.picks_today()
print(len(picks.get("matches", [])))El SDK lee `FORES_API_KEY` desde el entorno y lo envía mediante el encabezado `X-API-Key`. Enlaces: paquete PyPI · repositorio GitHub.
Diseñada para análisis, no para consejos de apuestas
La API está pensada para analytics deportivo, dashboards, herramientas privadas, bots, investigación y backtesting.
No es un consejo de apuestas y no garantiza ningún resultado. Las apuestas automatizadas, la reventa de datos brutos o la republicación pública no están permitidas sin autorización explícita.
Qué proporciona la API
La beta privada expone un esquema externo estable, separado de los endpoints utilizados por el sitio.
Badges de confianza
Badges técnicos y etiquetas legibles para la estabilidad del partido.
Marcadores probables
Candidatos de marcadores estructurados cuando el dato está disponible.
BTTS / Over / Under
Mercados de goles expuestos con campos limpios.
Señales de contexto
Clasificaciones, disponibilidad e indicadores contextuales cuando son suficientemente fiables para exponerse.
Datos por liga
Flujos cortos por liga, partido y fecha según el perímetro disponible en beta.
Casos de uso
La API está orientada a integraciones de fútbol serias que necesitan datos estructurados, no promesas de resultado.
Dashboards de fútbol
Seguir probabilidades, mercados de goles y badges de estabilidad.
Bots Telegram / Discord
Publicar lecturas de partidos o alertas privadas según tus criterios.
Notebooks Python
Explorar las señales Foresportia con pandas, notebooks o scripts de investigación.
Previews de partidos
Enriquecer un análisis editorial con probabilidades, contexto y tendencias de goles.
Herramientas media / data analysis
Comparar ligas, filtrar partidos y preparar formatos de contenido basados en datos.
Endpoints beta actuales
Cada endpoint siguiente incluye una descripción corta, el modo de autenticación, un ejemplo curl estático y un ejemplo compacto de respuesta. Los ejemplos protegidos usan `YOUR_API_KEY` como placeholder.
GET /v1/healthPúblico
Comprueba públicamente el estado de la capa API v1.
curl
curl https://api.foresportia.com/v1/healthEjemplo de respuesta
{
"status": "ok",
"api_version": "v1",
"source": "Foresportia"
}Utiliza este endpoint para verificar que la capa API pública es accesible.
GET /v1/meX-API-Key requerido
Devuelve el estado de la cuenta, el plan, la información del cliente y los endpoints disponibles para la clave API actual.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/meEjemplo de respuesta
{
"status": "active",
"plan": "beta_free",
"client": {
"name": "Example User",
"email": "user@example.com",
"usage_type": "dashboard"
},
"endpoints": [
"GET /v1/health",
"GET /v1/me",
"GET /v1/me/usage",
"GET /v1/leagues",
"GET /v1/leagues/{league_code}/matches",
"GET /v1/picks/today",
"GET /v1/matches/today"
]
}Este endpoint permite identificar la cuenta beta asociada a la clave API utilizada desde un servidor o una herramienta privada.
GET /v1/me/usageX-API-Key requerido
Devuelve el uso diario, mensual y por minuto de la clave API actual.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/me/usageEjemplo de respuesta
{
"daily": {
"date": "2026-05-20",
"used": 17,
"limit": 100,
"remaining": 83
},
"monthly": {
"month": "2026-05",
"used": 177,
"limit": 2000,
"remaining": 1823
},
"rate_limit_minute": {
"used": 2,
"limit": 10,
"remaining": 8
},
"last_used_at": "2026-05-20T09:20:25Z"
}Las líneas devueltas también se siguen internamente para el monitoreo operativo.
GET /v1/picks/todayX-API-Key requerido
Devuelve los picks seleccionados para el día actual. Es un subconjunto curado, no todos los partidos disponibles.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/picks/todayEjemplo de respuesta
{
"date": "2026-05-20",
"timezone": "Europe/Paris",
"source": "Foresportia",
"data_version": "example",
"matches": [
{
"id": "0f5f178951689210",
"kickoff": "2026-05-20T18:00:00Z",
"kickoff_local": "2026-05-20T20:00:00+02:00",
"league": {
"code": "NOR",
"name": "Eliteserien",
"country": "Norway"
},
"home_team": "IK Start",
"away_team": "FK Bodø/Glimt",
"probabilities": {
"home": 0.0844,
"draw": 0.1712,
"away": 0.7445
},
"confidence": {
"badge": "ultra_stable",
"label": "Very stable",
"score": 0.773469
},
"likely_scores": [
{
"score": "1-1",
"probability": 0.1234
},
{
"score": "0-1",
"probability": 0.1033
}
],
"markets": {
"btts": 0.5539,
"over_2_5": 0.6685,
"under_2_5": 0.3315
},
"status": "scheduled",
"pick": {
"outcome": "away",
"probability": 0.7445
}
}
]
}Las probabilidades y los mercados están en formato ratio 0..1.
GET /v1/matches/todayX-API-Key requerido
Devuelve todos los partidos disponibles hoy en el formato externo v1. El objeto match es similar a `/v1/picks/today`, pero el endpoint no se limita a los picks seleccionados.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/matches/todayEjemplo de respuesta
{
"date": "2026-05-20",
"timezone": "Europe/Paris",
"source": "Foresportia",
"data_version": "example",
"matches": [
{
"id": "43636da1c3e70181",
"kickoff": "2026-05-20T13:35:00Z",
"kickoff_local": "2026-05-20T15:35:00+02:00",
"league": {
"code": "CHN",
"name": "Chinese Super League",
"country": "China"
},
"home_team": "Shanghai Shenhua",
"away_team": "Wuhan Three Towns",
"probabilities": {
"home": 0.6624,
"draw": 0.2206,
"away": 0.117
},
"confidence": {
"badge": "correct",
"label": "Correct",
"score": 0.73624
},
"markets": {
"btts": 0.5425,
"over_2_5": 0.5955,
"under_2_5": 0.4045
},
"status": "scheduled",
"pick": {
"outcome": "home",
"probability": 0.6624
}
}
]
}Utiliza este endpoint si necesitas el flujo diario completo en lugar de solo los picks.
GET /v1/leaguesX-API-Key requerido
Devuelve los códigos de ligas disponibles y sus metadatos para los flujos enriquecidos de corto plazo.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/leaguesEjemplo de respuesta
{
"source": "Foresportia",
"data_version": "example",
"leagues": [
{
"code": "CHN",
"name": "Chinese Super League",
"country": "China",
"available": true,
"matches_available": 24
},
{
"code": "NOR",
"name": "Eliteserien",
"country": "Norway",
"available": true,
"matches_available": 8
}
]
}Utiliza estos códigos en `/v1/leagues/{league_code}/matches`.
GET /v1/leagues/{league_code}/matchesX-API-Key requerido
Devuelve un flujo corto limitado por liga. Este endpoint admite ventanas futuras, pasadas recientes o mixtas.
curl
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.foresportia.com/v1/leagues/CHN/matches?include=all&days=14&limit=20"Ejemplo de respuesta
{
"league": {
"code": "CHN",
"name": "Chinese Super League",
"country": "China"
},
"date_range": {
"start": "2026-05-20",
"end": "2026-06-02",
"include": "all"
},
"timezone": "Europe/Paris",
"source": "Foresportia",
"data_version": "example",
"matches": [
{
"id": "43636da1c3e70181",
"kickoff": "2026-05-20T13:35:00Z",
"kickoff_local": "2026-05-20T15:35:00+02:00",
"league": {
"code": "CHN",
"name": "Chinese Super League",
"country": "China"
},
"home_team": "Shanghai Shenhua",
"away_team": "Wuhan Three Towns",
"probabilities": {
"home": 0.6624,
"draw": 0.2206,
"away": 0.117
},
"confidence": {
"badge": "correct",
"label": "Correct",
"score": 0.73624
},
"markets": {
"btts": 0.5425,
"over_1_5": 0.9352,
"over_2_5": 0.5955,
"over_3_5": 0.6444,
"under_1_5": 0.0648,
"under_2_5": 0.4045,
"under_3_5": 0.3556,
"dnb_home": 0.8499,
"dnb_away": 0.1501,
"double_chance_1x": 0.883,
"double_chance_x2": 0.3376,
"double_chance_12": 0.7794
},
"ranking": {
"home_rank": 9,
"away_rank": 15,
"home_context_rank": 3,
"away_context_rank": 14,
"source": "api_standings",
"is_reliable": true
},
"status": "scheduled",
"pick": {
"outcome": "home",
"probability": 0.6624
}
}
]
}No es una exportación histórica completa. Los partidos pasados aquí se limitan a las líneas recientes presentes en los archivos enriquecidos por liga.
Campos comunes de respuesta
| probabilities.home/draw/away | Probabilidades 1X2 en formato ratio 0..1. |
|---|---|
| markets.* | Probabilidades de los mercados en formato ratio 0..1. |
| kickoff | Fecha/hora ISO-8601 en UTC. |
| kickoff_local | Fecha/hora convertida a la zona horaria de la API, actualmente Europe/Paris. |
| confidence.badge | Valor técnico: `ultra_stable`, `stable`, `correct` o `risk`. |
| confidence.label | Etiqueta legible como `Very stable`, `Stable`, `Correct` o `Risk`. |
| pick.outcome | Predicción 1X2: `home`, `draw` o `away`. |
| likely_scores.probability | Probabilidad estimada del marcador exacto cuando está disponible. |
| ranking | Incluido solo cuando el dato de clasificación está disponible y es suficientemente fiable para exponerse. |
Parámetros de partidos por liga
| include | `upcoming`, `past` o `all`. Valor por defecto: `upcoming`. |
|---|---|
| start | Fecha de inicio opcional en formato `YYYY-MM-DD`. |
| days | Tamaño de la ventana desde `start`, entre 1 y 31 días. |
| limit | Número máximo de líneas devueltas, entre 1 y 500. |
`upcoming` devuelve únicamente partidos futuros. `past` devuelve los partidos pasados recientes disponibles en los archivos enriquecidos de corto plazo. `all` devuelve partidos pasados y futuros dentro de la ventana seleccionada. No es una exportación histórica completa.
Formato de los datos
Probabilidades
Las probabilidades están en formato 0..1. Ejemplo: `0.7445` significa `74,45 %`.
Horarios
`kickoff` está en UTC. `kickoff_local` se convierte a la zona horaria de la API, actualmente Europe/Paris.
Badges
`ultra_stable`, `stable`, `correct`, `risk` son los valores técnicos.
Etiquetas
`Very stable`, `Stable`, `Correct`, `Risk` se proporcionan en `confidence.label`.
Autenticación y límites
Utiliza el encabezado `X-API-Key`. Las claves API son privadas y no deben exponerse en código frontend público ni en repositorios GitHub. Llama a la API desde un backend, un script, un bot o un entorno privado.
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.foresportia.com/v1/picks/todaybeta_free
100 peticiones/día, 2000 peticiones/mes, 10 peticiones/minuto.
Límites evolutivos
Las cuotas de la beta privada pueden evolucionar según los usos observados.
Líneas monitorizadas
Las líneas devueltas también se siguen internamente.
Gestión de errores
Todos los endpoints devuelven códigos HTTP estándar. Los errores se devuelven en JSON con un campo message corto.
| 200 OK | Petición procesada correctamente. |
|---|---|
| 400 Bad Request | Parámetro inválido (por ejemplo league_code desconocido, days/limit fuera de límites). |
| 401 Unauthorized | Encabezado X-API-Key ausente o inválido. |
| 403 Forbidden | Clave no autorizada para este endpoint o acceso beta aún no activado. |
| 404 Not Found | Recurso no encontrado (por ejemplo código de liga desconocido). |
| 429 Too Many Requests | Límite por minuto, diario o mensual superado. Reintentar después de la ventana. |
| 5xx Server Error | Error backend temporal. Reintentar con backoff exponencial. |
Los códigos 5xx deben tratarse como transitorios del lado cliente, no como errores definitivos.
Prompt para copiar en ChatGPT, Claude u otra IA
Utiliza este prompt para pedir ayuda a una IA para integrar la API. Si tu asistente IA tiene acceso a la web, puede leer esta página. No pegues tu clave API real salvo en un entorno privado que aceptes usar con la herramienta IA; si no, mantenla en una variable de entorno.
Consejo: sustituye únicamente el lenguaje deseado. Para un uso real, almacena la clave en `FORES_API_KEY` del lado servidor o en un entorno local privado.
Dashboard API conectado
La gestión del uso, de las claves activas y de la rotación está ahora separada de esta documentación pública.
¿Ya tienes acceso a la API? Abre el dashboard API
Abrir el dashboard API
Inicio de sesión sin contraseña por email y código temporal. Las claves existentes nunca se muestran en claro.
Solicitar acceso beta
El formulario beta está disponible en la página de acceso a la API. Las solicitudes se revisan manualmente. También puedes escribir a contact@foresportia.com con una breve descripción de tu proyecto.
Solicitar acceso beta
No se añade ningún nuevo endpoint backend de formulario en esta página.