Offline observational astronomy: positions, rise/set, moon phases, eclipses, and seasons.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Search forward from a start time for the next occurrences of one sky-event class, selected by the `event` enum: solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, or perigee_apogee. Both eclipse classes take an optional observer (latitude and longitude together). solar_eclipse without one returns global eclipses — kind, peak time, obscuration, and for a total or annular eclipse the latitude/longitude where it is greatest; with one it returns only eclipses visible from that point, with local contact times, `local_visible`, and the Sun's altitude at each contact. lunar_eclipse returns geocentric contact times, the same instants everywhere on Earth; an observer adds `local_visible` and the Moon's altitude at each contact. Every other class is geocentric and ignores a location. The body-relative events (opposition, conjunction, max_elongation, perigee_apogee) require a `body`: opposition applies to the superior planets (mars through pluto), conjunction to any planet, max_elongation to mercury and venus, and perigee_apogee to the moon (perigee/apogee), earth, or a planet (perihelion/aphelion). conjunction with `body` alone is that planet's conjunction with the Sun. Add `body2` for a conjunction of two bodies — the Moon or a planet with another: the instant they share one ecliptic longitude seen from Earth's center, with their `separation_degrees` at that instant. That separation is not always their closest approach, since two planets can pass closer days or weeks away, and listings that time conjunctions by right ascension differ by hours, or by days for slow pairs. Returns the next `count` occurrences (default 1), up to 20 per call: a larger `count`, up to 200, returns the first 20 and a notice naming the exact `start` and `count` that continue the series. Searches stop at the end of 2100, the close of the supported span; when that leaves fewer than `count`, a notice says so. Start defaults to now; pass an IANA `timezone` for observer-local timestamps.
Which class of event to search for.
Target body — required for opposition, conjunction, max_elongation, and perigee_apogee; ignored otherwise. "earth" is accepted only for perigee_apogee, which returns its perihelion and aphelion. With `body2`, the Moon or a planet.
Second body for a conjunction of two bodies: the Moon or a planet, different from `body`. Accepted only with event "conjunction", where it replaces the conjunction of `body` with the Sun by the conjunction of `body` and `body2` in ecliptic longitude seen from Earth's center. For the Moon meeting the Sun, search moon_quarter for the new moon.
Number of forward occurrences to return. Default 1. At most 20 are computed per call; a count up to 200 returns the first 20 with a notice naming the `start` and `count` that continue the series.
Search start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Eclipses are included when their peak is at or after start; earlier contacts may still be returned. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process.
Observer latitude in decimal degrees, supplied together with longitude. Optional for solar_eclipse and lunar_eclipse, where it adds local circumstances; omit both for a global solar search. Ignored by every other event.
IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only.
Observer elevation in meters above sea level. Default 0.
Observer longitude in decimal degrees, supplied together with latitude. Optional for solar_eclipse and lunar_eclipse; ignored by every other event.
Tool list last changed Oct 25, 2026.
Search forward from a start time for the next occurrences of one sky-event class, selected by the `event` enum: solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, or perigee_apogee. Both eclipse classes take an optional observer (latitude and longitude together). solar_eclipse without one returns global eclipses — kind, peak time, obscuration, and for a total or annular eclipse the latitude/longitude where it is greatest; with one it returns only eclipses visible from that point, with local contact times, `local_visible`, and the Sun's altitude at each contact. lunar_eclipse returns geocentric contact times, the same instants everywhere on Earth; an observer adds `local_visible` and the Moon's altitude at each contact. Every other class is geocentric and ignores a location. The body-relative events (opposition, conjunction, max_elongation, perigee_apogee) require a `body`: opposition applies to the superior planets (mars through pluto), conjunction to any planet, max_elongation to mercury and venus, and perigee_apogee to the moon (perigee/apogee), earth, or a planet (perihelion/aphelion). conjunction with `body` alone is that planet's conjunction with the Sun. Add `body2` for a conjunction of two bodies — the Moon or a planet with another: the instant they share one ecliptic longitude seen from Earth's center, with their `separation_degrees` at that instant. That separation is not always their closest approach, since two planets can pass closer days or weeks away, and listings that time conjunctions by right ascension differ by hours, or by days for slow pairs. Returns the next `count` occurrences (default 1), up to 20 per call: a larger `count`, up to 200, returns the first 20 and a notice naming the exact `start` and `count` that continue the series. Searches stop at the end of 2100, the close of the supported span; when that leaves fewer than `count`, a notice says so. Start defaults to now; pass an IANA `timezone` for observer-local timestamps.
| Argument | Type | Description |
|---|---|---|
| body | string | Target body — required for opposition, conjunction, max_elongation, and perigee_apogee; ignored otherwise. "earth" is accepted only for perigee_apogee, which returns its perihelion and aphelion. With `body2`, the Moon or a planet. |
| body2 | string | Second body for a conjunction of two bodies: the Moon or a planet, different from `body`. Accepted only with event "conjunction", where it replaces the conjunction of `body` with the Sun by the conjunction of `body` and `body2` in ecliptic longitude seen from Earth's center. For the Moon meeting the Sun, search moon_quarter for the new moon. |
| count | integer | Number of forward occurrences to return. Default 1. At most 20 are computed per call; a count up to 200 returns the first 20 with a notice naming the `start` and `count` that continue the series. |
| event* | string | Which class of event to search for. |
| start | string | Search start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Eclipses are included when their peak is at or after start; earlier contacts may still be returned. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
| latitude | number | Observer latitude in decimal degrees, supplied together with longitude. Optional for solar_eclipse and lunar_eclipse, where it adds local circumstances; omit both for a global solar search. Ignored by every other event. |
| timezone | string | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| elevation | number |
Fetch a time-series ephemeris for a small body (asteroid or comet) or spacecraft from JPL Horizons — RA/Dec, distance, and apparent magnitude over a span, optionally with observer-relative altitude/azimuth. This covers objects the in-process major-body set cannot. The designation is passed to Horizons verbatim, so it must be in a form Horizons resolves to a single record: a numbered asteroid takes a trailing-semicolon record lookup (e.g. "433;" for Eros, "1;" for Ceres), and a periodic comet takes the DES + closest-apparition form (e.g. "DES=1P;CAP" for Halley). Spacecraft take their negative SPK-ID. Anything else goes through the Horizons name search: a bare name matching nothing (e.g. "433 Eros") or several records (e.g. "1P/Halley") is rejected, but one matching a single object succeeds even when that object is not the one meant — "Eros" resolves to Kerberos, a moon of Pluto — so compare `target_name`, the object Horizons resolved, with the one intended. A major-body name matching several bodies (e.g. "Mars") is rejected with the ID number of each body it matched — pass one, such as "499" for the planet. `start` and `stop` are ISO 8601 UTC dates in the Gregorian calendar, extended before 1582, in years 0100 through 9999; `stop` must not be before `start`, and a `stop` equal to `start` returns the single row at that instant. `step` is a count plus a unit of m, h, d, mo, or y, such as "1d", "1h", or "10m". Supplying observer latitude/longitude yields topocentric coordinates and adds alt/az — supply both or neither. This is a gated, network-backed extension (JPL Horizons is keyless but rate-limited and best-effort); large spans truncate inline at 200 rows, and the truncation notice names the exact `start` to resume from — one step past the last row returned, because Horizons includes the start instant in its output — so re-calling from there continues the series without repeating a sample. Splitting the range into smaller adjacent spans works too; keep the same step either way so no sample is lost.
| Argument | Type | Description |
|---|---|---|
| step | string | Step size as a positive count up to 2147483647 plus a unit of m (minutes), h (hours), d (days), mo (months), or y (years), e.g. "10m", "1h", "1d". Default "1h". |
Report the Moon phase for an instant: illuminated fraction, phase name, synodic age in days since the new moon, phase longitude (the Moon–Sun ecliptic-longitude difference, 180° at full), and the next four quarter phases (new, first quarter, full, last quarter) with timestamps. Answers "what is the moon phase tonight" and "when is the next full moon" in one call without iteration. The time defaults to now; pass an IANA `timezone` to also receive observer-local timestamps. The phase is geocentric — no observer location is needed.
| Argument | Type | Description |
|---|---|---|
| time | string | Instant to evaluate as an ISO 8601 UTC string, e.g. "2024-12-15T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
| timezone | string | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"time": {
"type": "string",
"description": "Instant to evaluate as an ISO 8601 UTC string, e.g. \"2024-12-15T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized output, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
}
},
"additionalProperties": false
}Compute rise, set, and culmination (transit) times and maximum transit altitude for a body at an observer location. Searches forward from `start` (default now) for `count` daily cycles (default 1), including days without crossings. For the Sun, each cycle carries civil −6°, nautical −12°, and astronomical −18° twilight: dusk after its set or culmination, then dawn before the next day begins. A crossing absent from that night is null. When the Sun is down and the first cycle's day begins after `start`, `night_in_progress` carries the preceding night, including polar nights without a sunset and times before `start` that have passed. A first cycle beginning after the culmination of a dark day instead carries that night itself, with rise, set, and transit null. When a body is already up, the partial first cycle has null rise and the imminent set; no set precedes its own rise. Circumpolar and never-rises cycles have null crossings and explanatory notes. At most 31 cycles are served per call; a count up to 366 returns the first 31 with a notice naming the exact `start` and `count` for the rest, or saying no continuation exists past 2100. A continuation may repeat the preceding night in `night_in_progress`, while cycles continue without overlap. Default elevation is 0 m; pass an IANA `timezone` for local output. Resolve coordinates upstream; this server does not geocode.
| Argument | Type | Description |
|---|---|---|
| body* | string | The body to compute rise/set for. Twilight is included only when this is "sun". |
| count | integer | Number of forward rise/set cycles to return. Default 1. At most 31 are computed per call; a count up to 366 returns the first 31 with a notice naming the `start` and `count` that continue the series. |
| start | string |
Predict visible passes of a satellite (e.g. the ISS, NORAD 25544) over an observer in the next `days`. Identify the satellite by exactly one of `norad_id` or `name` — supplying both, or neither, is rejected. A few well-known common names resolve directly to their catalog numbers, ignoring case: ISS or International Space Station (25544), Hubble, Hubble Space Telescope, or HST (20580), and Tiangong, CSS, or Chinese Space Station (48274). Any other `name` is matched as a case-insensitive substring of CelesTrak's catalog names, so it resolves only when it picks out a single object: a broader query comes back with the matching objects and their catalog numbers to choose from. Either way the result echoes the query that resolved it as `resolved_from_name`. Fetches the object's current GP element set from CelesTrak, propagates it with SGP4 in-process, and returns each pass's rise, peak, and set times with azimuths and the peak elevation, plus the stretch of the pass visible to the naked eye: `visible_start_utc` through `visible_end_utc`, with the elevation and azimuth at each end. A pass is returned when that visible stretch — the satellite above the horizon and sunlit while the Sun is below −6° for the observer — reaches 10° elevation, wherever in the pass it falls. `sunlit` reports illumination at the peak instant, so it is false on a pass seen only before it enters Earth's shadow or after it leaves. Rise, set, and the visible-stretch edges are within 1 s of the true instants; the peak is the highest sample of a 30-second scan. Every returned pass rises in the requested window or in the 30 s before `start`: a pass up longer than that at `start` is omitted rather than reported with `start` as its rise, so back up `start` to see it, while a pass still up when the window ends is reported through its actual set. Searches at most 10 days per call: a larger `days`, up to 30, searches the first 10 and returns a notice naming the exact `start` and `days` that continue the search with no pass repeated or skipped, while that start stays within about a month of the element set's epoch. A `start` further than about a month from the element set's epoch is rejected as out of range on that distance alone, and an element set that will not propagate to a window inside that horizon is rejected as a reentry — so an empty `passes` means only that nothing was visible. CelesTrak publishes only current element sets, so in practice `start` must be within about a month of today. NORAD catalog numbers and catalog names are found at celestrak.org or heavens-above.com. This is a gated, network-backed extension (CelesTrak is keyless but rate-limited; element sets are cached briefly). Default elevation 0 m; pass an IANA timezone for observer-local pass times.
Compute the apparent topocentric position of one solar-system body (sun, moon, mercury through neptune, pluto) or a named bright star for an observer location and instant. Returns equatorial (RA/Dec), refraction-corrected horizontal (altitude/azimuth), and ecliptic coordinates, plus distance, apparent magnitude, angular diameter, phase angle, illuminated fraction, angular distance from the Sun, and the constellation it falls in. For a solar-system body it also returns that body card — classification, mean radius, naked-eye visibility — the same values served at astronomy://body/{body}, so a client without resource support does not need a second surface to reach them; a catalog star has no card and the field is absent. Positions are parallax- and aberration-corrected for the given observer; default elevation is 0 m and the default time is now. Supply `star` (e.g. "Sirius", "Polaris") instead of `body` to target a catalog star; `body` is ignored when `star` is set. Pass an IANA `timezone` to also receive the observer-local time. This server does not geocode — resolve a place name to latitude/longitude upstream first.
| Argument | Type | Description |
|---|---|---|
| body | string | Solar-system body to locate. Omit when targeting a named star via `star`. |
| star | string | Named star to locate, from a bundled catalog of 32 stars — about 30 of the brightest naked-eye stars plus Polaris, not an arbitrary star. Accepts a common name or Bayer designation, with the Greek letter spelled out or as a symbol and the constellation as its genitive or IAU abbreviation (e.g. "Sirius", "Alpha Centauri", "α CMa"). A name outside the catalog fails with the full list of catalog stars. Takes precedence over `body`. |
| time | string | Instant of observation as an ISO 8601 UTC string, e.g. "2024-04-08T18:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
The one-call "what is up right now" answer. For an observer location and instant, iterate every naked-eye solar-system body (and, with include_stars, the bundled bright stars), compute altitude and azimuth, keep those above the horizon, rank them brightest-and-highest first, and attach a plain-language visibility note to each, along with its angular distance from the Sun. The whole sky is gated by the Sun's altitude into daylight / civil / nautical / astronomical twilight / dark, returned alongside the list, and each note says when daylight, civil twilight, or the Sun's glare hides or dims that body. `time` is a single evaluation instant, not a window — for "tonight" pass a time after astronomical dusk (use astronomy_get_rise_set on the sun to find it). Default elevation 0 m; use min_altitude to skip objects grazing the horizon. This server does not geocode — resolve coordinates upstream first; pass an IANA timezone for observer-local times on each body.
| Argument | Type | Description |
|---|---|---|
| time | string | Evaluation instant as an ISO 8601 UTC string, e.g. "2024-08-12T05:00:00Z". Defaults to now. A single instant, not a window. A value with no zone designator is read as UTC, not the local zone of the server process. |
| latitude* | number | Observer latitude in decimal degrees, north positive. |
| timezone | string | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| elevation | number | Observer elevation in meters above sea level. Default 0. |
| Observer elevation in meters above sea level. Default 0. |
| longitude | number | Observer longitude in decimal degrees, supplied together with latitude. Optional for solar_eclipse and lunar_eclipse; ignored by every other event. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"event"
],
"properties": {
"body": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"earth"
],
"type": "string",
"description": "Target body — required for opposition, conjunction, max_elongation, and perigee_apogee; ignored otherwise. \"earth\" is accepted only for perigee_apogee, which returns its perihelion and aphelion. With `body2`, the Moon or a planet."
},
"body2": {
"enum": [
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string",
"description": "Second body for a conjunction of two bodies: the Moon or a planet, different from `body`. Accepted only with event \"conjunction\", where it replaces the conjunction of `body` with the Sun by the conjunction of `body` and `body2` in ecliptic longitude seen from Earth's center. For the Moon meeting the Sun, search moon_quarter for the new moon."
},
"count": {
"type": "integer",
"default": 1,
"maximum": 200,
"minimum": 1,
"description": "Number of forward occurrences to return. Default 1. At most 20 are computed per call; a count up to 200 returns the first 20 with a notice naming the `start` and `count` that continue the series."
},
"event": {
"enum": [
"solar_eclipse",
"lunar_eclipse",
"equinox",
"solstice",
"moon_quarter",
"opposition",
"conjunction",
"max_elongation",
"perigee_apogee"
],
"type": "string",
"description": "Which class of event to search for."
},
"start": {
"type": "string",
"description": "Search start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\". Eclipses are included when their peak is at or after start; earlier contacts may still be returned. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees, supplied together with longitude. Optional for solar_eclipse and lunar_eclipse, where it adds local circumstances; omit both for a global solar search. Ignored by every other event."
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized output, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees, supplied together with latitude. Optional for solar_eclipse and lunar_eclipse; ignored by every other event."
}
},
"additionalProperties": false
}| stop | string | Ephemeris stop as an ISO 8601 UTC string in years 0100 through 9999, at or after start — equal to start returns the single row at that instant. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process. |
| start | string | Ephemeris start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z", in years 0100 through 9999 — the calendar years JPL Horizons reads. Dates are Gregorian, extended before 1582. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
| latitude | number | Observer latitude in decimal degrees — supply together with longitude for topocentric coordinates and alt/az. Supplying one without the other is rejected. |
| elevation | number | Observer elevation in meters above sea level. Default 0. With latitude and longitude it must be greater than -20000 and less than 40000000 — the observer altitudes Horizons accepts; a geocentric request ignores it. |
| longitude | number | Observer longitude in decimal degrees. Supply together with latitude; one without the other is rejected. |
| designation* | string | JPL Horizons target, passed verbatim — use a form that resolves to one record. Numbered asteroid: trailing-semicolon record lookup, e.g. "433;" (Eros), "1;" (Ceres). Periodic comet: DES + closest-apparition flag, e.g. "DES=1P;CAP" (Halley), "DES=2P;CAP" (Encke). Spacecraft: negative SPK-ID, e.g. "-48" (Hubble). A bare name like "433 Eros" (no match) or "1P/Halley" (several records) is rejected, and "Mars" (several major bodies) is rejected with their ID numbers listed — the planet is "499" — but one matching a single object succeeds even when it is not the object meant — check `target_name` in the result. Earth ("399") is rejected, being the body the observer is on, and so is a name containing an apostrophe, which the Horizons search cannot match — "6P/d'Arrest" resolves as "DES=6P;CAP" — or any character outside printable ASCII, which Horizons refuses, such as an accent or a typographic apostrophe — "Šteins" resolves as "2867;". Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"designation"
],
"properties": {
"step": {
"type": "string",
"default": "1h",
"description": "Step size as a positive count up to 2147483647 plus a unit of m (minutes), h (hours), d (days), mo (months), or y (years), e.g. \"10m\", \"1h\", \"1d\". Default \"1h\"."
},
"stop": {
"type": "string",
"description": "Ephemeris stop as an ISO 8601 UTC string in years 0100 through 9999, at or after start — equal to start returns the single row at that instant. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"start": {
"type": "string",
"description": "Ephemeris start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\", in years 0100 through 9999 — the calendar years JPL Horizons reads. Dates are Gregorian, extended before 1582. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees — supply together with longitude for topocentric coordinates and alt/az. Supplying one without the other is rejected."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0. With latitude and longitude it must be greater than -20000 and less than 40000000 — the observer altitudes Horizons accepts; a geocentric request ignores it."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees. Supply together with latitude; one without the other is rejected."
},
"designation": {
"type": "string",
"pattern": "\\S",
"description": "JPL Horizons target, passed verbatim — use a form that resolves to one record. Numbered asteroid: trailing-semicolon record lookup, e.g. \"433;\" (Eros), \"1;\" (Ceres). Periodic comet: DES + closest-apparition flag, e.g. \"DES=1P;CAP\" (Halley), \"DES=2P;CAP\" (Encke). Spacecraft: negative SPK-ID, e.g. \"-48\" (Hubble). A bare name like \"433 Eros\" (no match) or \"1P/Halley\" (several records) is rejected, and \"Mars\" (several major bodies) is rejected with their ID numbers listed — the planet is \"499\" — but one matching a single object succeeds even when it is not the object meant — check `target_name` in the result. Earth (\"399\") is rejected, being the body the observer is on, and so is a name containing an apostrophe, which the Horizons search cannot match — \"6P/d'Arrest\" resolves as \"DES=6P;CAP\" — or any character outside printable ASCII, which Horizons refuses, such as an accent or a typographic apostrophe — \"Šteins\" resolves as \"2867;\". Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html."
}
},
"additionalProperties": false
}| Search start as an ISO 8601 UTC string, e.g. "2024-06-21T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
| latitude* | number | Observer latitude in decimal degrees, north positive. |
| timezone | string | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| elevation | number | Observer elevation in meters above sea level. Default 0. |
| longitude* | number | Observer longitude in decimal degrees, east positive. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"body",
"latitude",
"longitude"
],
"properties": {
"body": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string",
"description": "The body to compute rise/set for. Twilight is included only when this is \"sun\"."
},
"count": {
"type": "integer",
"default": 1,
"maximum": 366,
"minimum": 1,
"description": "Number of forward rise/set cycles to return. Default 1. At most 31 are computed per call; a count up to 366 returns the first 31 with a notice naming the `start` and `count` that continue the series."
},
"start": {
"type": "string",
"description": "Search start as an ISO 8601 UTC string, e.g. \"2024-06-21T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized output, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees, east positive."
}
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| days | integer | Number of days ahead to search for passes. Default 7. At most 10 are searched per call; a value up to 30 searches the first 10 with a notice naming the `start` and `days` that continue the search. |
| name | string | Satellite name to resolve, e.g. "ISS (ZARYA)". The common names ISS, International Space Station, Hubble, Hubble Space Telescope, HST, Tiangong, CSS, and Chinese Space Station resolve directly to their catalog numbers, ignoring case and surrounding whitespace. Any other name is matched against CelesTrak as a case-insensitive substring of the catalog name, so give the fullest name you have — a short one matches many objects and is rejected as ambiguous. Mutually exclusive with `norad_id` — supply exactly one. |
| start | string | Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. |
| latitude* | number | Observer latitude in decimal degrees, north positive. |
| norad_id | integer | NORAD catalog number of the satellite, e.g. 25544 for the ISS. Found at celestrak.org or heavens-above.com. Mutually exclusive with `name` — supply exactly one. |
| timezone | string | IANA timezone for localized pass times, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| elevation | number | Observer elevation in meters above sea level. Default 0. |
| longitude* | number | Observer longitude in decimal degrees, east positive. |
{
"type": "object",
"oneOf": [
{
"not": {
"required": [
"name"
]
},
"type": "object",
"required": [
"norad_id"
]
},
{
"not": {
"required": [
"norad_id"
]
},
"type": "object",
"required": [
"name"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"latitude",
"longitude"
],
"properties": {
"days": {
"type": "integer",
"default": 7,
"maximum": 30,
"minimum": 1,
"description": "Number of days ahead to search for passes. Default 7. At most 10 are searched per call; a value up to 30 searches the first 10 with a notice naming the `start` and `days` that continue the search."
},
"name": {
"type": "string",
"description": "Satellite name to resolve, e.g. \"ISS (ZARYA)\". The common names ISS, International Space Station, Hubble, Hubble Space Telescope, HST, Tiangong, CSS, and Chinese Space Station resolve directly to their catalog numbers, ignoring case and surrounding whitespace. Any other name is matched against CelesTrak as a case-insensitive substring of the catalog name, so give the fullest name you have — a short one matches many objects and is rejected as ambiguous. Mutually exclusive with `norad_id` — supply exactly one."
},
"start": {
"type": "string",
"description": "Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees, north positive."
},
"norad_id": {
"type": "integer",
"maximum": 9007199254740991,
"description": "NORAD catalog number of the satellite, e.g. 25544 for the ISS. Found at celestrak.org or heavens-above.com. Mutually exclusive with `name` — supply exactly one.",
"exclusiveMinimum": 0
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized pass times, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees, east positive."
}
},
"additionalProperties": false
}| latitude* | number | Observer latitude in decimal degrees, north positive. |
| timezone | string | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| elevation | number | Observer elevation in meters above sea level. Default 0. |
| longitude* | number | Observer longitude in decimal degrees, east positive. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"latitude",
"longitude"
],
"properties": {
"body": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string",
"description": "Solar-system body to locate. Omit when targeting a named star via `star`."
},
"star": {
"type": "string",
"description": "Named star to locate, from a bundled catalog of 32 stars — about 30 of the brightest naked-eye stars plus Polaris, not an arbitrary star. Accepts a common name or Bayer designation, with the Greek letter spelled out or as a symbol and the constellation as its genitive or IAU abbreviation (e.g. \"Sirius\", \"Alpha Centauri\", \"α CMa\"). A name outside the catalog fails with the full list of catalog stars. Takes precedence over `body`."
},
"time": {
"type": "string",
"description": "Instant of observation as an ISO 8601 UTC string, e.g. \"2024-04-08T18:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized output, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees, east positive."
}
},
"additionalProperties": false
}| longitude* |
| number |
| Observer longitude in decimal degrees, east positive. |
| min_altitude | number | Minimum altitude in degrees to include a body. Default 0 (above the horizon); use e.g. 5 to require clearance. |
| include_stars | boolean | Include the bundled bright stars alongside planets. Default false. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"latitude",
"longitude"
],
"properties": {
"time": {
"type": "string",
"description": "Evaluation instant as an ISO 8601 UTC string, e.g. \"2024-08-12T05:00:00Z\". Defaults to now. A single instant, not a window. A value with no zone designator is read as UTC, not the local zone of the server process."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude in decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA timezone for localized output, e.g. \"America/Los_Angeles\". When omitted, output is UTC-only."
},
"elevation": {
"type": "number",
"default": 0,
"description": "Observer elevation in meters above sea level. Default 0."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude in decimal degrees, east positive."
},
"min_altitude": {
"type": "number",
"default": 0,
"maximum": 90,
"minimum": -90,
"description": "Minimum altitude in degrees to include a body. Default 0 (above the horizon); use e.g. 5 to require clearance."
},
"include_stars": {
"type": "boolean",
"default": false,
"description": "Include the bundled bright stars alongside planets. Default false."
}
},
"additionalProperties": false
}