# Build with Ember

> Ember’s directory of Mass times is open: churches worldwide with the times of their Masses, confessions and adoration. There are no keys and no sign-up, and every response allows any origin.

Web page: https://ember.dpgu.me/developers/ · Em português: https://ember.dpgu.me/pt/desenvolvedores.md

## Mass-times API

Churches near a point, by name or on a map, each with its Mass, confession and adoration times written as recurrence rules.

Base URL: `https://ember-mass-times.dpgu.workers.dev`

[API reference](https://ember.dpgu.me/developers/api.md)

## Quick start

The API answers plain HTTP GETs. From a shell:

```sh
# The five churches nearest the Sé of São Paulo
curl 'https://ember-mass-times.dpgu.workers.dev/churches/near?lat=-23.5505&lng=-46.6333&limit=5'
```

## Using it well

- **Cache what you fetch.** Church data changes by the day: keeping it for up to a day is fine, and a mirror can refresh daily. Fetch a church again when someone opens it, so they see the latest corrections. Reads have no rate limit, so for heavy traffic serve your own copy rather than calling the API for every visitor.
- **Show how fresh a time is.** Parishes change their times and a directory falls behind. Show `lastVerifiedAt` beside a schedule, and let people confirm it or send a correction from your app.
- **Credit Ember, if you can.** We’d be grateful for a line such as “Mass times from Ember” linking to [ember.dpgu.me/app/](https://ember.dpgu.me/app/). Where you show a single church, its page on Ember, `https://ember.dpgu.me/mass-times/church/?id={id}`, makes a good link too.
- **Writes are suggestions.** A correction goes to a queue a person reviews and never edits a church directly. A confirmation counts once per client and church every 30 days. Each client may write 20 times a minute; past that the API answers `429`.
- **Identify each device or person.** A client is its IP address together with the `X-Client-Id` header. Send a stable id per device or user, so people who share an address, such as everyone whose writes pass through your server, keep separate limits and separate confirmations.

## Source

- [apps/backend](https://github.com/gustavo-depaula/ember/blob/main/apps/backend): The Mass-times Worker: Hono on Cloudflare Workers and D1
- [packages/api](https://github.com/gustavo-depaula/ember/blob/main/packages/api): The API’s schemas, its OpenAPI document and a schedule expander