PH Holidays API

Read-only JSON API for Philippine public holidays, with proclamation citations

Calls without a key stop working on 23 January 2027 UTC. Until then they are served with Deprecation and Sunset headers. Get a free Sandbox key at /account or choose a Plan at /pricing.

Quick start

Get a free Sandbox key (2024 data, 100 a day) or a Plan at /account.

Send it in a header:

x-api-key: phc_…
# or
Authorization: Bearer <key>

Make your first call, GET /v1/holidays?year=2026: the Request panel has it in cURL, JavaScript and Python.

Base URL	`https://api.pholidays.com`
CORS	Enabled for all origins.
Caching	Responses are edge-cached for up to an hour, so cache on your side too.
Dates	`YYYY-MM-DD` in Asia/Manila.

Authentication

Send a Client key (phc_…) in the x-api-key header, or as Authorization: Bearer <key>. Choose a Plan at /pricing, then create keys at /account.

Calls without a key are being phased out. A call with a key is never affected.

Errors and limits

A refusal has the body { "error": "...", "detail": { "reason": "..." } } and cache-control: no-store.

Code	Reason	Meaning
400	—	Invalid query parameters; `detail` holds the field errors.
401	`invalid_keyno_key`	The key is invalid or revoked, or none was sent.
403	`sandbox_year_onlyfeature_not_in_planpast_duesubscription_inactive`	Refused.
404	—	No holiday recorded on that date.
429	`rate_limitedquota_exceeded`	Over a limit; wait `Retry-After` seconds.
500	—	Internal error.

GET`/v1/holidays`

List holidays

Parameters

Name	Type	Notes
year	integer	min 2000, max 2100
type	HolidayType	`regularspecial_non_workingspecial_workinglocal`
status	HolidayStatus	`confirmedprojectedpending`
locality	string	Locality slug, or `nationwide`.min length 1, max length 100Pro & Business
from	string (date)	Inclusive start date.
to	string (date)	Inclusive end date.
limit	integer	min 1, max 500, default 366

Responses

Matching holidays.

Header	Type	Notes
Cache-Control	string	Edge-cached; cache on your side too. A Sandbox key gets `private, no-store` instead.
x-pholidays-sandbox	integer	Present only for a Sandbox key. The one year it serves. On every 200 to a Sandbox key, cache HIT included.
Deprecation	string	Present only on a call with no key, once a sunset date is announced. RFC 9745: `@` followed by Unix seconds, 60 days before `Sunset`. On a 200 to a call with no key, cache HIT included.
Sunset	string	Present only on a call with no key, once a sunset date is announced. RFC 8594 HTTP-date: when calls with no key start to get a `401`. On a 200 to a call with no key, cache HIT included.
Link	string	Present only on a call with no key, once a sunset date is announced. `<https://pholidays.com/pricing>; rel="sunset"`: where to get a key. On a 200 to a call with no key, cache HIT included.

Response schema

Field	Type	Notes
data	array<Holiday>
id	integer
date	string (date)
weekday	string
year	integer
name	string
type	HolidayType	`regularspecial_non_workingspecial_workinglocal`
status	HolidayStatus	`confirmedprojectedpending`
locality	string
region	string \| null
province	string \| null
proclamationNumber	string \| null
sourceUrl	string \| null
isMovable	boolean
notes	string \| null
source	string	`projectionseedscrapermanual`
premiumPay	PremiumPay	What an employee earns on the day, as a multiple of the daily wage.
unworked	number	Day not worked.
worked	number	Day worked (first 8 hours).
note	string
updatedAt	string (date-time)
meta	object
lastUpdated	string \| null
lastChecked	string \| null
coverage	string
officialSource	string
sandbox	object	Present only on a 200 to a Sandbox key.optional
year	integer	The one year a Sandbox key serves.
requestsPerDay	integer	The daily cap (UTC day).
remainingToday	integer	Requests left today after this one.
note	string	A reminder of the Sandbox rules and where to buy a Plan.
count	integer	How many items `data` holds.
filters	object	The parsed filters that were applied.optional

Errors: see Errors and limits.

Request

curl "https://api.pholidays.com/v1/holidays?year=2026" \
  -H "x-api-key: $API_KEY"

Response · 200 · sample, trimmed

{
  "data": [
    {
      "id": 1,
      "date": "2026-01-01",
      "name": "New Year's Day",
      "type": "regular",
      "status": "confirmed",
      "premiumPay": { "unworked": 1, "worked": 2, "note": "Paid even if unworked; 200% of daily wage if worked." }
      // … 11 more fields
    }
    // … 20 more
  ],
  "meta": { "count": 21 /* … 5 more fields */ }
}

Sandbox key

A Customer with no Plan access right now (never subscribed, or their Plan has lapsed) can take a free Sandbox key at /account. No card. Use it to try the API before you buy.

It serves 2024 only, 100 requests a day (UTC day), and the core lookups only.
Refusals are not counted.

Route	Sandbox rule
`/v1/holidays`	Needs `year`, or `from` and `to`, inside 2024.
`/v1/holidays/{date}` and `/v1/is-holiday`	The date must be inside 2024.
`/v1/long-weekends`	Needs `year` = 2024.
`/v1/upcoming`	Always refused.
`/v1/workday`, `/v1/export`, `/v1/calendar.ics` and `/v1/changes`	Plan features, refused with `403 feature_not_in_plan`.
A `locality` other than `nationwide`, on a route that takes `locality`	A Plan feature, refused with `403 feature_not_in_plan`.
`/v1/coverage`	Open to a Sandbox key.

Headers and meta

An answer to a Sandbox key carries the header x-pholidays-sandbox: 2024:

On a 200 (a cache hit too), a 400, a 404 from a lookup, the 403 refusals (feature_not_in_plan, sandbox_year_only) and the daily 429.
Not on a 401, the per-IP 429, a 500, the OPTIONS preflight or a 404 for an unknown path.
A 200 also has meta.sandbox (year, requestsPerDay, remainingToday, note) and cache-control: private, no-store.

What a Sandbox key sees:

Every row keeps its sourceUrl and proclamationNumber. Provenance is part of every row. The source links listed in the Plans are the features built on them, not those fields.
/v1/holidays?year=2024 keeps the local rows. The Plan feature is filtering by locality, not seeing local rows.
/v1/coverage returns counts, Source status and the verification summary, never holiday rows.

Plans

Plan	Pro	Business
Price	Pro$19/month or $190/year	Business$59/month or $590/year
Requests	Pro50,000 a month, 120 a minute	Business500,000 a month, 600 a minute
Client keys	Pro2	Business10
Support within	Pro2 business days	Business1 business day
Includes	Pro Core lookups (holidays, is-holiday, upcoming, long weekends, coverage) Workday calculations (/v1/workday) Local (locality) filters Change feed Links to the source proclamation	BusinessEverything in Pro, plus: Bulk year export iCal feed

Quotas are hard caps. Past the quota a call gets 429 with Retry-After. There is no overage billing.
Full refund on request within 14 days of a payment.
A past_due subscription keeps working for 7 days, then gets 403; keys are never deleted and work again when payment succeeds.

Data freshness and support

The sources (PCO and the Official Gazette) are checked once a day.
The annual PCO list is applied automatically.
Amendments, mid-year proclamations and some local proclamations need a manual review.
We add them within 2 business days of their publication by PCO or the Official Gazette.
Every answer carries meta.lastChecked, the last successful check of the sources (not a re-check of every holiday).
No uptime SLA.
Email support (support@pholidays.com) targets: Pro within 2 business days, Business within 1 business day.

Status values

Status	Meaning
`confirmed`	Declared by an official proclamation or statute.
`projected`	Derived from fixed legal rules (fixed dates, Easter, last Monday of August); proclamation not yet seen.
`pending`	E.g. Eid'l Fitr/Adha: the date is an estimate until proclaimed.

Nationwide holidays are the focus. Local holidays are best-effort and always incomplete — see /v1/coverage.