holidays

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2023 License: MIT Imports: 8 Imported by: 0

README

The Official Holiday and Event API for Go

Go Reference Build Status Code Coverage Funding Status

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 added in v0.0.2 

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 added in v1.0.0 

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.