Versioned paths, versioned data

Routes are prefixed /v1. Separately, every payload carries the version of the dataset it answered from, because a contract can stay stable while the facts underneath it change. Ask /health on any service to see the dataset version it is currently serving.

Provenance is a field, not a footnote

Records carry the identifiers you need to audit them: a sourceId (or sourceIds) pointing at the register entry for the publishing authority, and a verifiedAt or reviewedAt date saying when a human last checked. If a record cannot carry those, it does not get published.

Honest outcomes over convenient ones

Where a question has no single correct answer, the API says so rather than picking. GhanaCodes returns an ambiguous outcome with sorted candidates instead of guessing a match. GhanaCalendar leaves an unannounced movable holiday as null rather than predicting a date. An empty or undecided answer is a feature.

Coverage is stated, never implied

Responses include a coverage string such as "verified subset" or "metadata-only verified subset". None of these services claims to be a comprehensive national database, and reading one row should never leave you thinking it is.

Read-only and public, but not open-CORS

The public APIs are read-only, with no signup and no token. Nothing accepts a credential, proxies a government transaction or reproduces an official form. If a future surface needs authentication, it will be a new surface, separately announced.

Cross-origin access is the one place people get caught out. Each API sends Access-Control-Allow-Origin for its own product site only — for example api-gov allows https://gov.digitalghana.dev and nothing else. A fetch from your own front end will be blocked by the browser. Call these services from your backend, or run your own instance from the source.

Stable identifiers

Record IDs are stable and are not recycled. A breaking contract change gets a new path version and a published migration, rather than a quiet change of meaning under the old one.

Corrections need evidence

Data is wrong sometimes; that is normal and worth fixing properly. Open an issue on the product repository with the affected identifier, the current value, the proposed value, the authoritative source and its publication date. Automation may draft a correction, but a human reviewer approves anything that becomes canonical.

Cold starts

Product APIs run on Render. A service that has been idle takes 30–60 seconds to wake. Set a generous timeout on the first call, retry once, and do not treat a single slow response as an outage.

Independence

Every product in this portfolio is independent open source. None is operated by, endorsed by, or affiliated with the Government of Ghana or any of its agencies. Official transactions belong on the official government websites these services link to.