Kirchenführer API Documentation

API Documentation

This page describes how to access and use the Kirchenführer API.

Authorization

To connect to our API, you must include your access token in the Authorization header of each request.

curl https://der-kirchenfuehrer.de/api/v1/churches
-H "Authorization: Bearer TOKEN-HERE"
-H "Accept: application/json"

Getting access tokens

The Kirchenführer API is currently in private beta. You will be able to register for an access token once it goes public.

Response structure

All endpoints return their data in JSON format. Unless otherwise specified, the resource data of a request will be wrapped inside a top-level data key. For “list” routes, the response will include additional pagination information at the top-level.

Responses follow https://schema.org resources where possible. The specific resource used will be noted in the documentation for each endpoint.

Pagination

When fetching records in bulk using the “list” endpoints, our API returns a paginated result.

The Kirchenführer API uses cursor-based pagination and will in include, among other meta information, links to the next and previous page when applicable.

{
"data": [
/* ... */
],
"links": {
"first": null,
"last": null,
"prev": "https://der-kirchenfuehrer.de/api/v1/churches?cursor=eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
"next": "https://der-kirchenfuehrer.de/api/v1/churches?cursor=eyJpZCI6MjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://der-kirchenfuehrer.de/api/v1/churches",
"per_page": 25,
"next_cursor": "eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
"prev_cursor": "eyJpZCI6MjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
}
}

Errors

When we detect an error in the request, we will return an HTTP 4xx response, and a JSON payload with a single key error containing the error message.

If you’re not receiving errors, make sure to include Accept: application/json in your request headers.

{
"message": "Unauthenticated."
}

Rate limiting

We limit API requests to 60 requests per minute. If you go over this limit, the API returns a 429 Too Many Requests response. In this case, you may inspect the Retry-After and X-RateLimit-Reset headers of the response to see when the limit resets.

HTTP/1.1 429 Too Many Requests
Retry-After: 58
X-RateLimit-Reset: 1661227009
{
"message": "Too Many Attempts."
}

Language

While it is planned to include an option for fetching resources in different languages, the API currently always returns the German language version for each resource.

Ping

You can use the ping endpoint to check if the API is reachable and if your access token is valid.

GET https://der-kirchenfuehrer.de/api/v1/ping

Sample response

"pong"

Churches

The response structure of these endpoints follow the Church schema.

List churches

Returns a list of Church objects

GET https://der-kirchenfuehrer.de/api/v1/churches

Sample response

{
"data": [
{
"@context": "https://schema.org",
"@type": "Church",
"@id": "ce1ec177-f947-4a9a-8432-15ce73154f9d",
"name": "Sample Church",
"description": "A short description of the church",
"address": {
"@type": "PostalAddress",
"streetAddress": "Musterstraße 5",
"postalCode": "99999",
"addressLocality": "Musterstadt"
},
"url": [
"https://der-kirchenfuehrer.de/kirchen/sample-church"
],
"telephone": "+49 1234 5678",
"publicAccess": true,
"geo": {
"@type": "GeoCoordinates",
"longitude": 10.000000,
"latitude": 48.000000
},
"image": {
"@type": "ImageObject",
"@id": "ad6257cf-3dc4-43a9-974a-5951bceded24",
"contentUrl": "https://der-kirchenfuehrer.de/storage/1/image.jpg",
"author": {
"@type": "Person",
"@id": "fde82dfb-007f-4183-b5fe-a009eb2c4984",
"familyName": "Mustermann",
"givenName": "Max"
},
"copyrightHolder": {
"@type": "Organization",
"@id": "6e928cb1-8d29-4bcd-a901-373577381aad",
"legalName": "Der Kirchenführer UG (haftungsbeschränkt)",
"name": "Der Kirchenführer"
},
"license": "https://creativecommons.org/licenses/by-sa/2.0/"
},
"photo": {
"@type": "ImageObject",
"@id": "ad6257cf-3dc4-43a9-974a-5951bceded24",
"contentUrl": "https://kirchenfuehrer.test/storage/1/image.jpg",
"author": {
"@type": "Person",
"@id": "fde82dfb-007f-4183-b5fe-a009eb2c4984",
"familyName": "Mustermann",
"givenName": "Max"
},
"copyrightHolder": {
"@type": "Organization",
"@id": "6e928cb1-8d29-4bcd-a901-373577381aad",
"legalName": "Der Kirchenführer UG (haftungsbeschränkt)",
"name": "Der Kirchenführer"
},
"license": "https://creativecommons.org/licenses/by-sa/2.0/"
},
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "https://schema.org/Monday",
"opens": "08:00",
"closes": "19:50"
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "https://schema.org/Friday",
"opens": "08:00",
"closes": "19:50"
}
]
}
/* ... */
],
"links": { Click to show }
"first": null,
"last": null,
"prev": "https://der-kirchenfuehrer.de/api/v1/churches?cursor=eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
"next": "https://der-kirchenfuehrer.de/api/v1/churches?cursor=eyJpZCI6MjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": { Click to show }
"path": "https://der-kirchenfuehrer.de/api/v1/churches",
"per_page": 25,
"next_cursor": "eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
"prev_cursor": "eyJpZCI6MjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
}
}

Note that both photo and image are optional properties.

Get church

Returns a single Church object for a given UUID. Returns a 404 Not Found response if no church exists for the given UUID.

GET https://der-kirchenfuehrer.de/api/v1/churches/{uuid}

Sample response

{
"data": {
"@context": "https://schema.org",
"@type": "Church",
"@id": "ce1ec177-f947-4a9a-8432-15ce73154f9d",
"name": "Sample Church",
"description": "A short description of the church",
"address": {
"@type": "PostalAddress",
"streetAddress": "Musterstraße 5",
"postalCode": "99999",
"addressLocality": "Musterstadt"
},
"url": [
"https://der-kirchenfuehrer.de/kirchen/sample-church"
],
"telephone": "+49 1234 5678",
"publicAccess": true,
"geo": {
"@type": "GeoCoordinates",
"longitude": 10.000000,
"latitude": 48.000000
},
"image": {
"@type": "ImageObject",
"@id": "ad6257cf-3dc4-43a9-974a-5951bceded24",
"contentUrl": "https://der-kirchenfuehrer.de/storage/1/image.jpg",
"author": {
"@type": "Person",
"@id": "fde82dfb-007f-4183-b5fe-a009eb2c4984",
"familyName": "Mustermann",
"givenName": "Max"
},
"copyrightHolder": {
"@type": "Organization",
"@id": "6e928cb1-8d29-4bcd-a901-373577381aad",
"legalName": "Der Kirchenführer UG (haftungsbeschränkt)",
"name": "Der Kirchenführer"
},
"license": "https://creativecommons.org/licenses/by-sa/2.0/"
},
"photo": {
"@type": "ImageObject",
"@id": "ad6257cf-3dc4-43a9-974a-5951bceded24",
"contentUrl": "https://kirchenfuehrer.test/storage/1/image.jpg",
"author": {
"@type": "Person",
"@id": "fde82dfb-007f-4183-b5fe-a009eb2c4984",
"familyName": "Mustermann",
"givenName": "Max"
},
"copyrightHolder": {
"@type": "Organization",
"@id": "6e928cb1-8d29-4bcd-a901-373577381aad",
"legalName": "Der Kirchenführer UG (haftungsbeschränkt)",
"name": "Der Kirchenführer"
},
"license": "https://creativecommons.org/licenses/by-sa/2.0/"
},
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "https://schema.org/Monday",
"opens": "08:00",
"closes": "19:50"
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "https://schema.org/Friday",
"opens": "08:00",
"closes": "19:50"
}
]
}
}

Note that both photo and image are optional properties.