DEV Community

Cover image for dz-data-api: a small REST API for wilayas, holidays and prayer times in Algeria
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

dz-data-api: a small REST API for wilayas, holidays and prayer times in Algeria

Many apps built for Algeria need the same few pieces of data. A sign-up form needs a wilaya dropdown. A leave or delivery planner needs the public holidays of the year. A community or mosque app needs prayer times. None of this is hard to find for a person, but for a program it usually means copying a table out of a PDF, pasting it into the code, and fixing it by hand the day someone reports a mistake.

dz-data-api puts that data behind a small REST API. It is written in Go with no dependencies, and the data is embedded in the binary. The README describes the audience plainly: Algerian developers building apps that need a wilaya dropdown, a holiday calendar for leave or delivery planning, or prayer times, and who do not want to scrape PDFs or hard-code tables.

What I like to point out first is that the project says how accurate each piece of data is. Some of it is exact, some of it is computed, and some of it is an approximation that is labelled as one.

What it does

Wilayas. All 58, with French, Arabic and English names and the coordinates of their capital. The list follows the 2019 territorial organisation: 48 wilayas plus the 10 new southern ones. A since field gives the reform that created each wilaya (1974, 1984 or 2019).

Public holidays for any year. The civil holidays have fixed dates, taken from law 63-278 as amended, with Yennayer added by law 18-12. The religious holidays come from the tabular Hijri calendar and are clearly marked approximate. The two Eids last 3 days each, following law 23-10 of 26 June 2023.

Prayer times. They are computed astronomically with the Ministry of Religious Affairs parameters: Fajr at 18°, Isha at 17°, and standard Asr. You can ask for any wilaya capital or for any coordinates.

Hijri date conversion. Tabular, and therefore approximate.

HTTP done properly. Every response carries a strong ETag, and a request with If-None-Match gets a 304 Not Modified. There is an OpenAPI 3 spec at /openapi.yaml.

How to use it

Install the binary with Go. The data is embedded, so there is nothing else to download:

go install github.com/AbdeldjalilChougui/dz-data-api/cmd/dz-data-api@latest
Enter fullscreen mode Exit fullscreen mode

Or run it from a checkout and try the endpoints:

go run ./cmd/dz-data-api -addr :8080

curl localhost:8080/v1/wilayas/16
curl 'localhost:8080/v1/holidays?year=2027'
curl 'localhost:8080/v1/prayer-times?wilaya=31&date=2026-10-17'
curl 'localhost:8080/v1/prayer-times?lat=36.36&lon=6.61'
curl 'localhost:8080/v1/hijri?date=2026-10-17'
curl -i -H 'If-None-Match: "…"' localhost:8080/v1/wilayas   # → 304
Enter fullscreen mode Exit fullscreen mode

A prayer-times response looks like this:

{
  "date": "2026-10-17",
  "method": { "name": "Algeria (Ministry of Religious Affairs)", "fajr_angle": 18, "isha_angle": 17, "asr": "standard (shadow factor 1)" },
  "place": { "wilaya": 16, "name": "Alger", "latitude": 36.754, "longitude": 3.059 },
  "times": { "fajr": "05:31", "sunrise": "06:57", "dhuhr": "12:33", "asr": "15:42", "maghrib": "18:09", "isha": "19:30" },
  "timezone": "UTC+01:00"
}
Enter fullscreen mode Exit fullscreen mode

The response states the method and the place it used, so a client can show where the numbers come from.

Data sources and accuracy

This section of the README is the one to read before you depend on the API.

  • Wilayas come from a curated list embedded in the binary. The names were checked by hand. The capital coordinates are approximate city centres, about ±5 km.
  • Civil holidays are exact.
  • Religious holidays are approximate. The official dates follow the crescent sighting, and a tabular calendar cannot know that in advance. The tests check the 2023 to 2025 Eids, Islamic New Year and Mawlid against the observed dates: all are within 2 days, usually 0 or 1.
  • Prayer times are computed from a low-precision sun position (the USNO formulas, the approach used by PrayTimes.org). They are within ±2 minutes of published Algiers and Oran timetables, and that is tested.
  • Dairas and communes are not included. /v1/dairas and /v1/communes return 501. They are meant to come from a sibling project, dz-geodata, whose data is not ready yet.

The README adds a warning that applies to any list of this kind: the territorial organisation can change, for example with a new reform creating more wilayas. Check the list against the latest official texts before relying on it for administrative work.

How it works

Prayer times. For each date, the sun's declination and the equation of time are computed from the Julian day. Dhuhr is solar noon. Fajr and Isha are the moments when the sun is 18° and 17° below the horizon. Sunrise and Maghrib use 0.833°, which accounts for refraction plus the sun's radius. Asr is when the shadow of an object equals its length plus its noon shadow. The times are refined once with the declination at the estimated time, then rounded to the minute. Algeria is UTC+1 all year, so there is no daylight-saving logic.

Hijri. The conversion uses the arithmetic 30-year cycle, with 11 leap years, and goes through Julian Day Numbers. The tests do a round trip on every day from 1950 to 2100, and check that consecutive days advance by exactly one Hijri day.

ETags. The JSON is rendered deterministically, with sorted map keys, then hashed with SHA-256. The same data therefore always gets the same ETag, and clients and CDNs can revalidate cheaply. If-None-Match handles lists, * and weak (W/) tags.

Things to know

  • Wilaya level only. There are no dairas or communes until dz-geodata ships, and no postal codes.
  • Religious holiday dates are predictions. For official dates, wait for the Ministry's announcement. An app that shows them should label them as expected dates.
  • Prayer times have known gaps. They do not account for elevation or for the ministry's precautionary minutes (ihtiyat). There is no high-latitude adjustment, which is not needed for Algeria, and coordinates are limited to ±66°.
  • since is a reform year. It gives the reform that created a wilaya, not its exact legal date.
  • What was tested. go test -race ./... compares prayer times with the October 2026 timetables for Algiers and Oran published by islamicprayerstimes.online under the "Algerian Ministry of Religious Affairs" method: five dates per city, all six times each, within ±2 minutes. The README notes that the ministry's own site (marw.gov.dz) was down when the reference was collected. In practice the computed times are usually 1 minute off: Fajr and sunrise a minute later, and Asr, Maghrib and Isha a minute, sometimes two, earlier. That suggests the reference applies a small precaution offset or a different rounding. The other tests cover the holiday rules, the Hijri calendar, the wilaya data, the ETag and 304 behaviour, input validation, and the OpenAPI spec listing every route.

Why I built it

The problem is the one in the README: apps for Algeria keep needing wilayas, holidays and prayer times, and the alternatives are scraping PDFs or hard-coding tables. A hard-coded table works on the day it is written. It then lives in one app, gets copied into the next one, and nobody knows which copy was corrected.

Putting the data behind one small service, with the sources and the accuracy written next to each dataset, makes it possible to fix a mistake once. Computing the prayer times instead of storing timetables means the API answers for any date and any coordinates, not only for the cities and months someone typed in. And being honest about approximation matters here more than in most projects. A religious holiday that depends on a crescent sighting cannot be exact in advance, and a prayer time within two minutes of a timetable is not the timetable. The API says so in its responses and its documentation, so the developer using it can decide how to present the data.

Strong ETags are there because this data changes rarely. A client that already has the wilaya list should be able to confirm it with a 304 and move on.

Get the code

The source, the embedded data, the OpenAPI spec and the tests are on GitHub: https://github.com/AbdeldjalilChougui/dz-data-api. It is MIT licensed. Issues and pull requests are welcome, especially corrections to the data.


Originally published at abdeldjalilchougui.biz.

Top comments (0)