Skip to main content
Public religion contract

Religion API and release docs

This is the public site contract for the religion atlas. It is separate from the paid /api/v1 developer platform and documents the JSON feeds that power published religion atlas and dossier pages.

Contract version
V1
Published dossiers
20
Politics-enabled
12
Source window
Religion Census 2020 + modeled 2016-2024 politics where stable
Contract policy

The published religion product is dossier-first. Use /api/religion/catalog for atlas discovery, /api/religion/national for the U.S. baseline, and the dossier routes for page-level payloads.

Interpretation rule

Footprint fields describe adherent and population concentration. Politics fields describe modeled geographic patterns only where a stable series exists. They do not describe observed individual vote behavior.

Endpoints

Public religion responses now carry a describedby link header pointing back to this page.

Atlas catalog
/api/religion/catalog

Returns the published religion atlas entries with national population share, adherent share, strongest geographies, and dossier availability flags.

GET /api/religion/catalog
National baseline
/api/religion/national

Returns the U.S. adherent baseline plus tradition-level share-of-adherents and share-of-population metrics.

GET /api/religion/national
Dossier payload
/api/religion/{slug}

Returns one religion dossier with national footprint, top geographies, related groups, methodology, provenance, and modeled politics when published.

GET /api/religion/catholic
Geography rankings
/api/religion/{slug}/geographies

Returns the public state and county rankings for one religion dossier, preserving population share and adherent share as separate measures.

GET /api/religion/catholic/geographies
Denomination lookup
/api/religion/denominations?geo_id={geo_id}

Returns denomination-level breakdowns for a selected geography, grouped under parent traditions.

GET /api/religion/denominations?geo_id=county:2020:17031
Legacy politics feed
/api/religion

Returns the raw modeled religion margin series by election year. Use this only when you want the politics rows directly rather than the dossier contract.

GET /api/religion?year=2024

Response semantics

These fields define the public religion product and keep footprint metrics separate from modeled politics.

Core fields
  • shareOfPopulationPct: share of the full geography population represented by the religion or denomination.
  • shareOfAdherentsPct: share of religious adherents represented by the religion or denomination when derivable from the source data.
  • kind: tradition or denomination, matching the published religion registry.
  • hasPoliticsModule: true only when a stable modeled politics series is published for the dossier.
  • method and reliability: model provenance for the politics timeline when a series exists.
  • contractVersion and docs: every public religion response links back to this page through both headers and payload fields where the route shape allows it.
Type shape
interface ReligionDossierPayload {
  success: true;
  contractVersion: 'v1';
  docs: string;
  dossier: {
    entity: {
      kind: 'tradition' | 'denomination';
      releaseLabel: 'PUBLISHED' | 'HELD';
      availability: {
        hasPoliticsModule: boolean;
        indexStatus: 'index' | 'noindex';
      };
    };
    nationalFootprint: {
      shareOfPopulationPct: number | null;
      shareOfAdherentsPct: number | null;
    };
    politicsSummary: {
      latestYear: number;
      latestMarginPct: number | null;
      method: string | null;
      reliability: string | null;
    } | null;
  };
}

Coverage classes

The published religion atlas mixes top-level traditions and denomination dossiers without collapsing their semantics.

Traditions

12 published top-level traditions. These are the main religion atlas dossiers and may include modeled politics where stable.

Denominations

8 published denomination dossiers. These preserve footprint metrics even when no politics series is published.

Politics-enabled

12 published religion dossiers currently expose a modeled politics timeline.

Footprint-only

8 published dossiers expose geography and footprint metrics without a politics module.

Scope and limits

What these endpoints are, and what they are not.

Included
  • Religion Census 2020 footprint and geography rankings.
  • Explicit separation between share of population and share of adherents.
  • Modeled politics only for dossiers with a stable published series.
Excluded
  • Observed individual vote behavior or respondent-level survey claims.
  • Any promise that a denomination without a politics module will receive one automatically.
  • Paid developer platform guarantees from the authenticated /api/v1 product.
Return to religion atlasOpen methodology