# Aladhan Prayer Times API

Free REST API for Islamic prayer times worldwide. No API key required.

**Base URL:** `https://api.aladhan.com/v1`

## Key Endpoints

### By City
```
GET /timingsByCity?city=Vienna&country=Austria&method=13&latitudeAdjustmentMethod=2
```

### Parameters

| Parameter | Values | Notes |
|-----------|--------|-------|
| `method` | 3=MWL, 4=Umm al-Qura, 5=Egyptian, 13=Diyanet (Turkey) | Calculation method |
| `school` | 0=Hanafi, 1=Shafi (default) | Affects Asr time |
| `latitudeAdjustmentMethod` | 1=Midnight, 2=OneSeventh, 3=Angle-based | **Critical for high latitudes (>48°)** |
| `date` | `DD-MM-YYYY` | Omit for today |

## High-Latitude Problem

Cities above ~48°N (Vienna, Berlin, London) have no true astronomical twilight in summer — the sun never sinks 18° below the horizon. Standard calculation methods produce physically impossible Fajr/Isha times (e.g. Fajr at 02:31 when sunrise is 04:47).

**Solution:** `latitudeAdjustmentMethod=2` (OneSeventh of Night). This divides the night into 7 equal parts and places Fajr at the start of the last seventh, Isha at the end of the first seventh. Produces realistic times (Fajr ~1h before sunrise, Isha ~1h after sunset).

## Response Format

```json
{
  "data": {
    "timings": {
      "Fajr": "03:46",
      "Sunrise": "04:47",
      "Dhuhr": "13:00",
      "Asr": "17:15",
      "Maghrib": "21:04",
      "Isha": "22:05"
    },
    "date": { "readable": "16 Jun 2026" }
  }
}
```

## Tested Cities

| City | Method | LatAdj | Works? |
|------|--------|--------|--------|
| Vienna | 13 (Diyanet) | 2 (OneSeventh) | ✓ |
| Istanbul | 13 (Diyanet) | none needed | ✓ |

## Quick Test

```bash
curl -sL "https://api.aladhan.com/v1/timingsByCity/$(date +%d-%m-%Y)?city=Vienna&country=Austria&method=13&latitudeAdjustmentMethod=2" -H "User-Agent: curl/8" | python3 -c "
import json,sys
d=json.load(sys.stdin)['data']
print(d['date']['readable'])
for k in ['Fajr','Sunrise','Dhuhr','Asr','Maghrib','Isha']:
    print(f'  {k}: {d[\"timings\"][k]}')
"
```

## Pitfalls

- **302 Redirect without date:** Calling `/v1/timingsByCity` without a date path segment (e.g. `?city=Vienna&...`) returns HTTP 302. Always include the date: `/v1/timingsByCity/DD-MM-YYYY?city=...`
- **User-Agent required:** The API may reject requests without a `User-Agent` header. Always send at least `-H "User-Agent: curl/8"` or equivalent.
- **Node.js `https.get`:** When fetching from a Node.js server (no external deps), use `node:https` module. Parse the URL with `new URL(...)`, set `headers: { 'User-Agent': 'muslimos/1.0' }`, and collect chunks into a buffer before `JSON.parse`.