Corpus — Sacred Site Mapping

The Corpus engine is the geographic layer of the Torch. It exposes a PostGIS-backed dataset of Catholic churches and sacred sites sourced from OpenStreetMap, enabling proximity searches, name lookups, and diocese boundary queries.

All Corpus endpoints are mounted at /v1/corpus and require an X-API-Key header. See Authentication.

Find Nearby Sites

GET /v1/corpus/nearby

Returns sacred sites within a given radius of a coordinate, ordered by proximity (nearest first).

Query parameters:

Parameter	Type	Default	Description
`lat`	`float`	(required)	Latitude in decimal degrees
`lon`	`float`	(required)	Longitude in decimal degrees
`radius_miles`	`float`	`10.0`	Search radius (0–100 miles)
`event_type`	`LiturgyType`	(optional)	Filter to sites offering a specific liturgy
`limit`	`int`	`50`	Max results (1–200)

Example:

curl "https://api.torchandlily.com/v1/corpus/nearby?lat=40.7128&lon=-74.0060&radius_miles=5" \
  -H "X-API-Key: tl_your_key_here"

Response: List[SacredSiteRead]

[
  {
    "id": 101,
    "name": "Saint Patrick's Cathedral",
    "slug": "saint-patricks-cathedral-new-york",
    "site_type": "CATHEDRAL",
    "location": { "type": "Point", "coordinates": [-73.9762, 40.7580] },
    "osm_id": "node/123456789",
    "website_url": "https://saintpatrickscathedral.org",
    "street": "5th Avenue",
    "city": "New York",
    "state": "NY",
    "postcode": "10022",
    "phone": null,
    "saint_id": null,
    "diocese_id": null,
    "denomination": "catholic",
    "historic": null,
    "distance_miles": 1.4,
    "liturgies": []
  }
]

Find by Name

GET /v1/corpus/find

Searches for sacred sites by name using trigram similarity. Results are alphabetical by default; provide coordinates to sort nearest-first.

Query parameters:

Parameter	Type	Default	Description
`name`	`str`	(required, min 2 chars)	Church name or partial name
`state`	`str`	(optional)	State abbreviation (e.g. `TX`)
`city`	`str`	(optional)	City name
`lat`	`float`	(optional)	Your latitude — enables nearest-first ordering
`lon`	`float`	(optional)	Your longitude — enables nearest-first ordering
`limit`	`int`	`50`	Max results (1–200)

Example:

curl "https://api.torchandlily.com/v1/corpus/find?name=Holy+Redeemer&state=TX" \
  -H "X-API-Key: tl_your_key_here"

Response: List[SacredSiteRead]

Search by Location

GET /v1/corpus/search

Finds sacred sites near a named location. Geocoding is performed via OpenStreetMap Nominatim. Provide either q (free-text) or city.

Query parameters:

Parameter	Type	Default	Description
`q`	`str`	(optional)	Free-text location (e.g. `Weatherford TX`)
`city`	`str`	(optional)	City name for structured search
`state`	`str`	(optional)	State or region
`radius_miles`	`float`	`10.0`	Search radius (0–100 miles)
`event_type`	`LiturgyType`	(optional)	Filter by liturgy type
`limit`	`int`	`50`	Max results (1–200)

Example:

curl "https://api.torchandlily.com/v1/corpus/search?q=Fort+Worth+TX&radius_miles=15" \
  -H "X-API-Key: tl_your_key_here"

Get Site by Slug

GET /v1/corpus/slug/{slug}

Returns full details for a single sacred site.

Path parameters:

slug — URL-safe site identifier

Response: SacredSiteRead

SacredSiteRead — Full Schema

Field	Type	Notes
`id`	`int`	Internal ID
`name`	`str`	Site display name
`slug`	`str`	URL-safe identifier
`site_type`	`str`	`CHURCH`, `CATHEDRAL`, `BASILICA`, `CHAPEL`, `SHRINE`, or `ORATORY`
`location`	`GeoJSON Point`	`{ "type": "Point", "coordinates": [lon, lat] }`
`osm_id`	`str?`	OpenStreetMap node/way/relation ID
`website_url`	`str?`	Official website
`street`	`str?`	Street address
`city`	`str?`	City
`state`	`str?`	Two-letter state abbreviation
`postcode`	`str?`	Postal code
`phone`	`str?`	Phone number
`saint_id`	`int?`	Linked saint ID (Devotio engine)
`diocese_id`	`int?`	Linked diocese ID (populated after diocese sync)
`denomination`	`str?`	OSM denomination tag (e.g. `catholic`, `roman_catholic`)
`historic`	`str?`	OSM historic classification
`distance_miles`	`float?`	Distance from query point (only on `/nearby` and `/search` responses)
`liturgies`	`List[LiturgyRead]`	Mass and sacrament schedules

LiturgyRead

Field	Type	Notes
`id`	`int`	Internal ID
`site_id`	`int`	Parent site ID
`type`	`LiturgyType`	`MASS`, `CONFESSION`, or `ADORATION`
`day`	`str`	Day name (e.g. `Sunday`)
`start_time`	`str`	24-hour time string (e.g. `09:00`)
`language`	`str?`	Language of the liturgy

LiturgyType Enum

Value	Description
`MASS`	Holy Mass
`CONFESSION`	Sacrament of Confession
`ADORATION`	Eucharistic Adoration

Dioceses

The diocese layer provides the canonical boundary polygons for Catholic dioceses, sourced from OpenStreetMap relation data. Sites are assigned to a diocese via spatial intersection (ST_Within).

Diocese boundary data in OpenStreetMap is currently concentrated outside the United States — approximately 7,000 Catholic diocese boundaries exist globally (primarily in Europe, Latin America, and Africa), but US dioceses have not yet been mapped as boundary relations in OSM. As a result, the diocese endpoints will return empty results for US coverage until one of two things happens:

International expansion — when Torch & Lily syncs non-US regions, the existing pipeline will capture diocese boundaries automatically.
OSM community contribution — if contributors map US Catholic diocese boundaries using the boundary=religious_administration + denomination=catholic tags, our sync will pick them up on the next run.

The diocese_id field on site records will remain null for US sites until diocese data becomes available. All diocese endpoints and infrastructure are fully operational and ready to serve data once it exists.

List Dioceses

GET /v1/corpus/diocese

Returns all published dioceses with name, slug, and site count. Boundary geometry is omitted — use the detail endpoint for the full polygon.

Response: List[DioceseRead]

[
  {
    "id": 14,
    "name": "Archdiocese of New York",
    "slug": "archdiocese-of-new-york",
    "osm_id": "relation/123456",
    "website_url": "https://archny.org",
    "site_count": 412
  }
]

Get Diocese Detail

GET /v1/corpus/diocese/{slug}

Returns a single diocese with its full boundary as a GeoJSON MultiPolygon. Suitable for rendering on a map.

Response: DioceseDetail

{
  "id": 14,
  "name": "Archdiocese of New York",
  "slug": "archdiocese-of-new-york",
  "osm_id": "relation/123456",
  "website_url": "https://archny.org",
  "boundary": {
    "type": "MultiPolygon",
    "coordinates": [ ... ]
  }
}

Sites in a Diocese

GET /v1/corpus/diocese/{slug}/sites

Returns all sacred sites whose coordinates fall within the diocese boundary polygon (ST_Within).

Path parameters:

slug — diocese slug

Query parameters:

limit — max results (default: 100, max: 500)

Response: List[SacredSiteRead]

Integration Notes

Cross-engine enrichment: When a site has a saint_id, retrieve the full saint record via GET /v1/devotio/saints/id/{saint_id}. Sites dedicated to a named saint will carry this link when the hagiographic record is present in the Devotio engine.

Diocese membership: The diocese_id field on each site is populated via a spatial pass after dioceses are synced. This field is currently null for US sites — see the Dioceses section for details on data availability. When populated, query the site’s diocese via GET /v1/corpus/diocese/{slug} to retrieve the boundary and metadata.