API Documentation

All endpoints require an X-API-Key header.

Base URL

https://madridweekend.com/api/v1

GET/activities

List all activities for the upcoming weekend. Supports filtering.

Query Parameters

Parameter	Type	Description
date	string	Filter by date (YYYY-MM-DD)
category	string	outdoor \| cultural \| shows \| events
source	string	madrid \| ticketmaster \| brave

Example

curl -H "X-API-Key: mw_live_abc123" \
  "https://madridweekend.com/api/v1/activities?category=outdoor"

Response

{
  "activities": [
    {
      "id": "1",
      "title": "Taller de huerto urbano",
      "description": "...",
      "url": "https://...",
      "affiliateUrl": "https://...?aid=XX",
      "location": "Parque del Retiro",
      "address": "Plaza de la Independencia",
      "date": "2026-03-28",
      "price": "Gratis",
      "source": "madrid",
      "category": "outdoor"
    }
  ],
  "total": 1,
  "generatedAt": "2026-03-25T07:00:00.000Z"
}

GET/activities/:id

Get a single activity by ID.

curl -H "X-API-Key: mw_live_abc123" \
  "https://madridweekend.com/api/v1/activities/1"

GET/weather

Weekend weather forecast for Madrid.

curl -H "X-API-Key: mw_live_abc123" \
  "https://madridweekend.com/api/v1/weather"

GET/usage

Check your current month's usage and estimated cost.

{
  "currentMonthUsage": 342,
  "estimatedCost": "€3.42",
  "status": "active",
  "usageResetDate": "2026-04-01",
  "lastUsedAt": "2026-03-25T14:30:00.000Z"
}

Response Headers

Header	Description
X-Usage-Count	Your current month's total API calls
X-Generated-At	When the activity data was last refreshed

Error Codes

Code	Meaning
401	Missing X-API-Key header
403	Invalid or suspended API key
404	Resource not found
429	Rate limit exceeded (60 req/min)

Code Examples

Python

import requests

headers = {"X-API-Key": "mw_live_your_key_here"}
r = requests.get(
    "https://madridweekend.com/api/v1/activities",
    params={"category": "outdoor"},
    headers=headers,
)
activities = r.json()["activities"]

JavaScript

const res = await fetch(
  "https://madridweekend.com/api/v1/activities?category=outdoor",
  { headers: { "X-API-Key": "mw_live_your_key_here" } }
);
const { activities } = await res.json();