Documentation

API Key

An API key is required for every request to the Festivo. Your API key is used to authenticate you with our API, and it should be provided as a api_key URL parameter. The API key can be retrieved from the dashboard page.

If you don't have an account yet, you can sign up for free!

Authentication

Once you have your API Key, you should append it to your GET query, as per example:

                    
    $ curl -G
    -d api_key="[ YOUR API KEY HERE]"
    -d country="US"
    -d year="2019"

    "https://getfestivo.com/v1/holidays"
                    
                

In other words, you need to make a simple GET request to https://getfestivo.com/v1/holidays, so in this case:

                    
https://getfestivo.com/v1/holidays?api_key=[ YOUR API KEY HERE]&country=US&year=2019
                    
                

Have a look at extra filters that may help you to get exactly the data you need.

Rate Limiting

Methods

The Festivo is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We enforce using SSL encryption by issuing requests through HTTPS.

Check out possible API Responses. Remember you are obligated to collect full responses in order to report bugs and issues.

Responses

Festivo follows standard HTTP response codes best practices in the industry. Each response comes with an appropriate response status code:

Standard request response

Below is an example status 200 standard response returned by our API:

                    
{
  "status": 200,
  "message": "",
  "errors": null,
  "envelope": {
    "api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "remote_ip": "127.0.0.1",
    "request_url": "https://getfestivo.com/v1/holidays?api_key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&country=US&month=12&year=2017",
    "signature": "2a371752bdc521f0743ea403dd880ef9"
  },
  "holidays": {
    "holidays": {
      "2017-12-07": [
        [
          {
            "name": "Pearl Harbor Remembrance Day",
            "country": "US",
            "date": "2017-12-07",
            "public": null
          }
        ]
      ],
      ...
      "2017-12-31": [
        [
          {
            "name": "New Year's Eve",
            "country": "US",
            "date": "2017-12-31",
            "public": null
          },
          {
            "name": "Sixth Day of Kwanzaa",
            "country": "US",
            "date": "2017-12-31",
            "public": null
          }
        ]
      ]
    }
  }
}
                    
                

Request using day parameter response

Below is an example status 200 response returned by our API to a single day request:

                    
    {
      "status": 200,
      "message": "",
      "errors": null,
      "envelope": {
        "api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "remote_ip": "127.0.0.1",
        "request_url": "https://getfestivo.com/v1/holidays?api_key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&country=US&day=25&month=12&year=2017",
        "signature": "d0a855a9cae7ef063b1b545fd98fb6ef"
      },
      "holidays": {
        "holidays": [
          {
            "name": "Christmas",
            "country": "US",
            "date": "2017-12-25",
            "public": null
          }
        ]
      }
    }
                    
                

Available Countries

Officially, are currently supporting 144 countries and constantly adding more. Another 70 countries are available to our chosen customers on a beta test basis.

If you would like to help adding your country's holidays to expand the service, please do not hesitate to contact us. To all collaborates we're offering a lifetime Premium Plan.

Holiday Types

Following launch of Festivo v.1.1 we've extended returned data by field type that contains exact holiday type indicator (in opposition to public field which indicates only if given holiday is public or not)

Filters

After Authentication' section api_key parameter in your GET query, you are able to append more parameters. Some of them are required some of them are optional, but each of them alter received list of holidays a bit. Please make yourself comfortable with the list below before you start using our API.

SDKs

If you'd like to participate in development of new SDKs or you have already made a wrapper in your favourite language, please do let us know. We offer free Premium Plan subscription to authors of all verified SDKs.

Support

We are here to assist you, thank you for report any bug/issue to our email [email protected].

What support includes?

1. Availability to answer questions
2. Answering technical questions about plan's features
3. Assistance with reported bugs and issues
4. Help with payments and subscription troubleshooting

What support doesn't include:

1. Customization services
2. Installation services

If you already read the documentation and you still need assistance, please send us an email to [email protected] or contact us via any other support channel available in your plan and we'll be glad to help you.