Moon visibility

The crescent-visibility data behind the moonsighting maps — a world zone grid for any evening of a Hijri month's sighting window, or per-location visibility with first-sighting dates under each criterion (Yallop/Shaukat, calibrated against moonsighting.com).

GET https://theshia.org/api/v1/moon-visibility

Parameters

hy default: current Hijri year, 1317 to 1523 — the lunation the maps are anchored to.
hm default: current Hijri month, 1 (Muharram) to 12 (Dhul Hijjah).
evening default: 0 -2 to 2 — which evening of the sighting window (0 = the sighting evening, the day before the month begins).
res default: 5 grid cell size in degrees — values: "5" (72×26 cells, AL-Qamar's native grid) · "2" (180×65 cells).
lat point mode latitude -90 to 90 — switches to a per-location response (with lng).
lng point mode longitude -180 to 180.
city point mode city id from /cities — alternative to lat & lng.

Grid response: rows of digit strings top-to-bottom, lat +70 to −60, lon −180 to +180; values: 0 not visible · 1 zone A (easily visible) · 2 zone B (perfect conditions) · 3 zone C (optical aid) · 4 zone D (telescope). Cell centers: lat = 70 − (row+0.5)·res, lon = −180 + (col+0.5)·res. Includes counts and a legend with the exact q-value thresholds.
Point response: q-value and zone for the seven evenings from conjunction, plus firstVisible dates under each criterion — AL-Qamar's first-sighting scan.
meta always includes the conjunction instant (UTC, ΔT-corrected), the month's start date and its source, and the sighting-evening date.
Identical to the maps on the moonsighting page — same engine, same calibration (the site renders 1° client-side; the API serves 5° and 2°).

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/moon-visibility?hy=1448&hm=2"

JavaScript

const res = await fetch("https://theshia.org/api/v1/moon-visibility?hy=1448&hm=2");
const data = await res.json();

Python

import requests

data = requests.get("https://theshia.org/api/v1/moon-visibility?hy=1448&hm=2").json()

Rate limits & fair use

Responses are cached hard at the edge — please cache on your side too. Uncached requests are limited to 100 per minute per IP; oversized requests (over 496 day×method computations) are rejected. Free for community use, no uptime guarantee.