Developer API Pro Only

Welcome to the Madridonomy Public API. Our REST API provides access to real-time data on Real Madrid players, match history, standings, and historical records.

Access to the Public API is restricted to users on the Pro Membership tier. You can manage your API keys in your Account Dashboard.

Authentication

Authenticate your requests by passing your API key in the Authorization header or as a query parameter.

Option 1: Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

Option 2: Query Parameter

GET /api/v1/players?api_key=YOUR_API_KEY

Rate Limits

Pro tier users are limited to 1,000 requests per day. Limits are tracked per API key and reset at 00:00 UTC daily.

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed per day.
X-RateLimit-Remaining	The number of requests remaining in the current day.
Retry-After	Sent with HTTP 429 responses, indicating seconds until reset.

Response Format

All successful responses follow this JSON structure:

{
  "data": { ... },
  "meta": {
    "generated_at": "2024-03-29T21:05:00Z",
    "page": 1,
    "per_page": 20,
    "total": 450
  }
}

Players

GET /api/v1/players

List all players with optional filtering and pagination.

Param	Type	Description
active	bool	Filter by current squad status (true/false).
position	string	Filter by position (GK, DEF, MID, FWD).
limit	int	Results per page (default 20, max 100).

GET /api/v1/players/:slug

Get detailed profile for a specific player by their slug (e.g. jude-bellingham).

Matches

GET /api/v1/matches

List match history with filters for competition and result.

competition	LaLiga \| UCL \| Copa \| Supercopa
result	W \| D \| L
season	Label (e.g. 2023-24)

Standings

GET /api/v1/standings

Get the live La Liga table (cached hourly).

Club Records

GET /api/v1/records

Get historical club milestones including top scorers, most appearances, and biggest victories.

Quick Start Examples

Python

import requests

url = "https://madridonomy.com/api/v1/players"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()

for player in data['data']:
    print(f"{player['name']} - {player['position']}")

JavaScript

const response = await fetch('https://madridonomy.com/api/v1/matches', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data);