Reference data

Public holiday calendar for a country, paid per call over x402 (same data is free at /v1/{country}/public-holidays)

The same cited payload as GET /v1/{country}/public-holidays, sold per call so x402 agents and indexes (Coinbase Bazaar) can discover and pay for it like any other resource. Optional ?year=YYYY filters to one calendar year. Website visitors and anyone happy with the free route should use /v1/{country}/public-holidays, which stays free.

get/v1/holidays/{country}

Request

  • Base URL: https://afriref.dev
  • URL: https://afriref.dev/v1/holidays/{country}
  • Auth: one of:
    • API key in header PAYMENT-SIGNATURE
    • API key in header X-PAYMENT
    • API key in header X-API-Key

Path parameters

country'ao' | 'bf' | 'bj' | 'bw' | 'cd' | 'cf' | 'cg' | 'ci' | 'cm' | 'dz' | 'eg' | 'et' | 'ga' | 'gh' | 'gq' | 'ke' | 'ls' | 'ma' | 'ml' | 'mu' | 'mz' | 'na' | 'ne' | 'ng' | 'rw' | 'sn' | 'sz' | 'td' | 'tg' | 'tn' | 'tz' | 'ug' | 'za' | 'zm' required
Example:ao

Query parameters

yearstring

Response

Holiday calendar, plus subdivisions where the country has regions

countrystring required

ISO 3166-1 alpha-2 country code

seriesstring required
valueunknown required
unitstring
effective_fromstring date nullable required
effective_from_basis'restatement'

Optional. Absent: effective_from is the date the value became the law (a genuine change point). 'restatement': effective_from is the date the value's CURRENT LEGAL BASIS took effect (a new tax code, an annual finance law) while the value itself is older and its true origin is not primary-verifiable — a verified floor, not a change. Do not read a restatement row as the value having changed on that date.

last_confirmedstring date required

When this value was last verified against the official source

staleboolean required

True when past the expected update cycle — treat with caution

notesstring
effective_ratenumber

Optional. Combined effective rate where statutory levies stack on top of the standard rate (e.g. Ghana VAT 15% + NHIL 2.5% + GETFund 2.5% = 20%). Present only where it differs from value.

confidence_label'high' | 'medium' | 'low'

Derived from source type, verification age, stale. Rules: /label-rules

coverage_label'ready' | 'partial' | 'gap'

ready=complete, partial=limited, gap=no number. Rules: /label-rules

label_basisobject

Inputs and rule ids behind both labels

Changes

No recorded changes to this operation across all 3 revisions of this API.