Eventos

Endpoint unificado para listar y buscar eventos con filtrado, paginación y búsqueda.


GET /api/v1/events

Este endpoint sustituye a los anteriores /schedule, /events/live y /events/search. Toda la funcionalidad de esos endpoints está ahora disponible aquí mediante parámetros de consulta. Consulta las Notas de migración más abajo.

Autenticación

Requiere una API key mediante la cabecera X-API-Key, la cabecera Authorization: Bearer o el parámetro de consulta api_key. Disponible para todos los planes.

Parámetros de consulta

Parámetro	Tipo	Por defecto	Descripción
`sport`	string	todos	Filtra por deporte. Separados por comas para varios (p. ej., `basketball,football`)
`league`	string	todas	Filtra por liga. Separadas por comas para varias (p. ej., `nba,nfl`)
`sportsbook`	string	todas	Filtra por casa de apuestas (p. ej., `draftkings,pinnacle`)
`live`	boolean	—	`true` = solo en directo, `false` = solo previos al partido, omitir = ambos
`has_score`	boolean	—	`true` = solo eventos con estado de partido en directo o marcadores
`date`	string	—	Filtra por fecha en formato `YYYY-MM-DD`
`team`	string	—	Filtra por nombre de equipo (coincidencia parcial, sin distinguir mayúsculas, admite alias como `lakers`)
`q`	string	—	Consulta de búsqueda que coincide con nombres de equipos o de eventos
`limit`	integer	50	Resultados por página (máx. 200)
`offset`	integer	0	Desplazamiento de paginación (máx. 5000)

Los parámetros de consulta utilizan la forma singular y valores separados por comas para múltiples elementos: sport=basketball,football, no sports=basketball&sports=football.

Cabeceras de respuesta

Todas las respuestas incluyen cabeceras estándar de límite de peticiones (rate limit) y de metadatos:

Cabecera	Descripción
`X-RateLimit-Limit`	Máximo de peticiones por minuto para tu plan
`X-RateLimit-Remaining`	Peticiones restantes en la ventana actual
`X-RateLimit-Reset`	Marca de tiempo Unix de cuándo se reinicia la ventana del rate limit
`X-Data-Delay`	Retardo de los datos para tu plan (p. ej., `0s`, `60s`)
`X-Request-Id`	Identificador único de la petición para depuración

Objeto Event

Campo	Tipo	Descripción
`id`	string	Identificador canónico del evento — el mismo para cada casa de apuestas que cubra este evento. Úsalo como clave primaria para emparejamientos entre casas. Consulta Emparejamiento de eventos.
`external_ids`	object	Mapa del ID de la casa de apuestas al ID nativo del evento de esa casa (p. ej., `{"draftkings": "33483153"}`). Úsalos para enlaces directos a las páginas de las casas de apuestas.
`sport`	string	Identificador del deporte (p. ej., `basketball`, `football`)
`league`	string	Slug de la liga (p. ej., `nba`, `nfl`)
`home_team`	string	Nombre del equipo local
`away_team`	string	Nombre del equipo visitante
`start_time`	string	Hora de inicio del evento en ISO 8601
`status`	string	Estado del evento: `upcoming` o `live`
`is_live`	boolean	Indica si el evento está en directo en este momento
`book_count`	integer	Número de casas de apuestas con cuotas para este evento
`markets`	string[]	Array ordenado de los tipos de mercado disponibles (p. ej., `["moneyline", "point_spread", "total_points"]`)
`books`	string[]	Array ordenado de los IDs de las casas de apuestas con cuotas para este evento
`game_state`	object \| undefined	Estado del partido en directo (solo presente para eventos en directo con marcadores)

Objeto Game State

Se incluye cuando el evento está en directo y dispone de datos de marcador:

Campo	Tipo	Descripción
`home_score`	number	Marcador del equipo local
`away_score`	number \| null	Marcador del equipo visitante
`period`	string \| null	Periodo actual (p. ej., `Q3`, `2nd`, `3rd Period`)
`clock`	string \| null	Tiempo restante (p. ej., `5:42`)
`score_type`	string	Tipo de marcador (p. ej., `game_points`, `match`)
`possession`	string \| null	Equipo en posesión (`home` o `away`)
`is_timeout`	boolean \| null	Indica si hay un tiempo muerto en curso
`power_play`	string \| null	Información de superioridad numérica (`home` o `away`, hockey)
`last_play`	string \| null	Descripción de la última jugada

Ejemplos de peticiones

Listar próximos eventos de NBA y NFL

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();
console.log(`Found ${meta.total} events, showing ${meta.count}`);

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'sport': 'basketball,football',
        'league': 'nba,nfl',
        'limit': 20
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()
print(f"Found {data['meta']['total']} events")

Obtener solo eventos en directo

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?live=true',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(`${data.length} live events`);

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'live': 'true'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
live_events = response.json()['data']

Buscar un equipo

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?q=celtics',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'q': 'celtics'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
results = response.json()['data']

Filtrar por fecha y casa de apuestas

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'date': '2026-02-08',
        'sportsbook': 'draftkings,fanduel'
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()

Respuesta

Éxito (200)


{
  "data": [
    {
      "id": "evt_nba_bos_lal_20260208",
      "external_ids": {
        "draftkings": "33483200",
        "fanduel": "nba-bos-lal-20260208"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Boston Celtics",
      "away_team": "Los Angeles Lakers",
      "start_time": "2026-02-08T19:30:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 6,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "caesars", "draftkings", "fanduel"]
    },
    {
      "id": "evt_nba_gsw_mia_20260208",
      "external_ids": {
        "draftkings": "33483205"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Golden State Warriors",
      "away_team": "Miami Heat",
      "start_time": "2026-02-08T22:00:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 5,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "draftkings", "fanduel"]
    }
  ],
  "meta": {
    "count": 2,
    "total": 43,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50
    },
    "updated_at": "2026-02-08T12:00:00Z",
    "filters": {
      "sport": ["basketball"],
      "league": ["nba"]
    }
  }
}

Respuestas de error

401 Unauthorized


{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "docs": "https://docs.sharpapi.io/en/authentication"
  }
}

400 Bad Request


{
  "error": {
    "code": "validation_error",
    "message": "Invalid date format. Use YYYY-MM-DD.",
    "docs": "https://docs.sharpapi.io/en/api-reference/events"
  }
}

429 Rate Limited


{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Upgrade your tier for higher limits.",
    "docs": "https://docs.sharpapi.io/en/pricing"
  }
}

Migración desde endpoints anteriores

Varias subrutas de eventos heredadas de versiones anteriores de la API se mantienen como señalizaciones de obsolescencia: al invocarlas se devuelve 410 Gone con una pista legible por máquina que apunta al endpoint correcto.

Ruta obsoleta	Usa en su lugar
`GET /events/search?q=celtics`	`GET /events?q=celtics`
`GET /events/list`	`GET /events`
`GET /events/all`	`GET /events`
`GET /events/find`	`GET /events`

Estructura de la respuesta 410


{
  "error": {
    "code": "unknown_endpoint",
    "message": "There is no /api/v1/events/search endpoint. Use GET /api/v1/events — results can be filtered with ?sport=, ?league=, and ?book= query parameters.",
    "correct_endpoint": "/api/v1/events",
    "docs": "https://docs.sharpapi.io/api-reference"
  }
}

Las respuestas previas a la v1 utilizaban nombres de campo en camelCase (homeTeam, awayTeam, isLive, bookCount). La API v1 usa snake_case exclusivamente (home_team, away_team, is_live, book_count). Actualiza el código de tu cliente en consecuencia.

Cambios principales respecto a versiones anteriores

Los nombres de los campos están ahora en snake_case (p. ej., home_team en lugar de homeTeam)
La respuesta utiliza el sobre estándar data/meta en lugar de un array events en el nivel superior
Los parámetros de consulta usan la forma singular (sport en lugar de sports)
La URL base es https://api.sharpapi.io (no https://sharpapi.io)
La paginación incluye ahora los campos has_more y next_offset

Emparejamiento de eventos entre casas

El campo id es un identificador canónico de evento: el mismo evento del mundo real recibe el mismo id independientemente de la casa de apuestas de la que provenga. Úsalo como clave primaria al construir herramientas de comparación entre casas. El campo external_ids mapea cada casa de apuestas con su ID nativo del evento para enlaces directos.

Consulta Emparejamiento de eventos para conocer todos los detalles sobre cómo funcionan los IDs canónicos.

Endpoints relacionados

Detalles del evento - Obtener todos los detalles de un único evento
Cuotas del evento - Obtener todas las cuotas de un evento concreto
Mercados del evento - Obtener los mercados disponibles para un evento
Snapshot de cuotas - Obtener las cuotas actuales en todos los eventos