API - New Moon Day

Quick start

Base URL: https://moon.grafted.in/api/v1. Every endpoint is a plain GET that returns JSON.

curl https://moon.grafted.in/api/v1/moon

const res = await fetch("https://moon.grafted.in/api/v1/calendar");
const { today, feasts } = await res.json();
console.log(`Month ${today.month}, day ${today.day}`);

`/api/v1/moon`	The Moon now: phase, illumination, position, next rise and set.
`/api/v1/crescent`	Upcoming new moons, each with its first two sighting evenings: sunset, moonset, Odeh visibility zone and weather.
`/api/v1/calendar`	The Israel calendar: today's month and day, the month chain, feasts, aviv barley and the last reported sighting.
`/api/v1`	This list, as JSON.

Parameters

All are optional. Without lat and lon the observer is Jerusalem.

`lat`, `lon`	Observer in decimal degrees, north and east positive. Give both. Not used by `/calendar`, which is always Israel.
`tz`	IANA time zone for local times, such as `Europe/London`. Recommended with `lat`/`lon`: it handles daylight saving.
`utc_offset`	Fixed offset in hours, used when `tz` is absent. With neither, the offset is estimated from the longitude (15° per hour).
`name`	A label for the place, echoed back in `observer.name`.
`date`	`YYYY-MM-DD`, from 1900 to 2100. Answers as if it were noon UTC on that date instead of now.
`months`	`/crescent` only: how many new moons ahead to list, 1 to 12. Default 6.

curl "https://moon.grafted.in/api/v1/crescent?lat=51.5074&lon=-0.1278&tz=Europe/London&months=3"

Moon

GET/api/v1/moon

The Moon at this moment for the observer.

`phase`	Name of the phase, such as `Waxing Crescent`.
`phase_index`	0 New, 1 Waxing Crescent, 2 First Quarter, 3 Waxing Gibbous, 4 Full, 5 Waning Gibbous, 6 Last Quarter, 7 Waning Crescent.
`waxing`	`true` from new moon to full moon.
`illumination_percent`	Lit part of the disc, 0 to 100.
`age_days`, `age_hours`	Time since the last conjunction.
`cycle_fraction`	Age as a fraction of the mean synodic month (29.53 days), 0 to 1.
`above_horizon`	Whether the Moon is up: its upper edge above a flat horizon, allowing for standard refraction (the same rule as the rise and set times).
`altitude_deg`, `azimuth_deg`	Position in the sky. Azimuth is clockwise from north. Altitude is geometric (no refraction).
`apparent_altitude_deg`	Altitude as the eye sees it, with standard atmospheric refraction (1010 mb, 15 °C). Up to about 0.6° higher than `altitude_deg` near the horizon.
`compass`	The azimuth as a 16-point compass direction.
`limb_tilt_deg`	For drawing the Moon as it looks in the sky. Start from an upright phase (lit side right when waxing, left when waning) and rotate it clockwise by this angle.
`north_tilt_deg`	Where the Moon's north pole points in your sky. To draw surface features (a north-up Moon photo) the right way round, rotate the photo clockwise by this angle. It changes with your location and through the night; from the southern hemisphere it is near 180°.
`next_rise_`, `next_set_`	Next moonrise and moonset. `null` where the Moon does not rise or set (polar regions).
`previous_new_moon_utc`, `next_new_moon_utc`	The conjunctions on either side, to the minute.

Example response (live)

{
  "generated_utc": "2026-10-30T06:50:22Z",
  "as_of_utc": "2026-10-30T06:50:22Z",
  "observer": {
    "name": "Jerusalem",
    "latitude": 31.7683,
    "longitude": 35.2137,
    "elevation_m": 754,
    "timezone": "Asia/Jerusalem",
    "utc_offset_hours": 2.0
  },
  "moon": {
    "phase": "Waning Gibbous",
    "phase_index": 5,
    "waxing": false,
    "illumination_percent": 78.6,
    "age_days": 19.6,
    "age_hours": 471.0,
    "cycle_fraction": 0.6646,
    "above_horizon": true,
    "altitude_deg": 18.48,
    "apparent_altitude_deg": 18.53,
    "azimuth_deg": 290.95,
    "compass": "WNW",
    "limb_tilt_deg": 64.7,
    "north_tilt_deg": 63.1,
    "next_rise_utc": "2026-10-30T18:35:30Z",
    "next_rise_local": "2026-10-30T20:35:30+02:00",
    "next_set_utc": "2026-10-30T08:36:12Z",
    "next_set_local": "2026-10-30T10:36:12+02:00",
    "previous_new_moon_utc": "2026-10-10T15:50:00Z",
    "next_new_moon_utc": "2026-11-09T07:02:00Z"
  }
}

Crescent

GET/api/v1/crescent

new_moons lists the coming conjunctions. For two days after a conjunction, while its crescent is still being looked for, that one stays at the top of the list with in_sighting_window: true.

`conjunction_*`	The astronomical new moon.
`days_until`	Whole days from today to the conjunction (negative once past).
`in_sighting_window`	The conjunction has passed and its crescent is being watched for.
`first_naked_eye_evening`	The first of the two evenings in zone A or B, or `null` if neither is.
`evenings`	Two evenings: the first sunset after the conjunction (the same day if the conjunction is before local noon, otherwise the next) and the one after it.

An evening

`date`	The date of the sunset.
`sunset_`, `moonset_`	`null` where the Sun or Moon does not set that day.
`best_time_*`	Best moment to look: sunset plus 4/9 of the lag. Equals sunset when the Moon sets first.
`lag_minutes`	Moonset minus sunset. Negative when the Moon sets before the Sun.
`moon_age_hours`	Time from conjunction to sunset.
`odeh.zone`	Odeh (2006) visibility zone at the best time: `A` easily visible to the naked eye, `B` visible under perfect conditions, `C` may need optical aid to find, `D` not visible even with optical aid.
`odeh.v`	Odeh's V value. A ≥ 5.65, B ≥ 2.00, C ≥ −0.96, D below.
`odeh.arcv_deg`	Arc of vision: Moon altitude minus Sun altitude.
`odeh.arcl_deg`	Arc of light: Sun–Moon separation.
`odeh.daz_deg`	Difference in azimuth between Sun and Moon.
`odeh.width_arcmin`	Topocentric crescent width W.
`odeh.moon_altitude_deg`, `moon_azimuth_deg`, `sun_altitude_deg`	Positions at the best time, without refraction.
`weather`	See below. `null` when there is no best time.

Weather

Advisory only: it never changes a date. Values are for the hour nearest the best time, taking the worse of the observer's position and a point 25 km toward the setting Moon. When available is false, reason is beyond_forecast_range (with forecast_from, the date a forecast will first exist) or unavailable.

`source`	`forecast`, or `recorded` for a past evening.
`long_range`	A forecast 7 or more days ahead: treat it as a rough guide.
`hour_utc`	The hour the values are for.
`sky`, `sky_label`	`clear`, `fair`, `poor` or `bad`, and the same in words.
`sighting_chance`, `sighting_chance_label`	Zone and sky combined: `good`, `possible`, `unlikely`, `very-unlikely`, `optics` (binoculars only) or `no`.
`cloud_cover_percent`, `cloud_low_percent`, `cloud_mid_percent`, `cloud_high_percent`	Total cloud and the three layers.
`visibility_km`	Horizontal visibility.
`precipitation_probability_percent`, `precipitation_mm`	Rain in that hour.
`humidity_percent`	Relative humidity at the observer.
`dust_ug_m3`, `aerosol_optical_depth`	Dust and haze. `null` more than 5 days ahead.

Example response (live, one new moon)

{
  "generated_utc": "2026-10-30T06:50:22Z",
  "as_of_utc": "2026-10-30T06:50:22Z",
  "observer": {
    "name": "Jerusalem",
    "latitude": 31.7683,
    "longitude": 35.2137,
    "elevation_m": 754,
    "timezone": "Asia/Jerusalem",
    "utc_offset_hours": 2.0
  },
  "new_moons": [
    {
      "conjunction_utc": "2026-11-09T07:02:03Z",
      "conjunction_local": "2026-11-09T09:02:03+02:00",
      "days_until": 10,
      "in_sighting_window": false,
      "first_naked_eye_evening": null,
      "evenings": [
        {
          "date": "2026-11-09",
          "sunset_utc": "2026-11-09T14:43:33Z",
          "sunset_local": "2026-11-09T16:43:33+02:00",
          "moonset_utc": "2026-11-09T14:30:54Z",
          "moonset_local": "2026-11-09T16:30:54+02:00",
          "best_time_utc": "2026-11-09T14:43:33Z",
          "best_time_local": "2026-11-09T16:43:33+02:00",
          "lag_minutes": -12.7,
          "moon_age_hours": 7.7,
          "odeh": {
            "zone": "D",
            "description": "Not visible even with optical aid",
            "v": -8.905,
            "arcv_deg": -2.33,
            "arcl_deg": 6.43,
            "daz_deg": 6.0,
            "width_arcmin": 0.09,
            "moon_altitude_deg": -3.17,
            "moon_azimuth_deg": 244.5,
            "sun_altitude_deg": -0.84
          },
          "weather": {
            "available": true,
            "source": "forecast",
            "long_range": true,
            "hour_utc": "2026-11-09T15:00:00Z",
            "sky": "poor",
            "sky_label": "Cloudy or hazy",
            "sighting_chance": "no",
            "sighting_chance_label": "None — too close to the Sun",
            "cloud_cover_percent": 42,
            "cloud_low_percent": 52,
            "cloud_mid_percent": 3,
            "cloud_high_percent": 0,
            "visibility_km": 25,
            "precipitation_probability_percent": 27,
            "precipitation_mm": 0.0,
            "humidity_percent": 60,
            "dust_ug_m3": null,
            "aerosol_optical_depth": null
          }
        },
        {
          "date": "2026-11-10",
          "sunset_utc": "2026-11-10T14:42:53Z",
          "sunset_local": "2026-11-10T16:42:53+02:00",
          "moonset_utc": "2026-11-10T15:11:14Z",
          "moonset_local": "2026-11-10T17:11:14+02:00",
          "best_time_utc": "2026-11-10T14:55:30Z",
          "best_time_local": "2026-11-10T16:55:30+02:00",
          "lag_minutes": 28.4,
          "moon_age_hours": 31.7,
          "odeh": {
            "zone": "C",
            "description": "May need optical aid to find",
            "v": 1.36,
            "arcv_deg": 5.32,
            "arcl_deg": 15.43,
            "daz_deg": 14.49,
            "width_arcmin": 0.54,
            "moon_altitude_deg": 1.95,
            "moon_azimuth_deg": 237.3,
            "sun_altitude_deg": -3.37
          },
          "weather": {
            "available": true,
            "source": "forecast",
            "long_range": true,
            "hour_utc": "2026-11-10T15:00:00Z",
            "sky": "poor",
            "sky_label": "Cloudy or hazy",
            "sighting_chance": "no",
            "sighting_chance_label": "None",
            "cloud_cover_percent": 52,
            "cloud_low_percent": 0,
            "cloud_mid_percent": 44,
            "cloud_high_percent": 44,
            "visibility_km": 29,
            "precipitation_probability_percent": 34,
            "precipitation_mm": 0.0,
            "humidity_percent": 48,
            "dust_ug_m3": null,
            "aerosol_optical_depth": null
          }
        }
      ]
    }
  ]
}

Calendar

GET/api/v1/calendar

The biblical calendar as kept on this site: a month begins when the crescent is sighted in Israel. A month is reported when a sighting has been recorded for it, and estimated otherwise — estimated dates can still move by a day. The About page explains the rules.

Days begin at sunset. Every *_evening field is the Gregorian date of the sunset at which something begins or ends.

`today`

`date`	Today's date in Jerusalem.
`month`	Month number. Month 1 is Aviv; a leap year has a month 13.
`day`	Day of the month whose daytime falls on `date`. The next day begins at sunset. `0` means the month begins at sunset today.
`month_status`	`reported` or `estimated`.
`month_began_evening`	The sunset at which this month began.

`next_month_watch`

The two evenings that decide the next month, day_29 and day_30 of the current one, each a full evening with weather. If the crescent is seen on day 29 the next month begins that evening; otherwise it begins on day 30.

`months`

The previous month, the current one and the twelve after it.

`month`	Month number, 1 to 13.
`begins_evening`	The sunset at which the month begins.
`first_day`	The daytime date of day 1 (the day after `begins_evening`).
`status`	`reported` or `estimated`.
`may_begin_a_day_later`	An estimated month expected to begin on day 29 of the previous one, which slips a day if the crescent is missed.
`length_days`	29 or 30. An estimate until the following month is reported. `null` for the last month listed.
`year_rule`	Set on a month 1 or 13 (otherwise `null`): how the year was decided. `set` by the admin on a report, `barley` aviv barley found, `not_aviv` barley not ready so a 13th month, `equinox` estimated so that Passover falls on or after the spring equinox, `after_13` follows a 13th month.
`awaiting_barley`	A future month 1 or 13 that rests on the equinox estimate and may change with the barley report.
`current`	The month `today` is in.
`watch`	The evenings that decide this month's start: `day_29` and `day_30` of the month before, each with `date` and Odeh `zone` for Jerusalem.

`feasts`

The feasts of the current biblical year (Leviticus 23, and the Head of the Year). Next year's appear once this year's Eighth Day has passed. While fall_feasts_pending is true, the fall feasts are left out because the year's first month is not decided yet.

`key`	Stable identifier: `head`, `passover`, `unleavened`, `firstfruits`, `shavuot`, `trumpets`, `atonement`, `tabernacles`, `eighth`.
`name`, `hebrew_name`, `reference`	Names and the Scripture reference.
`biblical_date`	Month/day, such as `7/10`, or the rule for First Fruits and Shavuot.
`begins_evening`	The feast begins at sunset on this date. Passover is the exception: it is at twilight on this date, at the end of the 14th.
`ends_evening`	The feast ends at sunset on this date.
`days`	Length in days.
`status`	`confirmed` when its month was reported, else `estimated`.
`may_begin_a_day_later`	As for its month.
`in_progress`, `past`	Under way now, or over.
`days_until`	Days from today to `begins_evening` (negative once begun).

Other fields

`aviv_barley`	`in_season` is `true` in months 11, 12, 13 and 1. `report` is the latest inspection, with `date` and `status` (`aviv` or `not_aviv`), or `null`.
`last_sighting`	The most recent reported sighting: `evening`, and `location` and `time_local` where recorded. `null` if none is on record.

Example response (live, lists shortened)

{
  "generated_utc": "2026-10-30T06:50:22Z",
  "as_of_utc": "2026-10-30T06:50:22Z",
  "observer": {
    "name": "Jerusalem",
    "latitude": 31.7683,
    "longitude": 35.2137,
    "elevation_m": 754,
    "timezone": "Asia/Jerusalem",
    "utc_offset_hours": 2.0
  },
  "today": {
    "date": "2026-10-30",
    "month": 8,
    "day": 18,
    "month_status": "estimated",
    "month_began_evening": "2026-10-12"
  },
  "next_month_watch": {
    "day_29": {
      "date": "2026-11-10",
      "sunset_utc": "2026-11-10T14:42:53Z",
      "sunset_local": "2026-11-10T16:42:53+02:00",
      "moonset_utc": "2026-11-10T15:11:14Z",
      "moonset_local": "2026-11-10T17:11:14+02:00",
      "best_time_utc": "2026-11-10T14:55:30Z",
      "best_time_local": "2026-11-10T16:55:30+02:00",
      "lag_minutes": 28.4,
      "moon_age_hours": 31.7,
      "odeh": {
        "zone": "C",
        "description": "May need optical aid to find",
        "v": 1.36,
        "arcv_deg": 5.32,
        "arcl_deg": 15.43,
        "daz_deg": 14.49,
        "width_arcmin": 0.54,
        "moon_altitude_deg": 1.95,
        "moon_azimuth_deg": 237.3,
        "sun_altitude_deg": -3.37
      },
      "weather": {
        "available": true,
        "source": "forecast",
        "long_range": true,
        "hour_utc": "2026-11-10T15:00:00Z",
        "sky": "poor",
        "sky_label": "Cloudy or hazy",
        "sighting_chance": "no",
        "sighting_chance_label": "None",
        "cloud_cover_percent": 52,
        "cloud_low_percent": 0,
        "cloud_mid_percent": 44,
        "cloud_high_percent": 44,
        "visibility_km": 29,
        "precipitation_probability_percent": 34,
        "precipitation_mm": 0.0,
        "humidity_percent": 48,
        "dust_ug_m3": null,
        "aerosol_optical_depth": null
      }
    },
    "day_30": {
      "date": "2026-11-11",
      "sunset_utc": "2026-11-11T14:42:14Z",
      "sunset_local": "2026-11-11T16:42:14+02:00",
      "moonset_utc": "2026-11-11T15:56:51Z",
      "moonset_local": "2026-11-11T17:56:51+02:00",
      "best_time_utc": "2026-11-11T15:15:24Z",
      "best_time_local": "2026-11-11T17:15:24+02:00",
      "lag_minutes": 74.6,
      "moon_age_hours": 55.7,
      "odeh": {
        "zone": "A",
        "description": "Easily visible to the naked eye",
        "v": 14.776,
        "arcv_deg": 13.67,
        "arcl_deg": 26.14,
        "daz_deg": 22.34,
        "width_arcmin": 1.52,
        "moon_altitude_deg": 6.13,
        "moon_azimuth_deg": 231.7,
        "sun_altitude_deg": -7.54
      },
      "weather": {
        "available": true,
        "source": "forecast",
        "long_range": true,
        "hour_utc": "2026-11-11T15:00:00Z",
        "sky": "bad",
        "sky_label": "Overcast, rain or dust",
        "sighting_chance": "very-unlikely",
        "sighting_chance_label": "Very unlikely",
        "cloud_cover_percent": 79,
        "cloud_low_percent": 53,
        "cloud_mid_percent": 44,
        "cloud_high_percent": 23,
        "visibility_km": 16,
        "precipitation_probability_percent": 31,
        "precipitation_mm": 1.6,
        "humidity_percent": 60,
        "dust_ug_m3": null,
        "aerosol_optical_depth": null
      }
    }
  },
  "months": [
    {
      "month": 7,
      "begins_evening": "2026-09-12",
      "first_day": "2026-09-13",
      "status": "reported",
      "may_begin_a_day_later": false,
      "length_days": 30,
      "year_rule": null,
      "awaiting_barley": false,
      "current": false,
      "watch": {
        "day_29": {
          "date": "2026-09-12",
          "zone": "B"
        },
        "day_30": {
          "date": "2026-09-13",
          "zone": "A"
        }
      }
    },
    {
      "month": 8,
      "begins_evening": "2026-10-12",
      "first_day": "2026-10-13",
      "status": "estimated",
      "may_begin_a_day_later": false,
      "length_days": 30,
      "year_rule": null,
      "awaiting_barley": false,
      "current": true,
      "watch": {
        "day_29": {
          "date": "2026-10-11",
          "zone": "D"
        },
        "day_30": {
          "date": "2026-10-12",
          "zone": "A"
        }
      }
    }
  ],
  "feasts": [
    {
      "key": "head",
      "name": "Head of the Year",
      "hebrew_name": "Rosh Chodesh Aviv",
      "reference": "Exod. 12:2",
      "biblical_date": "1/1",
      "begins_evening": "2027-03-09",
      "ends_evening": "2027-03-10",
      "days": 1,
      "status": "estimated",
      "may_begin_a_day_later": false,
      "in_progress": false,
      "past": false,
      "days_until": 130
    },
    {
      "key": "passover",
      "name": "Passover",
      "hebrew_name": "Pesach",
      "reference": "Lev. 23:5",
      "biblical_date": "1/14",
      "begins_evening": "2027-03-23",
      "ends_evening": "2027-03-23",
      "days": 1,
      "status": "estimated",
      "may_begin_a_day_later": false,
      "in_progress": false,
      "past": false,
      "days_until": 144
    }
  ],
  "fall_feasts_pending": true,
  "aviv_barley": {
    "in_season": false,
    "report": null
  },
  "last_sighting": {
    "evening": "2026-09-12",
    "location": "Gilo, Jerusalem",
    "time_local": "19:10"
  }
}

Conventions

Times ending in _utc are ISO 8601 in UTC, such as 2026-11-10T14:52:30Z.
Times ending in _local are the same instant with the observer's UTC offset, such as 2026-11-10T16:52:30+02:00.
Dates are YYYY-MM-DD.
Every response has generated_utc (when it was calculated), as_of_utc (the moment it describes) and observer.
A value that does not apply is null; the field is still present.
Errors use the matching HTTP status and this body: {"error": {"code": "invalid_parameter", "message": "..."}}. Codes: invalid_parameter (400), not_found (404), rate_limited (429).
Versioning: within v1, fields keep their names and meaning. New fields may be added, so ignore ones you do not know.

Limits

No key or sign-up.
CORS is open (Access-Control-Allow-Origin: *), so browser code on any site can call it.
Responses are cached for 60 seconds; asking more often returns the same answer.
60 requests per 60 seconds per IP address. Beyond that you get 429 with a Retry-After header.

Terms

Free to use. A link back to moon.grafted.in is appreciated.
Weather, dust and haze values come from Open-Meteo (CC BY 4.0). If you show them, credit Open-Meteo.
Visibility predictions are calculations, and estimated calendar dates change when a sighting is reported. The service comes with no guarantee of accuracy or availability.
The older /data.json still works and mirrors the Data tab, but its shape can change. Build on /api/v1.