dz-data-api

README

dz-data-api

A small, dependency-free REST API with public data about Algeria:

• Wilayas: all 58, with French, Arabic and English names and their capital's coordinates.
• Public holidays for any year. The civil holidays have fixed dates. The religious ones come from the tabular Hijri calendar and are clearly marked approximate.
• Prayer times, computed astronomically with the Ministry of Religious Affairs parameters (Fajr 18°, Isha 17°, standard Asr), for any wilaya capital or any coordinates.
• Hijri date conversion (tabular, approximate).

Every response carries a strong ETag, and If-None-Match gets a 304 Not Modified. There's an OpenAPI 3 spec at /openapi.yaml.

Who it's for

Algerian developers building apps that need a wilaya dropdown, a holiday calendar for leave or delivery planning, or prayer times, and who don't want to scrape PDFs or hard-code tables.

Install

Install the binary with Go (the data is embedded):

go install github.com/AbdeldjalilChougui/dz-data-api/cmd/dz-data-api@latest

Quick start

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

{
  "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"
}

Data sources and accuracy

data	source	accuracy
Wilayas	Curated list embedded in the binary (2019 territorial organisation: 48 + 10 new southern wilayas)	Names checked by hand. Capital coordinates are approximate city centres (about ±5 km)
Dairas, communes	Not included. /v1/dairas and /v1/communes return 501. They're meant to come from the sibling dz-geodata project, whose data isn't ready yet	—
Civil holidays	Law 63-278 as amended (Yennayer added by law 18-12)	exact
Religious holidays	Tabular Islamic calendar. The two Eids last 3 days each (law 23-10 of 26 June 2023)	approximate. The official dates follow the crescent sighting. The tests check 2023–2025 Eids, Islamic New Year and Mawlid against the observed dates (all within 2 days, usually 0–1)
Prayer times	Computed (USNO low-precision sun position, the PrayTimes.org approach)	Within ±2 minutes of published Algiers and Oran timetables (tested)

The territorial organisation can change (for example, 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 when the sun is 18° and 17° below the horizon. Sunrise and Maghrib use 0.833° (refraction plus the sun's radius). Asr is when the shadow equals the object's length plus its noon shadow. Times are refined once with the declination at the estimated time, then rounded to the minute. Algeria is UTC+1 all year.
• Hijri. This is the arithmetic 30-year cycle (11 leap years), converted 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 (sorted map keys), then hashed with SHA-256, so the same data always gets the same ETag and clients and CDNs can revalidate cheaply. If-None-Match handles lists, * and weak (W/) tags.

Tests

go test -race ./...

• Prayer times are compared with the October 2026 timetables for Algiers and Oran published by islamicprayerstimes.online ("Algerian Ministry of Religious Affairs" method), five dates per city with all six times each, and must be within ±2 minutes. 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, 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, ETag/304 behaviour, input validation, and the OpenAPI spec listing every route.

Status and limitations

• 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.
• Prayer times don't account for elevation or the ministry's precautionary minutes (ihtiyat), and there's no high-latitude adjustment (that isn't needed for Algeria; coordinates are limited to ±66°).
• The since field gives the reform that created a wilaya (1974, 1984 or 2019), not its exact legal date.

License

MIT. See LICENSE.