# Prayer times (SBX-PRAY)

Daily prayer times for any city or coordinate, by the Diyanet method by default or eleven others, with the Qibla direction.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/prayer-times/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["prayer-times"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/prayer-times/days

**Get prayer times**

The five daily prayer times and sunrise for a city (`cityId`, from the Cities API) or a point (`lat`, `lon`), for one day or up to 31 days from `date` (default: today there). The timezone is the city's, or the nearest city's for a point, unless `timezone` is given. The default method `turkey` follows the Turkish Presidency of Religious Affairs (Diyanet: İmsak 18°, Yatsı 17°, with its minute adjustments); results can differ from Diyanet's published table by a minute or two. `meta.qiblaDegrees` is the Qibla direction, clockwise from true north.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cityId` | query | string | no | A city id from the Cities API, e.g. 745044 (İstanbul). |
| `lat` | query | number | no | Latitude (WGS84), with `lon`. |
| `lon` | query | number | no | Longitude (WGS84), with `lat`. |
| `date` | query | string | no | First day, YYYY-MM-DD. Default: today in the place's timezone. |
| `days` | query | integer | no | Number of days, 1–31. |
| `timezone` | query | string | no | IANA timezone, e.g. Europe/Istanbul. Default: the city's. |
| `method` | query | string | no | Calculation method (see /methods). |
| `madhab` | query | string (`shafi`, `hanafi`) | no | `shafi` (standard Asr, as Diyanet) or `hanafi`. |

**Example**

```bash
curl "https://api.servicebox.io/v1/prayer-times/days" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/prayer-times/methods

**List calculation methods**

The calculation methods `method` accepts, with their twilight angles. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/prayer-times/methods" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/prayer-times/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-PRAY
- API page: https://servicebox.io/en/apis/prayer-times