https://github.com/westy92/holiday-event-api-python
The Official Holiday and Event API for Python
https://github.com/westy92/holiday-event-api-python
api calendar celebration checkiday date day event federal free holiday holidays list month occurrence official public python python3 unofficial year
Last synced: 3 months ago
JSON representation
The Official Holiday and Event API for Python
- Host: GitHub
- URL: https://github.com/westy92/holiday-event-api-python
- Owner: westy92
- License: mit
- Created: 2022-12-08T02:42:30.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-21T22:42:27.000Z (over 1 year ago)
- Last Synced: 2025-07-07T02:42:49.472Z (3 months ago)
- Topics: api, calendar, celebration, checkiday, date, day, event, federal, free, holiday, holidays, list, month, occurrence, official, public, python, python3, unofficial, year
- Language: Python
- Homepage: https://pypi.org/project/holiday-event-api/
- Size: 32.2 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The Official Holiday and Event API for Python
[](https://pypi.org/project/holiday-event-api)
[](https://pypi.org/project/holiday-event-api)
[](https://github.com/westy92/holiday-event-api-python/actions)
[](https://codecov.io/gh/westy92/holiday-event-api-python)
[](https://snyk.io/test/github/westy92/holiday-event-api-python)
[](https://github.com/sponsors/westy92)
Industry-leading Holiday and Event API for Python. Over 5,000 holidays and thousands of descriptions. Trusted by the World’s leading companies. Built by developers for developers since 2011.
## Supported Python Versions
Latest version of the the Holiday and Event API supports all actively-maintained Python [releases](https://devguide.python.org/versions/) and might work with older versions. It also supports PyPy.
## Authentication
Access to the Holiday and Event API requires an API Key. You can get for one for FREE [here](https://apilayer.com/marketplace/checkiday-api#pricing), no credit card required! Note that free plans are limited. To access more data and have more requests, a paid plan is required.
## Installation
The Holiday and Event API is available on PyPI:
```console
$ python -m pip install holiday-event-api
```
## Example
```python
import holidays
try:
# Get a FREE API key from https://apilayer.com/marketplace/checkiday-api#pricing
client = holidays.client('')
# Get Events for a given Date
events = client.getEvents(
# These parameters are the defaults but can be specified:
# date='today',
# timezone='America/Chicago',
# adult=False,
)
event = events.events[0]
print(f"Today is {event.name}! Find more information at: {event.url}.")
print(f"Rate limits remaining: {events.rateLimit.remainingMonth}/{events.rateLimit.limitMonth} (month).")
# Get Event Information
eventInfo = client.getEventInfo(
id=event.id,
# These parameters can be specified to calculate the range of eventInfo.Event.Occurrences
# start=2020,
# end=2030,
)
print(f"The Event's hashtags are {eventInfo.event.hashtags}.")
# Search for Events
query = "pizza day"
search = client.search(
query=query,
# These parameters are the defaults but can be specified:
# adult=False,
)
print(f"Found {len(search.events)} events, including {search.events[0].name}, that match the query '{query}'.")
except Exception as e:
print(f"There was an error: {e}")
```