Managing the Consensus Threshold

The Holiday Oracle API's default setting is to return all winning holiday rules with a consensus score of greater than 0.5 (as there was more agreement in the underlying data, than not).

However, as a developer you can control the level of consensus in the dates you wish to use. The API will transparently expose to you a score which is a measure of the degree of consensus in the holiday rule and its dates. It is a configurable API parameter.

You decide. You are in control.

Score Closer to 0 Score > 0.5 Score Closer to 1
What do you get

More Dates, Less Certainty

If you lower the threshold, more holidays will be returned.

Consensus of open data

Less Dates, More Certainty

If you increase the threshold, less holidays will be returned.

When to use

If your software project requires you to locate a wider set of possible holidays.

You have a higher tolerance for false positives.

The default setting with more projects predicting the holiday than not.

If your software project requires you to use holidays with a higher level of consensus.

You have a higher tolerance for false negatives.

Outcome The lack of consensus in the underlying data might be due to certain holidays being regionally celebrated (ie, only in some cities), only celebrated for part days or by a certain section of the population (eg, government employees only), or even due to underlying open data errors or omissions, however you will see all holidays that exceed the threshold. This will be suitable for some uses cases, and not others. Mid-ground with more projects predicting the holiday than not. The holidays you use in your software project have a higher level of consensus in the underlying open data. You won’t get the holidays with a lower level of agreement. This will be suitable for some use cases, and not others.