Download OpenAPI specification:
GeoAstro API is a high‑precision astronomy REST API that delivers professional‑grade Sun, Moon and planet data for any location and date. It provides accurate rise, set and meridian transits, civil/nautical/astronomical twilight, golden hour and blue hour intervals, as well as detailed Moon phases, illumination, bright‑limb orientation and daily/monthly astro calendars. For planets, it exposes apparent positions, visual magnitude and visibility windows with a synthetic visibility score, helping you find the best observing or photography conditions. All responses are timezone‑aware, support sea‑level or custom observer altitude and are returned as clean JSON, making GeoAstro API ideal for mobile apps, web dashboards, weather services, photography planners and astronomy tools
Returns sunrise, sunset, twilights and meridian transits for the Sun for a specific day and location. The day is identified by a start-of-day Unix timestamp (seconds).
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Events for the following 24 hours will be returned. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard almanac-like sunrise/sunset times at sea level; non-zero values adjust rise/set and transits for the actual local horizon of the observer (e.g. on a hill or mountain). |
{- "rise": {
- "timestamp": 1707022800,
- "position": 110.5
}, - "set": {
- "timestamp": 1707066000,
- "position": 249.3
}, - "civilTwilight": {
- "start": {
- "timestamp": 1707020400,
- "position": 103.2
}, - "end": {
- "timestamp": 1707068400,
- "position": 256.7
}
}, - "nauticalTwilight": {
- "start": {
- "timestamp": 1707018600,
- "position": 95.4
}, - "end": {
- "timestamp": 1707070200,
- "position": 264.1
}
}, - "astronomicalTwilight": {
- "start": {
- "timestamp": 1707016800,
- "position": 88.9
}, - "end": {
- "timestamp": 1707072000,
- "position": 271
}
}, - "transits": {
- "southern": {
- "timestamp": 1707044400,
- "altitude": 35.7
}, - "northern": {
- "timestamp": 1707001200,
- "altitude": -35.7
}
}
}Returns the apparent azimuth and altitude of the Sun for the given time and observer location.
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 if you want times comparable to typical almanacs and weather apps (sea-level horizon); non-zero values give topocentric times for your real observing altitude. |
{- "position": 145.3,
- "altitude": 25.8
}Professional-grade Sun summary for a given instant and location: current apparent position plus sunrise, sunset, twilights and meridian transits for the local day (in the provided timezone).
| timestamp required | string Example: timestamp=1707032400 Reference timestamp (Unix seconds, typically "now" in UTC). The local calendar day in the given timezone containing this timestamp will be used to compute transit events. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. 0 means a sea-level observer (standard almanac horizon); higher values slightly advance sunrise and delay sunset according to the local horizon. |
| timezone required | string Example: timezone=America/New_York IANA timezone identifier for the observer location (e.g. "Europe/Rome", "America/New_York"). It defines what "today" means when computing sunrise, sunset and twilights. |
{- "timestamp": 1707032400,
- "timezone": "America/New_York",
- "dayStartTimestamp": 1707004800,
- "dayEndTimestamp": 1707091200,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "position": {
- "azimuthDeg": 145.3,
- "altitudeDeg": 25.8,
- "isAboveHorizon": true
}, - "transits": {
- "rise": {
- "timestamp": 1707022800,
- "position": 110.5
}, - "set": {
- "timestamp": 1707066000,
- "position": 249.3
}, - "civilTwilight": {
- "start": {
- "timestamp": 1707020400,
- "position": 103.2
}, - "end": {
- "timestamp": 1707068400,
- "position": 256.7
}
}, - "nauticalTwilight": {
- "start": {
- "timestamp": 1707018600,
- "position": 95.4
}, - "end": {
- "timestamp": 1707070200,
- "position": 264.1
}
}, - "astronomicalTwilight": {
- "start": {
- "timestamp": 1707016800,
- "position": 88.9
}, - "end": {
- "timestamp": 1707072000,
- "position": 271
}
}, - "transits": {
- "southern": {
- "timestamp": 1707044400,
- "altitude": 35.7
}, - "northern": {
- "timestamp": 1707001200,
- "altitude": -35.7
}
}
}, - "goldenHours": [
- {
- "start": 1707021000,
- "end": 1707028200,
- "type": "morning"
}
], - "blueHours": [
- {
- "start": 1707019800,
- "end": 1707024000,
- "type": "evening"
}
]
}Returns rise, set and meridian transits for the Moon for a specific day and location. The day is identified by a start-of-day Unix timestamp (seconds).
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Events for the following 24 hours will be returned. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard sea-level rise/set times comparable to printed almanacs; non-zero values adjust Moon rise/set and transits for the actual local horizon of the observer. |
{- "rise": {
- "timestamp": 1707026400,
- "position": 110.5
}, - "set": {
- "timestamp": 1707069600,
- "position": 249.3
}, - "transits": {
- "southern": {
- "timestamp": 1707048000,
- "altitude": 45.7
}, - "northern": {
- "timestamp": 1707004800,
- "altitude": -45.7
}
}
}Returns the apparent azimuth and altitude of the Moon for the given time and observer location.
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. 0 means a sea-level observer (standard horizon as in most almanacs); higher values compute topocentric Moon rise/set and transits for your true observing altitude. |
{- "position": 145.3,
- "altitude": 25.8
}Returns the geometric phase angle of the Moon for a given timestamp, plus a derived phaseId and phaseName describing the current lunar phase (new, crescent, quarter, gibbous, full).
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
{- "phaseAngle": 123.4,
- "phaseId": 4,
- "phaseName": "waxing-gibbous"
}Returns detailed illumination and phase information for the Moon: illuminated fraction, geometric phase angle and a derived phaseId/phaseName.
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
{- "illuminatedFraction": 0.54,
- "phaseAngle": 123.4,
- "phaseId": 4,
- "phaseName": "waxing-gibbous"
}Professional-grade Moon summary for a given instant and location: current position, illumination and phase plus rise/set and meridian transits for the local day (in the provided timezone), and bright limb angle to orient the illuminated side.
| timestamp required | string Example: timestamp=1707032400 Reference timestamp (Unix seconds, typically "now" in UTC). The local calendar day in the given timezone containing this timestamp will be used to compute rise/set and transits. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 if you want rise/set times comparable to typical almanacs; non-zero values slightly advance Moonrise and delay Moonset according to the local horizon at your altitude. |
| timezone required | string Example: timezone=America/New_York IANA timezone identifier for the observer location (e.g. "Europe/Rome", "America/New_York"). It defines what "today" means when computing rise/set and meridian transits. |
{- "timestamp": 1707032400,
- "timezone": "America/New_York",
- "dayStartTimestamp": 1707004800,
- "dayEndTimestamp": 1707091200,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "position": {
- "azimuthDeg": 145.3,
- "altitudeDeg": 25.8,
- "isAboveHorizon": true
}, - "illumination": {
- "illuminatedFraction": 0.98,
- "phaseAngle": 175.4,
- "phaseId": 5,
- "phaseName": "full-moon"
}, - "brightLimbAngleZenithDeg": 135,
- "transits": {
- "rise": {
- "timestamp": 1707026400,
- "position": 110.5
}, - "set": {
- "timestamp": 1707069600,
- "position": 249.3
}, - "transits": {
- "southern": {
- "timestamp": 1707048000,
- "altitude": 45.7
}, - "northern": {
- "timestamp": 1707004800,
- "altitude": -45.7
}
}
}
}Returns the position angle of the Moon bright limb with respect to the local zenith for the given location. The angle is measured from the zenith and increases clockwise as seen by the observer: 0° means the illuminated side points straight up, 90° to the right, 180° downwards and 270° to the left. This is useful to orient a Moon image in a UI; if your rendering system defines positive rotations as counter‑clockwise, you can usually rotate your base Moon sprite by (360° - angle) degrees around its centre.
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
{- "angle": 45.6
}Returns a list of upcoming Moon phases (new, first quarter, full, last quarter) starting from a given timestamp, searching roughly the next 30 days.
| timestamp required | string Example: timestamp=1707000000 Start timestamp (Unix seconds). The API will return the next Moon phases occurring in the following ~30 days. |
[- {
- "phaseId": 1,
- "phaseName": "new-moon",
- "timestamp": 1707026400
}
]Returns rise, set and meridian transits for a selected planet for a specific day and location. The day is identified by a start-of-day Unix timestamp (seconds).
| planet required | string Example: planet=jupiter Planet name (case-insensitive): mercury, venus, mars, jupiter, saturn, uranus or neptune. |
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Events for the following 24 hours will be returned. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. 0 means a sea-level observer (standard horizon as in most almanacs); higher values adjust rise/set and transits for the actual local horizon. |
{- "rise": {
- "timestamp": 1707026400,
- "position": 110.5
}, - "set": {
- "timestamp": 1707069600,
- "position": 249.3
}, - "transits": {
- "southern": {
- "timestamp": 1707048000,
- "altitude": 35.7
}, - "northern": {
- "timestamp": 1707004800,
- "altitude": -35.7
}
}
}Returns the apparent azimuth and altitude of a selected planet for the given time and observer location.
| planet required | string Example: planet=jupiter Planet name (case-insensitive): mercury, venus, mars, jupiter, saturn, uranus or neptune. |
| timestamp required | string Example: timestamp=1707000000 Timestamp (Unix seconds) |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 if you want positions comparable to standard ephemerides at sea level; non-zero values give fully topocentric positions for your real observing altitude. |
{- "position": 145.3,
- "altitude": 25.8,
- "magnitude": -2.6,
- "visibilityScore": 78
}Evaluates, for a specific day and location, when a selected planet is above the horizon and when it is well observable (planet above ~15° with the Sun below -12°).
| planet required | string Example: planet=jupiter Planet name (case-insensitive): mercury, venus, mars, jupiter, saturn, uranus or neptune. |
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Visibility will be evaluated for the following 24 hours. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. 0 means a sea-level observer (standard horizon); higher values adjust visibility windows using the true local horizon at that altitude. |
{- "dayStartTimestamp": 1707004800,
- "dayEndTimestamp": 1707091200,
- "planet": "jupiter",
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "sampling": {
- "stepSeconds": 600,
- "minPlanetAltitudeDeg": 15,
- "maxSunAltitudeDeg": -12
}, - "aboveHorizonIntervals": [
- {
- "start": 1707026400,
- "end": 1707060000
}
], - "observableIntervals": [
- {
- "start": 1707030000,
- "end": 1707058800
}
], - "bestObservableMoment": {
- "timestamp": 1707044400,
- "planetAltitude": 45.3,
- "sunAltitude": -20.5,
- "planetMagnitude": -2.1
}, - "visibilityScore": 82
}Returns timestamps for equinoxes and solstices for the given calendar year, plus a mapping by seasons for both hemispheres.
| year required | string Example: year=2024 Calendar year (UTC) for which to compute equinoxes and solstices |
{- "northwardEquinoxTimestamp": 1711044000,
- "northernSolsticeTimestamp": 1719057600,
- "southwardEquinoxTimestamp": 1727359200,
- "southernSolsticeTimestamp": 1735160400,
- "northernHemisphere": {
- "springEquinox": 1711044000,
- "summerSolstice": 1719057600,
- "autumnEquinox": 1727359200,
- "winterSolstice": 1735160400
}, - "southernHemisphere": {
- "autumnEquinox": 1711044000,
- "winterSolstice": 1719057600,
- "springEquinox": 1727359200,
- "summerSolstice": 1735160400
}
}Returns, in a single payload, the main Sun and Moon events for a specific day and location: sunrise/sunset, twilights, Moon phases of the day, illumination, maximum Moon altitude and approximate golden/blue hour intervals.
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Events for the following 24 hours will be returned. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard sea-level times comparable to printed almanacs; non-zero values adjust Sun and Moon rise/set and transits for the actual local horizon of the observer. |
{- "dayStartTimestamp": 1707004800,
- "dayEndTimestamp": 1707091200,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "sun": {
- "rise": {
- "timestamp": 1707022800,
- "position": 110.5
}, - "set": {
- "timestamp": 1707066000,
- "position": 249.3
}, - "civilTwilight": {
- "start": {
- "timestamp": 1707020400,
- "position": 103.2
}, - "end": {
- "timestamp": 1707068400,
- "position": 256.7
}
}, - "nauticalTwilight": {
- "start": {
- "timestamp": 1707018600,
- "position": 95.4
}, - "end": {
- "timestamp": 1707070200,
- "position": 264.1
}
}, - "astronomicalTwilight": {
- "start": {
- "timestamp": 1707016800,
- "position": 88.9
}, - "end": {
- "timestamp": 1707072000,
- "position": 271
}
}, - "transits": {
- "southern": {
- "timestamp": 1707044400,
- "altitude": 35.7
}, - "northern": {
- "timestamp": 1707001200,
- "altitude": -35.7
}
}
}, - "moon": {
- "illuminationAtNoon": 0.54,
- "phaseAtNoon": {
- "phase": 0.5,
- "illuminatedFraction": 0.54
}, - "phasesDuringDay": [
- {
- "phaseId": 3,
- "phaseName": "full-moon",
- "timestamp": 1707026400
}
], - "maxAltitudeTransit": {
- "timestamp": 1707048000,
- "altitude": 45.7
}
}, - "goldenHours": [
- {
- "start": 1707021000,
- "end": 1707028200,
- "type": "morning"
}
], - "blueHours": [
- {
- "start": 1707019800,
- "end": 1707024000,
- "type": "evening"
}
]
}Returns only the golden hour and blue hour intervals for a specific day and location, classified as morning (dawn) or evening (dusk).
| timestamp required | string Example: timestamp=1707004800 Start-of-day timestamp (Unix seconds). Intervals for the following 24 hours will be returned. Typically midnight UTC of the desired day. |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard sea-level times comparable to printed almanacs; non-zero values adjust golden/blue hour intervals for the true local horizon at that altitude. |
{- "dayStartTimestamp": 1707004800,
- "dayEndTimestamp": 1707091200,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "goldenHours": [
- {
- "start": 1707021000,
- "end": 1707028200,
- "type": "morning"
}
], - "blueHours": [
- {
- "start": 1707019800,
- "end": 1707024000,
- "type": "evening"
}
]
}Returns, for each day of a given month and location, the main Sun transit events (sunrise, sunset, twilights and meridian transits).
| year required | string Example: year=2024 Calendar year (UTC) for which to compute the monthly Sun calendar. |
| month required | string Example: month=3 Calendar month number (1-12). |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard sea-level times comparable to printed almanacs; non-zero values adjust Sun rise/set and transits for the actual local horizon. |
{- "year": 2024,
- "month": 3,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "days": [
- {
- "day": 21,
- "dayStartTimestamp": 1710979200,
- "dayEndTimestamp": 1711065600,
- "sun": {
- "rise": {
- "timestamp": 1710990000,
- "position": 88.5
}, - "set": {
- "timestamp": 1711033200,
- "position": 271.2
}, - "civilTwilight": {
- "start": {
- "timestamp": 1710988200,
- "position": 81.2
}, - "end": {
- "timestamp": 1711035000,
- "position": 278.8
}
}, - "nauticalTwilight": {
- "start": {
- "timestamp": 1710986400,
- "position": 73.4
}, - "end": {
- "timestamp": 1711036800,
- "position": 286.6
}
}, - "astronomicalTwilight": {
- "start": {
- "timestamp": 1710984600,
- "position": 66
}, - "end": {
- "timestamp": 1711038600,
- "position": 294
}
}, - "transits": {
- "southern": {
- "timestamp": 1711011600,
- "altitude": 45.2
}, - "northern": {
- "timestamp": 1710968400,
- "altitude": -45.2
}
}
}
}
]
}Returns, for each day of a given month and location, the main Moon transit events (moonrise, moonset and meridian transits), plus phase information (including illuminated fraction) evaluated at noon.
| year required | string Example: year=2024 Calendar year (UTC) for which to compute the monthly Moon calendar. |
| month required | string Example: month=3 Calendar month number (1-12). |
| lat required | string Example: lat=41.9028 Latitude in degrees (-90..90) |
| lng required | string Example: lng=12.4964 Longitude in degrees (-180..180) |
| height required | string Example: height=0 Observer height above sea level in meters. Use 0 for standard sea-level times comparable to printed almanacs; non-zero values adjust Moon rise/set and transits for the actual local horizon. |
{- "year": 2024,
- "month": 3,
- "location": {
- "lat": 41.9028,
- "lng": 12.4964,
- "height": 0
}, - "days": [
- {
- "day": 21,
- "dayStartTimestamp": 1710979200,
- "dayEndTimestamp": 1711065600,
- "moon": {
- "rise": {
- "timestamp": 1707026400,
- "position": 110.5
}, - "set": {
- "timestamp": 1707069600,
- "position": 249.3
}, - "transits": {
- "southern": {
- "timestamp": 1707048000,
- "altitude": 45.7
}, - "northern": {
- "timestamp": 1707004800,
- "altitude": -45.7
}
}, - "phaseAtNoon": {
- "phase": 0.5,
- "illuminatedFraction": 0.54
}
}
}
]
}