Documentación de la API v1

La Historia River API

API para consultar información histórica y deportiva de River Plate.

Base URLhttps://api.lahistoriariver.com/api/v1

Autenticación

Header x-api-key

Todos los endpoints de /api/v1 requieren una API key privada en el header x-api-key.

No la envíes como query param y no la publiques en frontend. Usala desde tu backend o desde procesos server-to-server.

curl "https://api.lahistoriariver.com/api/v1/partidos?anio=2025&orden=asc&pageSize=1" \
  -H "x-api-key: TU_API_KEY"

Respuestas

Formato de salida

{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  }
}

{
  "data": {}
}

Los listados devuelven data y meta. Los detalles devuelven el recurso envuelto en data.

Paginación

Valores reales

Parámetro	Tipo	Descripción
`page`	number	Valor por defecto: 1. Debe ser mayor o igual a 1.
`pageSize`	number	Valor por defecto: 20. Máximo: 100.
`total`	number	Cantidad total de registros que cumplen los filtros.
`totalPages`	number	Cantidad de páginas calculada con total y pageSize.

Filtros

Convenciones generales

Las fechas de query usan formato YYYY-MM-DD.

Los años usan cuatro dígitos y, en partidos, deben estar entre 1901 y 2100.

Los filtros por entidades relacionadas usan slugs cuando el endpoint los acepta.

La búsqueda textual se aplica con coincidencia parcial e insensible a mayúsculas/minúsculas.

También intenta coincidir con el slug normalizado, por lo que términos simples pueden encontrarse aunque se omitan acentos.

En búsquedas de varias palabras, el fallback por slug requiere una coincidencia continua dentro del slug.

En partidos, orden acepta únicamente asc o desc; el valor por defecto es desc.

anio no puede combinarse con desde o hasta.

Los campos sin dato disponible pueden devolverse como null.

API v1

Endpoints disponibles

GET/api/v1/partidosGET/api/v1/partidos/{slug}GET/api/v1/jugadoresGET/api/v1/jugadores/{slug}GET/api/v1/equiposGET/api/v1/equipos/{slug}GET/api/v1/estadiosGET/api/v1/titulosGET/api/v1/proximos-partidos

GET/api/v1/partidos

Lista partidos oficiales con filtros por equipo, competencia, temporada, condición, estadio, árbitro y fechas.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`equipo`	string	Slug de equipo local o visitante.
`competencia`	string	Slug de competencia.
`temporada`	string	Temporada exacta.
`condicion`	string	Condición exacta registrada para el partido.
`estadio`	string	Slug de estadio.
`arbitro`	string	Slug de árbitro.
`desde`	date	Fecha inicial en formato YYYY-MM-DD.
`hasta`	date	Fecha final en formato YYYY-MM-DD.
`anio`	number	Año entre 1901 y 2100. No se combina con desde/hasta.
`orden`	enum	asc o desc. Valor por defecto: desc.

Ejemplo/api/v1/partidos?anio=2025&orden=asc&pageSize=1

Respuesta

Listado paginado de partidos.

GET/api/v1/partidos/{slug}

Devuelve el detalle de un partido oficial, incluyendo eventos.

Parámetros

Parámetro	Tipo	Descripción
`slug`	string	Identificador público de la entidad en la ruta.

Ejemplo/api/v1/partidos/platense-vs-river-plate-liga-profesional-argentina-26-01-2025

Respuesta

Detalle envuelto en data.

GET/api/v1/jugadores

Lista jugadores con búsqueda textual y filtro por nacionalidad.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`busqueda`	string	Busca en nombre completo, nombre conocido y apodo.
`q`	string	Alias de busqueda.
`nacionalidad`	string	Búsqueda textual sobre nacionalidad.

Ejemplo/api/v1/jugadores?busqueda=alonso&pageSize=10

Respuesta

Listado paginado de jugadores.

GET/api/v1/jugadores/{slug}

Devuelve un jugador por slug.

Parámetros

Parámetro	Tipo	Descripción
`slug`	string	Identificador público de la entidad en la ruta.

Ejemplo/api/v1/jugadores/norberto-alonso

Respuesta

Detalle envuelto en data.

GET/api/v1/equipos

Lista equipos y permite buscar por nombre o nombre corto.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`busqueda`	string	Busca en nombre y nombre corto.

Ejemplo/api/v1/equipos?busqueda=river&pageSize=10

Respuesta

Listado paginado de equipos.

GET/api/v1/equipos/{slug}

Devuelve un equipo por slug.

Parámetros

Parámetro	Tipo	Descripción
`slug`	string	Identificador público de la entidad en la ruta.

Ejemplo/api/v1/equipos/river-plate

Respuesta

Detalle envuelto en data.

GET/api/v1/estadios

Lista estadios con búsqueda textual y filtro por equipo asociado.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`busqueda`	string	Busca en nombre y ubicación.
`equipo`	string	Slug de equipo asociado al estadio.

Ejemplo/api/v1/estadios?equipo=river-plate&pageSize=10

Respuesta

Listado paginado de estadios.

GET/api/v1/titulos

Lista títulos con competencia, partido definitorio y entrenador cuando existen.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`competencia`	string	Slug de competencia.
`temporada`	string	Temporada exacta.
`entrenador`	string	Slug o búsqueda textual por nombre de entrenador.

Ejemplo/api/v1/titulos?temporada=2024&pageSize=1

Respuesta

Listado paginado de títulos.

GET/api/v1/proximos-partidos

Lista próximos partidos desde una fecha inicial, con filtros por equipo, competencia y temporada.

Parámetros

Parámetro	Tipo	Descripción
`page`	number	Página solicitada. Valor por defecto: 1.
`pageSize`	number	Cantidad por página. Valor por defecto: 20. Máximo: 100.
`equipo`	string	Slug de equipo local o visitante.
`competencia`	string	Slug de competencia.
`temporada`	string	Temporada exacta.
`desde`	date	Fecha inicial en formato YYYY-MM-DD. Si no se envía, usa la fecha actual.
`hasta`	date	Fecha final en formato YYYY-MM-DD.

Ejemplo/api/v1/proximos-partidos?desde=2026-08-01&pageSize=1

Respuesta

Listado paginado de próximos partidos.

Errores

Códigos HTTP

Parámetro	Tipo	Descripción
`400`	Bad Request	Parámetros de query o ruta inválidos.
`401`	Unauthorized	API key ausente o inválida.
`403`	Forbidden	API key desactivada.
`404`	Not Found	Recurso de detalle no encontrado.
`429`	Too Many Requests	Rate limit excedido.
`500`	Internal Server Error	Error interno no controlado.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Debés enviar una API key en el header x-api-key."
  }
}

Rate limit

Límites por API key

Cada API key tiene un límite de solicitudes configurado. Al superarlo, la API responde con HTTP 429.

En esa respuesta se incluyen los headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Ejemplo exitoso

Partido oficial paginado

curl "https://api.lahistoriariver.com/api/v1/partidos?anio=2025&orden=asc&pageSize=1" \
  -H "x-api-key: TU_API_KEY"

{
  "data": [
    {
      "id": 6243,
      "fecha": "2025-01-25T19:30:00.000Z",
      "fase": "Fecha 1",
      "competencia": {
        "id": 45,
        "nombre": "Liga Profesional",
        "tipo": "Liga",
        "slug": "liga-profesional"
      },
      "equipoLocal": {
        "id": 76,
        "nombre": "Platense",
        "escudo": "platense.png",
        "slug": "platense"
      },
      "equipoVisitante": {
        "id": 1,
        "nombre": "River Plate",
        "escudo": "river-plate.png",
        "slug": "river-plate"
      },
      "golesLocal": 1,
      "golesVisitante": 1,
      "estadio": {
        "id": 120,
        "nombre": "Ciudad de Vicente López",
        "slug": "estadio-ciudad-de-vicente-lopez"
      },
      "slug": "platense-vs-river-plate-liga-profesional-argentina-26-01-2025"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 1,
    "total": 54,
    "totalPages": 54
  }
}

Acceso

Solicitar acceso

Contanos sobre tu proyecto y qué información necesitás.

Emailinfo@lahistoriariver.com Instagram@lahistoriariver X@lahistoriariver WhatsAppAbrir chat