holidays

README

The Official Holiday and Event API for Go

Industry-leading Holiday and Event API for Go. Over 5,000 holidays and thousands of descriptions. Trusted by the World’s leading companies. Built by developers for developers since 2011.

Supported Go Versions

Latest version of the the Holiday and Event API supports last two Go major releases and might work with older versions.

Authentication

Access to the Holiday and Event API requires an API Key. You can get for one for FREE here, no credit card required! Note that free plans are limited. To access more data and have more requests, a paid plan is required.

Installation

go get github.com/westy92/holiday-event-api-go

Example

import (
	"fmt"

	holidays "github.com/westy92/holiday-event-api-go"
)

func main() {
	// Get a FREE API key from https://apilayer.com/marketplace/checkiday-api#pricing
	client, err := holidays.New("<your API key>")

	if err != nil {
		fmt.Println(err)
		return
	}

	// Get Events for a given Date
	events, err := client.GetEvents(holidays.GetEventsRequest{
		// These parameters are the defaults but can be specified:
		// Date:     "today",
		// Timezone: "America/Chicago",
		// Adult:    false,
	})

	if err != nil {
		fmt.Println(err)
		return
	}

	event := events.Events[0]
	fmt.Printf("Today is %s! Find more information at: %s.\n", event.Name, event.Url)
	fmt.Printf("Rate limit remaining: %d/%d (month).\n", events.RateLimit.RemainingMonth, events.RateLimit.LimitMonth)

	// Get Event Information
	eventInfo, err := client.GetEventInfo(holidays.GetEventInfoRequest{
		Id: event.Id,
		// These parameters can be specified to calculate the range of eventInfo.Event.Occurrences
		// Start: 2020,
		// End: 2030,
	})

	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf("The Event's hashtags are %q.\n", eventInfo.Event.Hashtags)

	// Search for Events
	query := "pizza day"
	search, err := client.Search(holidays.SearchRequest{
		Query: query,
		// These parameters are the defaults but can be specified:
		// Adult: false,
	})

	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf("Found %d events, including %s, that match the query \"%s\".\n", len(search.Events), search.Events[0].Name, query)
}

Documentation

Index

• type AlternateName
• type Client
  • func New(apiKey string) (*Client, error)
  • func (c *Client) GetEventInfo(req GetEventInfoRequest) (*GetEventInfoResponse, error)
  • func (c *Client) GetEvents(req GetEventsRequest) (*GetEventsResponse, error)
  • func (c *Client) GetVersion() string
  • func (c *Client) Search(req SearchRequest) (*SearchResponse, error)
• type EventInfo
• type EventSummary
• type FounderInfo
• type GetEventInfoRequest
• type GetEventInfoResponse
• type GetEventsRequest
• type GetEventsResponse
• type ImageInfo
• type Occurrence
• type Pattern
• type RateLimit
• type RichText
• type SearchRequest
• type SearchResponse
• type StandardResponse
• type StandardResponseInterface

Types

type AlternateName

type AlternateName struct {
	Name      string `json:"name"`       // An Event's Alternate Name
	FirstYear int    `json:"first_year"` // The first year this Alternate Name was in effect (0 implies none or unknown)
	LastYear  int    `json:"last_year"`  // The last year this Alternate Name was in effect (0 implies none or unknown)
}

Information about an Event's Alternate Name

type Client

type Client struct {
	// contains filtered or unexported fields
}

The API Client

func New

func New(apiKey string) (*Client, error)

Creates a New Client using the provided API key. Get a FREE API key from https://apilayer.com/marketplace/checkiday-api#pricing

func (*Client) GetEventInfo

func (c *Client) GetEventInfo(req GetEventInfoRequest) (*GetEventInfoResponse, error)

Gets the Event Info for the provided Event

func (*Client) GetEvents

func (c *Client) GetEvents(req GetEventsRequest) (*GetEventsResponse, error)

Gets the Events for the provided Date

func (*Client) GetVersion

func (c *Client) GetVersion() string

Gets the API Client Version

func (*Client) Search

func (c *Client) Search(req SearchRequest) (*SearchResponse, error)

Searches for Events with the given criteria

type EventInfo

type EventInfo struct {
	EventSummary
	Adult          bool            `json:"adult"`           // Whether this Event is unsafe for children or viewing at work
	AlternateNames []AlternateName `json:"alternate_names"` // The Event's Alternate Names
	Hashtags       []string        `json:"hashtags"`        // The Event's hashtags
	Image          ImageInfo       `json:"image"`           // The Event's images
	Sources        []string        `json:"sources"`         // The Event's sources
	Description    RichText        `json:"description"`     // The Event's description
	HowToObserve   RichText        `json:"how_to_observe"`  // How to observe the Event
	Patterns       []Pattern       `json:"patterns"`        // Patterns defining when the Event is observed
	Occurrences    []Occurrence    `json:"occurrences"`     // The Event Occurrences (when it occurs)
	Founders       []FounderInfo   `json:"founders"`        // The Event's founders
}

Information about an Event

type EventSummary

type EventSummary struct {
	Id   string `json:"id"`   // The Event Id
	Name string `json:"name"` // The Event name
	Url  string `json:"url"`  // The Event URL
}

A summary of an Event

type FounderInfo

type FounderInfo struct {
	Name string `json:"name"` // The Founder's name
	Url  string `json:"url"`  // A link to the Founder
	Date string `json:"date"` // The date the Event was founded
}

Information about an Event Founder

type GetEventInfoRequest

type GetEventInfoRequest struct {
	Id    string `json:"id"`    // The ID of the requested Event.
	Start int    `json:"start"` // The starting range of returned occurrences. Optional, defaults to 2 years prior.
	End   int    `json:"end"`   // The ending range of returned occurrences. Optional, defaults to 3 years in the future.
}

The Request struct for calling GetEventInfo

type GetEventInfoResponse

type GetEventInfoResponse struct {
	StandardResponse           // Standard response fields
	Event            EventInfo `json:"event"` // The Event Info
}

The Response struct returned by GetEventInfo

type GetEventsRequest

type GetEventsRequest struct {
	Date     string // Date to get the events for. Defaults to today.
	Adult    bool   // Include events that may be unsafe for viewing at work or by children. Default is false.
	Timezone string // IANA Time Zone for calculating dates and times. Defaults to America/Chicago.
}

The Request struct for calling GetEvents

type GetEventsResponse

type GetEventsResponse struct {
	StandardResponse                // Standard response fields
	Adult            bool           `json:"adult"`             // Whether Adult entries can be included
	Date             string         `json:"date"`              // The Date string
	Timezone         string         `json:"timezone"`          // The Timezone used to calculate the Date's Events
	Events           []EventSummary `json:"events"`            // The Date's Events
	MultidayStarting []EventSummary `json:"multiday_starting"` // Multi-day Events that start on Date
	MultidayOngoing  []EventSummary `json:"multiday_ongoing"`  // Multi-day Events that are continuing their observance on Date
}

The Response struct returned by GetEvents

type ImageInfo

type ImageInfo struct {
	Small  string `json:"small"`  // A small image
	Medium string `json:"medium"` // A medium image
	Large  string `json:"large"`  // A large image
}

Information about an Event image

type Occurrence

type Occurrence struct {
	Date   string `json:"date"`   // The date or timestamp the Event occurs
	Length int    `json:"length"` // The length (in days) of the Event occurrence
}

Information about an Event's Occurrence

type Pattern

type Pattern struct {
	FirstYear        int    `json:"first_year"`        // The first year this event is observed (0 implies none or unknown)
	LastYear         int    `json:"last_year"`         // The last year this event is observed (0 implies none or unknown)
	Observed         string `json:"observed"`          // A description of how this event is observed (formatted as plain text)
	ObservedHtml     string `json:"observed_html"`     // A description of how this event is observed (formatted as HTML)
	ObservedMarkdown string `json:"observed_markdown"` // A description of how this event is observed (formatted as Markdown)
	Length           int    `json:"length"`            // For how many days this event is celebrated
}

Information about an Event's Pattern

type RateLimit

type RateLimit struct {
	LimitMonth     int // The amount of requests allowed this month
	RemainingMonth int // The amount of requests remaining this month
}

Your API plan's current Rate Limit and status. Upgrade to increase these limits.

type RichText

type RichText struct {
	Text     string `json:"text"`     // Formatted as plain text
	Html     string `json:"html"`     // Formatted as HTML
	Markdown string `json:"markdown"` // Formatted as Markdown
}

Formatted Text

type SearchRequest

type SearchRequest struct {
	Query string // The search query. Must be at least 3 characters long.
	Adult bool   // Include events that may be unsafe for viewing at work or by children. Default is false.
}

The Request struct for calling Search

type SearchResponse

type SearchResponse struct {
	StandardResponse                // Standard response fields
	Query            string         `json:"query"`  // The search query
	Adult            bool           `json:"adult"`  // Whether Adult entries can be included
	Events           []EventSummary `json:"events"` // The found Events
}

The Response struct returned by Search

type StandardResponse

type StandardResponse struct {
	RateLimit RateLimit // The API plan's current rate limit and status
}

The API's standard response

type StandardResponseInterface

type StandardResponseInterface interface {
}

An interface of the API's standard response