Quick Start Guide

Get up and running with the Festivo API in minutes.

Step 1: Get Your API Key

1. Sign up for a free account (no credit card required)
2. Navigate to your dashboard
3. Find your API key in the "API Keys" section
4. Copy your key - you'll need it for authentication

Free tier includes:

• 100 requests per day
• Access to 250+ countries
• Historical and future data
• Community support

Step 2: Make Your First Request

Let's get city-level holidays for Milan, Italy - including local observances like the Feast of Saint Ambrose (December 7th):

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=IT&regions=IT-MILAN&year=2026&api_key=YOUR_API_KEY"

1{
2  "holidays": [
3    {
4      "date": "2026-01-01",
5      "name": "New Year's Day",
6      "name_local": "Capodanno",
7      "type": "public",
8      "observed": "2026-01-01",
9      "public": true,
10      "country": "IT",
11      "subdivisions": [
12        "IT-MILAN"
13      ],
14      "regions": [
15        {
16          "code": "IT-MILAN",
17          "type": "city"
18        }
19      ]
20    },
21    {
22      "date": "2026-12-07",
23      "name": "Feast of Saint Ambrose",
24      "name_local": "Sant'Ambrogio",
25      "type": "regional",
26      "observed": "2026-12-07",
27      "public": true,
28      "country": "IT",
29      "subdivisions": [
30        "IT-MILAN"
31      ],
32      "regions": [
33        {
34          "code": "IT-MILAN",
35          "type": "city"
36        }
37      ],
38      "description": "Patron saint of Milan"
39    }
40  ],
41  "total": 15
42}

Step 3: Understanding the Response

The API returns a JSON object with city-specific holidays, including the structured regions field:

{
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "name_local": "Capodanno",
      "type": "public",
      "observed": "2026-01-01",
      "public": true,
      "country": "IT",
      "subdivisions": ["IT-MILAN"],
      "regions": [
        {
          "code": "IT-MILAN",
          "type": "city"
        }
      ],
      "description": "First day of the Gregorian calendar year"
    },
    {
      "date": "2026-12-07",
      "name": "Feast of Saint Ambrose",
      "name_local": "Sant'Ambrogio",
      "type": "regional",
      "observed": "2026-12-07",
      "public": true,
      "country": "IT",
      "subdivisions": ["IT-MILAN"],
      "regions": [
        {
          "code": "IT-MILAN",
          "type": "city"
        }
      ],
      "description": "Patron saint of Milan, city-specific holiday"
    }
  ],
  "total": 15
}

Response Fields

• date: The actual date of the holiday (YYYY-MM-DD)
• name: Holiday name in English
• name_local: Holiday name in the local language
• type: Holiday type (public, bank, observance, regional, religious)
• observed: The date the holiday is observed (may differ if substitute)
• public: Whether it's a public holiday
• country: ISO country code
• subdivisions: Legacy field with subdivision codes
• regions: Structured array with code and type (city or region) for precise geographic classification
• description: Additional details about the holiday

Common Use Cases

Get city-specific holidays (Pro plan)

Query granular city-level holidays like patron saint days and local observances:

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=IT&regions=IT-ROME&year=2026&api_key=YOUR_API_KEY" 

Get holidays for a specific month

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=US&year=2026&month=12&api_key=YOUR_API_KEY" 

Get holidays for ISO-coded subdivisions (Builder plan)

Query holidays by ISO 3166-2 subdivision codes for precise regional data:

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=GB&year=2026&regions=GB-SCT&api_key=YOUR_API_KEY" 

Get holidays in a different language

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=DE&year=2026&language=en&api_key=YOUR_API_KEY" 

Check if a specific date is a holiday

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/check?country=US&date=2026-12-25&api_key=YOUR_API_KEY" 

1{
2  "is_holiday": true,
3  "holiday": {
4    "date": "2026-12-25",
5    "name": "Christmas Day",
6    "type": "public",
7    "observed": "2026-12-25",
8    "public": true
9  }
10}

Request Parameters

Required Parameters

• country: ISO 3166-1 alpha-2 country code (e.g., US, GB, DE)
• year: Four-digit year (e.g., 2026)

Optional Parameters

• month: Month number (1-12)
• day: Day of month (1-31)
• language: ISO 639-1 language code for holiday names (e.g., en, de, fr, es). Growth and above; see API reference.
• type: Filter by type (public, bank, observance, religious)
• subdivision: State/province code (e.g., CA for California, BY for Bavaria)

Best Practices

1. Cache Responses

Holiday data doesn't change frequently. Cache responses to reduce API calls:

// Simple in-memory cache
const cache = new Map();

async function getHolidays(country, year) {
  const cacheKey = `${country}-${year}`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const response = await fetch(
    `https://api.getfestivo.com/v3/public-holidays/list?country=${country}&year=${year}`,
    {
      headers: { "X-API-Key": process.env.FESTIVO_API_KEY },
    },
  );

  const data = await response.json();
  cache.set(cacheKey, data);

  return data;
}

2. Handle Errors Gracefully

async function getHolidays(country, year) {
  try {
    const response = await fetch(
      `https://api.getfestivo.com/v3/public-holidays/list?country=${country}&year=${year}`,
      {
        headers: { "X-API-Key": process.env.FESTIVO_API_KEY },
      },
    );

    if (response.status === 429) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error("Failed to fetch holidays:", error.message);
    throw error;
  }
}

3. Use Environment Variables

Never hardcode your API key:

# .env file
FESTIVO_API_KEY=your_api_key_here

// Access via environment variable
const apiKey = process.env.FESTIVO_API_KEY;

Rate Limits

Monitor your usage through response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

If you exceed your limit, you'll receive a 429 Too Many Requests response.

Next Steps

• View Full API Reference - Complete endpoint documentation
• Browse Code Examples - Practical examples in multiple languages
• Learn About Authentication - Security best practices
• Upgrade Your Plan - Increase your rate limits

Need Help?

• Help center (docs, billing shortcuts, status): app.getfestivo.com/help
• Email: hello@getfestivo.com

Rate Limits

• Free tier: 100 requests per month
• Pro tier: 100,000 requests per month
• Enterprise tier: Custom limits

Error Handling

The API uses standard HTTP status codes:

• 200 OK: Success
• 400 Bad Request: Invalid parameters
• 401 Unauthorized: Invalid or missing API key
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Support

For questions or issues:

• Email: support@getfestivo.com
• Documentation: https://getfestivo.com/docs
• Status: https://status.getfestivo.com