Heliacal Events

Find the next heliacal rising or setting of a planet — the moment it first becomes visible in the morning or evening sky. Uses the Schaefer sky brightness model with configurable atmospheric and observer parameters.

Text

GET  /v1/heliacal
POST /v1/heliacal

Credit cost: 3

Parameters

Parameter	Type	Required	Default	Description
`datetime`	string	One of `datetime` or `jd`	—	ISO 8601 UTC datetime
`jd`	number	One of `datetime` or `jd`	—	Julian Day in UT1
`body`	string	Yes	—	Planet name (not sun or moon)
`event`	string	Yes	—	Event type (see below)
`lat`	number	Yes	—	Observer latitude
`lon`	number	Yes	—	Observer longitude
`alt`	number	No	0	Observer altitude in meters
`pressure_mbar`	number	No	1013.25	Atmospheric pressure
`temp_celsius`	number	No	15.0	Temperature
`humidity_pct`	number	No	40.0	Relative humidity (0–100)
`visibility_range_km`	number	No	0.0	Visibility range (0 = model default)
`age_years`	number	No	36.0	Observer age
`snellen_ratio`	number	No	1.0	Visual acuity (1.0 = normal)
`binoculars`	boolean	No	`true`	Binocular vision
`telescope_aperture_cm`	number	No	0.0	Telescope aperture (0 = naked eye)
`telescope_magnification`	number	No	1.0	Telescope magnification

Event types

Event	Description	Applies to
`morning_first`	First visible in morning sky (heliacal rising)	All eligible bodies
`evening_last`	Last visible in evening sky	All eligible bodies
`evening_first`	First visible in evening sky	Inner planets only (Mercury, Venus)
`morning_last`	Last visible in morning sky	Inner planets only
`acronychal_rising`	Rising at sunset	All eligible bodies
`acronychal_setting`	Setting at sunrise	All eligible bodies

Body restrictions: Sun and Moon are excluded. Outer planets (Jupiter–Pluto) cannot have evening_first or morning_last events.

Response

JSON

{
  "data": {
    "body": "venus",
    "event": "morning_first",
    "event_jd": 2460350.284,
    "event_datetime": "2024-02-05T18:49:00.000Z",
    "visibility_arc_deg": 12.45,
    "sun_altitude": -8.23,
    "object_altitude": 4.22
  },
  "meta": { "..." }
}

Field	Type	Description
`body`	string	Body identifier
`event`	string	Event type
`event_jd`	number	Julian Day of the event
`event_datetime`	string	ISO 8601 datetime of the event
`visibility_arc_deg`	number	Arc between Sun and object at event
`sun_altitude`	number	Sun's altitude at event (degrees)
`object_altitude`	number	Object's altitude at event (degrees)

Examples

Venus heliacal rising from New York

Bash

curl "https://api.morphemeris.com/v1/heliacal?datetime=2024-01-01T00:00:00Z&body=venus&event=morning_first&lat=40.7128&lon=-74.006" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/heliacal?datetime=2024-01-01T00:00:00Z&body=venus&event=morning_first&lat=40.7128&lon=-74.006",
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/heliacal",
    params={
        "datetime": "2024-01-01T00:00:00Z",
        "body": "venus",
        "event": "morning_first",
        "lat": 40.7128,
        "lon": -74.006,
    },
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Custom atmospheric conditions

Bash

curl "https://api.morphemeris.com/v1/heliacal?datetime=2024-01-01T00:00:00Z&body=mars&event=morning_first&lat=40.7128&lon=-74.006&pressure_mbar=1000&temp_celsius=20&humidity_pct=60" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

Heliacal Events

Heliacal Events

Parameters

Event types

Response

Examples

Venus heliacal rising from New York

Custom atmospheric conditions

On this page