API REST para Festivos Públicos de España

BASE_URL="https://calendariofestivos.es/api"
API_KEY="your_api_key_here"

# Step 1 — search a municipality by name.
# --get plus --data-urlencode builds the query string and escapes it, so
# names with spaces or accents ("Sant Cugat del Vallès") work unchanged.
curl -s --get "$BASE_URL/v1/holidays/search_municipality" \
     --data-urlencode "search_municipality=Bilbao" \
     --data-urlencode "year=2026" \
     -H "X-API-Key: $API_KEY" | jq .

# Step 2 — keep the id of the best match. Results come back sorted by
# trigram_sim, so element 0 is the closest name.
ENTRY_ID=$(curl -s --get "$BASE_URL/v1/holidays/search_municipality" \
     --data-urlencode "search_municipality=Bilbao" \
     --data-urlencode "year=2026" \
     -H "X-API-Key: $API_KEY" | jq -r '.[0].id')

# Step 3 — every holiday that applies to that municipality, sorted by date.
curl -s "$BASE_URL/v1/holidays/$ENTRY_ID" \
     -H "X-API-Key: $API_KEY" \
     | jq -r '.[] | "\(.holiday_date)  \(.description)"'

import requests

BASE_URL = "https://calendariofestivos.es/api"
API_KEY  = "your_api_key_here"
SCOPES   = ["State", "Community", "Island", "Region", "Municipality"]

# A Session attaches the header once and reuses the TCP connection, which
# matters if you are going to look up more than one municipality.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})


def search_municipality(name, year):
    """Matches ordered by trigram_sim, best first. May be empty."""
    response = session.get(
        f"{BASE_URL}/v1/holidays/search_municipality",
        # requests percent-encodes params for you, so spaces and
        # accents in `name` are safe.
        params={"search_municipality": name, "year": year},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


def holidays_for(entry_id):
    """Every holiday applying to the municipality of `entry_id`, by date."""
    response = session.get(f"{BASE_URL}/v1/holidays/{entry_id}", timeout=10)
    response.raise_for_status()
    return response.json()


try:
    results = search_municipality("Bilbao", 2026)
except requests.HTTPError as error:
    # 401 means the header is missing, the key is unknown, or the
    # subscription behind it is no longer active.
    raise SystemExit(f"HTTP {error.response.status_code}: {error.response.text}")

if not results:
    raise SystemExit("No municipality matched that name for that year.")

best = results[0]
print(f"Found: {best['municipality']} ({best['province_name']}) — id {best['id']}")

for holiday in holidays_for(best["id"]):
    scope = SCOPES[holiday["date_type"]]
    print(f"{holiday['holiday_date']}  {holiday['description']}  [{scope}]")

// Run this on your server, not in the browser. The API answers with
// Access-Control-Allow-Origin: *, so a fetch from a web page would in fact
// succeed — and would hand your API key to everyone who visits the page.

const BASE_URL = "https://calendariofestivos.es/api";
const API_KEY = "your_api_key_here";
const SCOPES = ["State", "Community", "Island", "Region", "Municipality"];

async function apiGet(path, params) {
  // URLSearchParams percent-encodes for you, so a name with spaces or
  // accents survives the round trip untouched.
  const query = new URLSearchParams(params ?? {}).toString();
  const url = query ? `${BASE_URL}${path}?${query}` : `${BASE_URL}${path}`;

  const response = await fetch(url, { headers: { "X-API-Key": API_KEY } });
  if (!response.ok) {
    // 401 means the header is missing, the key is unknown, or the
    // subscription behind it is no longer active.
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return response.json();
}

// Step 1 — search. Results arrive sorted by trigram_sim, best match first.
const results = await apiGet("/v1/holidays/search_municipality", {
  search_municipality: "Bilbao",
  year: 2026,
});

if (results.length === 0) {
  throw new Error("No municipality matched that name for that year.");
}

const best = results[0];
console.log(`Found: ${best.municipality} (${best.province_name}) — id ${best.id}`);

// Step 2 — every holiday applying to that municipality, sorted by date.
const holidays = await apiGet(`/v1/holidays/${best.id}`);

for (const holiday of holidays) {
  const scope = SCOPES[holiday.date_type];
  console.log(`${holiday.holiday_date}  ${holiday.description}  [${scope}]`);
}

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class CalendarioExample {

    private static final String BASE_URL = "https://calendariofestivos.es/api";
    private static final String API_KEY  = "your_api_key_here";
    private static final String[] SCOPES =
            {"State", "Community", "Island", "Region", "Municipality"};

    private static final HttpClient CLIENT = HttpClient.newHttpClient();
    private static final ObjectMapper MAPPER = new ObjectMapper();

    /** GET the URL with the API key attached, failing loudly on any non-200. */
    private static JsonNode apiGet(String url) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("X-API-Key", API_KEY)
                .GET()
                .build();

        HttpResponse<String> response =
                CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            // 401 means the header is missing, the key is unknown, or the
            // subscription behind it is no longer active.
            throw new RuntimeException(
                    "HTTP " + response.statusCode() + ": " + response.body());
        }
        return MAPPER.readTree(response.body());
    }

    public static void main(String[] args) throws Exception {
        // Step 1 — search. URLEncoder keeps spaces and accents from
        // breaking the query string.
        String term = URLEncoder.encode("Bilbao", StandardCharsets.UTF_8);
        JsonNode results = apiGet(BASE_URL
                + "/v1/holidays/search_municipality"
                + "?search_municipality=" + term
                + "&year=2026");

        if (results.isEmpty()) {
            System.out.println("No municipality matched that name for that year.");
            return;
        }

        // Results arrive sorted by trigram_sim, so index 0 is the best match.
        JsonNode best = results.get(0);
        int entryId = best.get("id").asInt();
        System.out.printf("Found: %s (%s) — id %d%n",
                best.get("municipality").asText(),
                best.get("province_name").asText(),
                entryId);

        // Step 2 — every holiday applying to that municipality, sorted by date.
        JsonNode holidays = apiGet(BASE_URL + "/v1/holidays/" + entryId);

        for (JsonNode holiday : holidays) {
            System.out.printf("%s  %s  [%s]%n",
                    holiday.get("holiday_date").asText(),
                    holiday.get("description").asText(),
                    SCOPES[holiday.get("date_type").asInt()]);
        }
    }
}

use reqwest::header::{HeaderMap, HeaderValue};
use serde_json::Value;

const BASE_URL: &str = "https://calendariofestivos.es/api";
const API_KEY: &str = "your_api_key_here";
const SCOPES: [&str; 5] = ["State", "Community", "Island", "Region", "Municipality"];

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_str(API_KEY)?);
    let client = reqwest::Client::builder()
        .default_headers(headers)
        .build()?;

    // Step 1 — search. .query() percent-encodes, so a name with spaces
    // or accents survives the round trip untouched.
    let results: Value = client
        .get(format!("{BASE_URL}/v1/holidays/search_municipality"))
        .query(&[("search_municipality", "Bilbao"), ("year", "2026")])
        .send()
        .await?
        // 401 means the header is missing, the key is unknown, or the
        // subscription behind it is no longer active.
        .error_for_status()?
        .json()
        .await?;

    // Results arrive sorted by trigram_sim, so element 0 is the best match.
    let best = match results.as_array().and_then(|entries| entries.first()) {
        Some(entry) => entry,
        None => {
            println!("No municipality matched that name for that year.");
            return Ok(());
        }
    };

    let entry_id = best["id"].as_i64().unwrap_or_default();
    println!(
        "Found: {} ({}) — id {}",
        best["municipality"].as_str().unwrap_or_default(),
        best["province_name"].as_str().unwrap_or_default(),
        entry_id
    );

    // Step 2 — every holiday applying to that municipality, sorted by date.
    let holidays: Value = client
        .get(format!("{BASE_URL}/v1/holidays/{entry_id}"))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    // as_array() yields an Option; into_iter().flatten() walks it without
    // borrowing a temporary, and gives an empty run if the body is not a list.
    for holiday in holidays.as_array().into_iter().flatten() {
        let index = holiday["date_type"].as_u64().unwrap_or_default() as usize;
        let scope = SCOPES.get(index).copied().unwrap_or("Other");
        println!(
            "{}  {}  [{}]",
            holiday["holiday_date"].as_str().unwrap_or_default(),
            holiday["description"].as_str().unwrap_or_default(),
            scope
        );
    }

    Ok(())
}

#include <curl/curl.h>
#include <nlohmann/json.hpp>
#include <iostream>
#include <stdexcept>
#include <string>

using json = nlohmann::json;

static const std::string BASE_URL = "https://calendariofestivos.es/api";
static const std::string API_KEY  = "your_api_key_here";
static const char* SCOPES[] =
        {"State", "Community", "Island", "Region", "Municipality"};

static size_t write_cb(void* data, size_t size, size_t nmemb, std::string* out) {
    out->append(static_cast<char*>(data), size * nmemb);
    return size * nmemb;
}

// Percent-encode a query value so spaces and accents survive the URL.
static std::string url_encode(const std::string& value) {
    CURL* curl = curl_easy_init();
    char* escaped = curl_easy_escape(curl, value.c_str(), 0);
    std::string out = escaped ? escaped : "";
    curl_free(escaped);
    curl_easy_cleanup(curl);
    return out;
}

// GET the URL with the API key attached, throwing on transport or HTTP errors.
static json api_get(const std::string& url) {
    CURL* curl = curl_easy_init();
    if (!curl) throw std::runtime_error("curl_easy_init failed");

    std::string body;
    curl_slist* headers =
            curl_slist_append(nullptr, ("X-API-Key: " + API_KEY).c_str());

    curl_easy_setopt(curl, CURLOPT_URL,           url.c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER,    headers);
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb);
    curl_easy_setopt(curl, CURLOPT_WRITEDATA,     &body);

    CURLcode rc = curl_easy_perform(curl);
    long status = 0;
    curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &status);

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);

    if (rc != CURLE_OK) throw std::runtime_error(curl_easy_strerror(rc));
    // 401 means the header is missing, the key is unknown, or the
    // subscription behind it is no longer active.
    if (status != 200)
        throw std::runtime_error("HTTP " + std::to_string(status) + ": " + body);

    return json::parse(body);
}

// province_name and the other name fields are nullable in the schema, and
// nlohmann throws when you .get a string out of a null. Read them defensively.
static std::string str_or(const json& node, const char* key, const char* fallback) {
    return node.contains(key) && node[key].is_string()
            ? node[key].get<std::string>()
            : fallback;
}

int main() {
    curl_global_init(CURL_GLOBAL_DEFAULT);

    // Step 1 — search. Results arrive sorted by trigram_sim, best match first.
    json results = api_get(BASE_URL + "/v1/holidays/search_municipality"
                           + "?search_municipality=" + url_encode("Bilbao")
                           + "&year=2026");

    if (results.empty()) {
        std::cout << "No municipality matched that name for that year.\n";
        curl_global_cleanup();
        return 0;
    }

    const auto& best = results[0];
    int entry_id = best["id"].get<int>();
    std::cout << "Found: " << str_or(best, "municipality", "?")
              << " (" << str_or(best, "province_name", "?") << ")"
              << " - id " << entry_id << "\n";

    // Step 2 — every holiday applying to that municipality, sorted by date.
    json holidays = api_get(BASE_URL + "/v1/holidays/" + std::to_string(entry_id));

    for (const auto& holiday : holidays) {
        int type = holiday["date_type"].get<int>();
        const char* scope = (type >= 0 && type <= 4) ? SCOPES[type] : "Other";
        std::cout << str_or(holiday, "holiday_date", "?") << "  "
                  << str_or(holiday, "description", "?") << "  ["
                  << scope << "]\n";
    }

    curl_global_cleanup();
    return 0;
}