API usage

Clean docs for a simple API.

Everything a programmer needs in one place: authentication, endpoints, parameters, examples, and JSON responses.

Quick start

All requests use GET and include your API key.

https://api.public-holidays.nz/v1/year?apikey=YOUR_API_KEY&year=2026

Authentication

API key required

Every request includes your API key as a query string parameter named apikey.

https://api.public-holidays.nz/v1/year?apikey=YOUR_API_KEY&year=2026

Interactive helper

Live example builder

Build an example request URL and copy it straight into your code or browser.

Endpoint

API key

Year

GET

/v1/year

Returns all public holidays in a specific year.

Parameter	Required	Description
apikey	Yes	Your API key
year	Yes	Four-digit year such as 2026

https://api.public-holidays.nz/v1/year?apikey=YOUR_API_KEY&year=2026

fetch("https://api.public-holidays.nz/v1/year?apikey=YOUR_API_KEY&year=2026")
  .then(function(response){ return response.json(); })
  .then(function(data){ console.log(data); });

<%
Dim http, url
url = "https://api.public-holidays.nz/v1/year?apikey=YOUR_API_KEY&year=2026"

Set http = Server.CreateObject("MSXML2.ServerXMLHTTP")
http.Open "GET", url, False
http.Send

Response.ContentType = "application/json"
Response.Write http.responseText

Set http = Nothing
%>

GET

/v1/day

Returns the details of a specific day.

Parameter	Required	Description
apikey	Yes	Your API key
date	Yes	Date in dd/mm/yyyy or dd-mm-yyyy format

https://api.public-holidays.nz/v1/day?apikey=YOUR_API_KEY&date=25/12/2026

GET

/v1/holiday

Returns true or false for whether a specific date is a public holiday.

Parameter	Required	Description
apikey	Yes	Your API key
date	Yes	Date in dd/mm/yyyy or dd-mm-yyyy format

https://api.public-holidays.nz/v1/holiday?apikey=YOUR_API_KEY&date=25/12/2026

GET

/v1/all

Returns all public holidays in the database.

Parameter	Required	Description
apikey	Yes	Your API key

https://api.public-holidays.nz/v1/all?apikey=YOUR_API_KEY

Error handling

Error responses

Missing API key

Not Authorised

Invalid date

{
  "success": false,
  "error": "Invalid date format"
}