vaktija.eu API

Quick start

1. Find the id of your location in the location list (no key needed).
2. Ask for an API key at [email protected].
3. Request the prayer times with your key:

curl -H "api-key: YOUR_API_KEY" \
  https://api.vaktija.eu/v4/locations/7/today

Authentication

Every endpoint that returns prayer times checks your API key. Send it in the api-key header with each request. The location list needs no key.

• A key is issued for specific locations. Requests for any other location answer 403.
• Keep the key secret. Call the API from your server or device, never from a web page that visitors can read. Browsers on other websites cannot call the API.
• If a key leaks, tell us and we will replace it.

Getting a key

Write to [email protected] with:

• your organisation and what you are building
• the locations you need, by id from the location list
• roughly how many screens, devices or users will use it

Endpoints

Paths are relative to https://api.vaktija.eu/v4. A location can be named by its id (7) or its slug (ulm); we recommend the id. Nothing else is available to partners.

curl https://api.vaktija.eu/v4/locations

{
  "status": "success",
  "data": [
    {
      "id": 7,
      "name": "Ulm",
      "slug": "ulm",
      "latitude": 48.4011,
      "longitude": 9.9876,
      "country": { "id": 1, "name": "germany", "slug": "germany", "code": "DE" }
    },
    {
      "id": 132,
      "name": "Sarajevo",
      "slug": "sarajevo",
      "latitude": 43.8563,
      "longitude": 18.4131,
      "country": { "id": 5, "name": "bosnia", "slug": "bosnia", "code": "BA" }
    }
  ],
  "meta": { "data_version": "3.16" }
}

curl -H "api-key: YOUR_API_KEY" \
  https://api.vaktija.eu/v4/locations/7/today

{
  "status": "success",
  "data": {
    "date": "2026-10-30",
    "prayers": {
      "fajr": "05:13:00",
      "sunrise": "06:56:00",
      "dhuhr": "12:09:00",
      "asr": "14:42:00",
      "maghrib": "17:12:00",
      "isha": "18:42:00"
    },
    "location": {
      "id": 7,
      "name": "Ulm",
      "slug": "ulm",
      "timezone": "Europe/Berlin"
    }
  },
  "meta": { "data_version": "3.16" }
}

curl -H "api-key: YOUR_API_KEY" \
  https://api.vaktija.eu/v4/locations/7

{
  "status": "success",
  "data": {
    "id": 7,
    "name": "Ulm",
    "slug": "ulm",
    "latitude": 48.4011,
    "longitude": 9.9876,
    "timezone": "Europe/Berlin",
    "months": {
      "1": {
        "days": {
          "1": {
            "day": 1,
            "month": 1,
            "fajr": "06:20:00",
            "sunrise": "08:05:00",
            "dhuhr": "12:29:00",
            "asr": "14:22:00",
            "maghrib": "16:43:00",
            "isha": "18:13:00"
          },
          "2": {
            "day": 2,
            "month": 1,
            "fajr": "06:20:00",
            "sunrise": "08:05:00",
            "dhuhr": "12:29:00",
            "asr": "14:23:00",
            "maghrib": "16:44:00",
            "isha": "18:14:00"
          }
        }
      }
    }
  },
  "meta": { "data_version": "3.16" }
}

// The date at the location, which can differ from your server's date
const today = new Intl.DateTimeFormat('en-CA', { timeZone: data.timezone }).format(new Date())
const [, month, day] = today.split('-').map(Number)

const times = data.months[month].days[day]
console.log(times.fajr) // "06:20:00"

Times and time zones

• Times are the local time at the location, 24-hour HH:MM:SS, with summer time already applied. Show them as they are.
• timezone is the location's IANA time zone. You only need it to turn a time into an exact moment on a computer in another time zone, for example a server that sends push notifications.
• sunrise is not a prayer: it marks the end of the time for Fajr.

Caching and updates

Prayer times rarely change: when a community corrects its calendar, and once a year around the summer time changes. Please do not request the same data more often than you need it.

1. Fetch the full year of each of your locations once and store it.
2. Once a day, make one request, for example today's times of one of your locations, and compare meta.data_version with the value you stored. It is the same for every location, so one request a day is enough however many locations you have.
3. When data_version has changed, times were corrected: fetch the full year of each location again.
4. Work out today's times and the next prayer from your copy. Do not call the API every minute.
5. If the API cannot be reached, keep using your copy.

// Once a day, for all your locations together
const response = await fetch('https://api.vaktija.eu/v4/locations/7/today', {
  headers: { 'api-key': process.env.VAKTIJA_API_KEY },
})
const { meta } = await response.json()

if (meta.data_version !== stored.dataVersion) {
  // Times were corrected: fetch the full year of each location again
}

Treat data_version as text and only check whether it changed; do not compare it as a number.

Rate limits

300 requests per 30 seconds per IP address. Following the advice above, you will stay far below it. Every response carries:

Errors

Errors use the HTTP status code and a JSON body of the same shape. Decide on statusCode; the message is for people and may change.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key may not read this location"
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required (api-key header)"
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key may not read this location"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key may not use this route"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Cannot GET /v4/locations/7/tomorrow"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Internal server error"
}

Versioning

• This is version 4: every path starts with /v4.
• We may add fields to responses at any time. Ignore the ones you do not use.
• We do not remove or rename fields within a version. Breaking changes come as a new version, announced by email to everyone with a key.