Astronomy data for any date and location — sunrise, sunset, solar noon, civil/nautical/astronomical twilight phases, moonrise, moonset, moon phase, illumination percentage, and altitude/azimuth for the sun and moon. Includes a /astronomy/timeSeries endpoint for date ranges.
openapi: 3.0.7
info:
title: 'IPGeolocation.io: Astronomy API'
version: "3.0"
description: |
Retrieve astronomical information including rise and set times for the
Sun and Moon, current position, distance from Earth, and azimuth for
a specific location and date.
The Astronomy API provides accurate-enough results (within approximately
one minute) suitable for applications like sunrise/sunset timers, though
not intended for precision astronomical purposes.
Astronomical information can be retrieved using multiple lookup inputs:
- Location address (preferably city-level)
- Geographic coordinates (latitude and longitude)
- IPv4 or IPv6 address
If no lookup parameter is provided, the API resolves the location using
the public IP address of the requesting client.
Two endpoints are available:
- **Single-date lookup** (`GET /v3/astronomy`) returns astronomical
information for a specific location and date, including sunrise,
sunset, moonrise, moonset, twilight phases, golden hour, blue hour,
sun and moon position data, and moon phase.
- **Time series lookup** (`GET /v3/astronomy/timeSeries`) returns
astronomical information across a date range (up to 90 days) for a
specific location.
## Authentication
Two authentication methods are supported:
### API Key
Pass your API key as the `apiKey` query parameter on every request. You can find your
key in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in
server-side environment variables. Avoid exposing it in client-side JavaScript.
### Request Origin (CORS)
Available on paid plans only. Whitelist your domain in the dashboard under the
"API Keys" section. Once configured, requests from that domain (and all its subdomains)
are accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),
not the full URL.
Each plan has a limit on the number of extra API keys and request origins:
| Plan | Extra API Keys + Request Origins |
|---|---|
| Starter (150K requests) | 1 |
| Core (250K requests) | 1 |
| Plus (500K requests) | 2 |
| Pro (1M requests) | 2 |
| Business (2M requests) | 3 |
| Premium (5M requests) | 3 |
Additional keys or origins can be added for $2.50 per month each.
## Credit Usage
Credits are charged only for successful **HTTP 200** responses. The
exact number of credits consumed by a request is returned in the
`X-Credits-Charged` response header.
- Each successful **Astronomy lookup** consumes **1 credit** per request.
## Lookup Parameter Priority
If multiple lookup parameters are provided in a request, the API resolves
the location using the following priority order:
1. Geographic coordinates (`lat` and `long`)
2. `location`
3. `ip`
If none of the lookup parameters are provided, the API resolves the
location using the public IP address of the requesting client.
## Time Zone Behavior
By default, all astronomical event timestamps (sunrise, sunset, moonrise,
moonset, twilight phases, solar noon, etc.) are returned in the local
time of the resolved geographic location.
If the optional `time_zone` parameter is provided, all timestamps are
converted to the specified IANA timezone. In this case, timestamps are
returned as full date-time values (`yyyy-MM-dd HH:mm`) rather than
time-only values (`HH:mm`), and a `time_zone` field is included in
the `astronomy` response object.
Due to timezone differences, some events may appear on a different
calendar date after conversion.
contact:
name: IPGeolocation Support
url: https://ipgeolocation.io/contact.html
email: [email protected]
termsOfService: https://ipgeolocation.io/tos.html
license:
name: Proprietary
url: https://ipgeolocation.io/tos.html
externalDocs:
description: IPGeolocation Astronomy API documentation
url: https://ipgeolocation.io/documentation/astronomy-api.html
servers:
- url: https://api.ipgeolocation.io
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Astronomy
description: |
API endpoints for retrieving astronomical information for a given
location, including sunrise and sunset times, moonrise and moonset
times, twilight phases, golden hour and blue hour windows, solar noon,
sun and moon position data (altitude, azimuth, distance), and moon
phase.
A time series endpoint is also available to retrieve daily astronomical
data across a date range of up to 90 days.
externalDocs:
description: IPGeolocation Astronomy API documentation
url: https://ipgeolocation.io/documentation/astronomy-api.html
paths:
/v3/astronomy:
get:
operationId: lookupAstronomy
summary: IPGeolocation.io Astronomy Lookup
description: |
Returns astronomical information for a specific location and date,
including:
- Sunrise and sunset times
- Moonrise and moonset times
- Morning and evening twilight phases (astronomical, nautical, civil)
- Golden hour and blue hour windows (morning and evening)
- Solar noon, day length, and astronomical midnight
- Sun position: altitude, azimuth, distance from Earth
- Moon position: altitude, azimuth, distance from Earth, parallactic angle
- Moon phase, illumination percentage, and angular diameter
The location can be resolved using geographic coordinates (`lat` and
`long`), a location address (`location`), or an IP address (`ip`).
If multiple lookup parameters are provided, the API resolves the
location using the following priority order:
1. `lat` and `long`
2. `location`
3. `ip`
If none of the lookup parameters are provided, the API resolves the
location using the public IP address of the requesting client.
By default, results are calculated for the current date. Pass the
`date` parameter to retrieve data for a specific date.
Each successful lookup consumes **1 credit**.
tags:
- Astronomy
parameters:
- $ref: "#/components/parameters/Lat"
- $ref: "#/components/parameters/Long"
- $ref: "#/components/parameters/Location"
- $ref: "#/components/parameters/Ip"
- $ref: "#/components/parameters/Date"
- $ref: "#/components/parameters/Elevation"
- $ref: "#/components/parameters/TimeZone"
- $ref: "#/components/parameters/Lang"
responses:
"200":
description: Successful response
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/AstronomyLookupResponse'
example:
location:
latitude: "40.76473"
longitude: "-74.00084"
country_name: "United States"
state_prov: "New York"
city: "New York"
locality: "Midtown West"
elevation: "9"
astronomy:
date: "2026-03-18"
current_time: "10:15:00.000"
mid_night: "00:06"
night_end: "04:49"
morning:
astronomical_twilight_begin: "04:49"
astronomical_twilight_end: "05:21"
nautical_twilight_begin: "05:21"
nautical_twilight_end: "05:53"
civil_twilight_begin: "05:53"
civil_twilight_end: "06:20"
blue_hour_begin: "05:42"
blue_hour_end: "06:03"
golden_hour_begin: "06:03"
golden_hour_end: "06:57"
sunrise: "06:20"
sunset: "19:00"
evening:
golden_hour_begin: "18:23"
golden_hour_end: "19:16"
blue_hour_begin: "19:16"
blue_hour_end: "19:38"
civil_twilight_begin: "19:00"
civil_twilight_end: "19:27"
nautical_twilight_begin: "19:27"
nautical_twilight_end: "19:59"
astronomical_twilight_begin: "19:59"
astronomical_twilight_end: "20:31"
night_begin: "20:31"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:40"
sun_altitude: 42.5
sun_distance: 148900000.0
sun_azimuth: 150.3
moon_phase: "WAXING_CRESCENT"
moonrise: "08:45"
moonset: "22:10"
moon_status: "-"
moon_altitude: 15.2
moon_distance: 384400.0
moon_azimuth: 220.5
moon_parallactic_angle: 30.1
moon_illumination_percentage: "25.40"
moon_angle: 0.52
application/xml:
schema:
$ref: '#/components/schemas/AstronomyLookupResponse'
example: |
<LinkedHashMap>
<location>
<latitude>40.76473</latitude>
<longitude>-74.00084</longitude>
<country_name>United States</country_name>
<state_prov>New York</state_prov>
<city>New York</city>
<locality>Midtown West</locality>
<elevation>9</elevation>
</location>
<astronomy>
<date>2026-03-18</date>
<current_time>15:54:15.261</current_time>
<mid_night>01:03</mid_night>
<night_end>05:31</night_end>
<morning>
<astronomical_twilight_begin>05:31</astronomical_twilight_begin>
<astronomical_twilight_end>06:03</astronomical_twilight_end>
<nautical_twilight_begin>06:03</nautical_twilight_begin>
<nautical_twilight_end>06:35</nautical_twilight_end>
<civil_twilight_begin>06:35</civil_twilight_begin>
<civil_twilight_end>07:02</civil_twilight_end>
<blue_hour_begin>06:24</blue_hour_begin>
<blue_hour_end>06:46</blue_hour_end>
<golden_hour_begin>06:46</golden_hour_begin>
<golden_hour_end>07:38</golden_hour_end>
</morning>
<sunrise>07:02</sunrise>
<sunset>19:06</sunset>
<evening>
<golden_hour_begin>18:30</golden_hour_begin>
<golden_hour_end>19:22</golden_hour_end>
<blue_hour_begin>19:22</blue_hour_begin>
<blue_hour_end>19:44</blue_hour_end>
<civil_twilight_begin>19:06</civil_twilight_begin>
<civil_twilight_end>19:33</civil_twilight_end>
<nautical_twilight_begin>19:33</nautical_twilight_begin>
<nautical_twilight_end>20:05</nautical_twilight_end>
<astronomical_twilight_begin>20:05</astronomical_twilight_begin>
<astronomical_twilight_end>20:38</astronomical_twilight_end>
</evening>
<night_begin>20:38</night_begin>
<sun_status>-</sun_status>
<solar_noon>13:04</solar_noon>
<day_length>12:04</day_length>
<sun_altitude>33.35169743090959</sun_altitude>
<sun_distance>148782269.19009596</sun_distance>
<sun_azimuth>234.07341944671086</sun_azimuth>
<moon_phase>NEW_MOON</moon_phase>
<moonrise>06:44</moonrise>
<moonset>18:57</moonset>
<moon_status>-</moon_status>
<moon_altitude>31.430127664137917</moon_altitude>
<moon_distance>374392.1525559059</moon_distance>
<moon_azimuth>237.27212480757834</moon_azimuth>
<moon_parallactic_angle>39.582319837764366</moon_parallactic_angle>
<moon_illumination_percentage>-0.07</moon_illumination_percentage>
<moon_angle>357.01360045404493</moon_angle>
</astronomy>
</LinkedHashMap>
"400":
description: |
Bad Request – Possible reasons include:
- If the provided IPv4 or IPv6 address is invalid.
- If special character(s) `( ) [ ] { } | ^ \`` is passed in the
API URL either as a parameter or its value, especially in the
case of an API key.
- If the provided `date` is not in the format `yyyy-MM-dd`.
- If an invalid or unsupported `lang` parameter is provided.
- If the provided values for `lat` and `long` are not numbers,
or fall outside the acceptable ranges. Valid latitude range is
**-90 to 90**; valid longitude range is **-180 to 180**.
- If the provided `elevation` value exceeds the maximum allowed
value of **10,000 meters**.
- If the provided `time_zone` is invalid or unrecognized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Invalid IPv4 or IPv6 address
value:
message: "Provided name, service or IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Invalid characters in request
value:
message: "Invalid character found in the request target."
invalidDate:
summary: Invalid date format
value:
message: "You must provide date in the 'yyyy-MM-dd' format"
invalidCoordinates:
summary: Coordinates out of range
value:
message: "Longitude must be between -180 and 180 or latitude must be between -90 and 90."
invalidElevation:
summary: Elevation exceeds maximum
value:
message: "Elevation cannot be greater than 10000 meters."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
invalidLang:
summary: Unsupported language parameter
value:
message: "This 'xx' lang is not valid. Please use 'en' as the default language."
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key.
- If your account has been disabled or locked by the admin due
to abuse or illegal activity.
- When the request is made using an API key for a database
subscription.
- When the request is made on a paused subscription.
- If you are making API requests after your subscription trial
has expired.
- If your active-until date has passed and you need to renew
or upgrade your subscription.
- A language other than English is specified in the `lang`
parameter while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at [email protected]"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at [email protected]"
databaseSubscription:
summary: Database subscription key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
pausedSubscription:
summary: Subscription paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance
at [email protected]"
freePlanLang:
summary: Non-English language on Free plan
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/astronomy/timeSeries:
get:
operationId: lookupAstronomyTimeSeries
summary: IPGeolocation.io Astronomy Time Series Lookup
description: |
Returns daily astronomical information for a specific location across
a date range.
The response contains an array of daily astronomy records, each
including sunrise, sunset, moonrise, moonset, twilight phases,
solar noon, day length, and moon phase. Real-time positional data
(altitude, azimuth, distance) is not included in time series
responses.
The location can be resolved using geographic coordinates (`lat` and
`long`), a location address (`location`), or an IP address (`ip`).
**Date range constraints:**
- Both `dateStart` and `dateEnd` are required.
- The maximum allowed span between `dateStart` and `dateEnd` is
**90 days**.
- Both past and future dates are supported within the 90-day window.
Each successful lookup consumes **1 credit** per request.
tags:
- Astronomy
parameters:
- $ref: "#/components/parameters/Lat"
- $ref: "#/components/parameters/Long"
- $ref: "#/components/parameters/Location"
- $ref: "#/components/parameters/Ip"
- $ref: "#/components/parameters/DateStart"
- $ref: "#/components/parameters/DateEnd"
- $ref: "#/components/parameters/Elevation"
- $ref: "#/components/parameters/TimeZone"
- $ref: "#/components/parameters/Lang"
responses:
"200":
description: Successful response
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/AstronomyTimeSeriesResponse'
example:
location:
latitude: "40.76473"
longitude: "-74.00084"
country_name: "United States"
state_prov: "New York"
city: "New York"
locality: "Midtown West"
elevation: "9"
astronomy:
- date: "2026-03-18"
mid_night: "00:06"
night_end: "04:49"
morning:
astronomical_twilight_begin: "04:49"
astronomical_twilight_end: "05:21"
nautical_twilight_begin: "05:21"
nautical_twilight_end: "05:53"
civil_twilight_begin: "05:53"
civil_twilight_end: "06:20"
blue_hour_begin: "05:42"
blue_hour_end: "06:03"
golden_hour_begin: "06:03"
golden_hour_end: "06:57"
sunrise: "06:20"
sunset: "19:00"
evening:
golden_hour_begin: "18:23"
golden_hour_end: "19:16"
blue_hour_begin: "19:16"
blue_hour_end: "19:38"
civil_twilight_begin: "19:00"
civil_twilight_end: "19:27"
nautical_twilight_begin: "19:27"
nautical_twilight_end: "19:59"
astronomical_twilight_begin: "19:59"
astronomical_twilight_end: "20:31"
night_begin: "20:31"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:40"
moon_phase: "WAXING_CRESCENT"
moonrise: "08:45"
moonset: "22:10"
moon_status: "-"
- date: "2026-03-19"
mid_night: "00:06"
night_end: "04:47"
morning:
astronomical_twilight_begin: "04:47"
astronomical_twilight_end: "05:19"
nautical_twilight_begin: "05:19"
nautical_twilight_end: "05:51"
civil_twilight_begin: "05:51"
civil_twilight_end: "06:18"
blue_hour_begin: "05:40"
blue_hour_end: "06:01"
golden_hour_begin: "06:01"
golden_hour_end: "06:55"
sunrise: "06:18"
sunset: "19:02"
evening:
golden_hour_begin: "18:25"
golden_hour_end: "19:18"
blue_hour_begin: "19:18"
blue_hour_end: "19:40"
civil_twilight_begin: "19:02"
civil_twilight_end: "19:29"
nautical_twilight_begin: "19:29"
nautical_twilight_end: "20:01"
astronomical_twilight_begin: "20:01"
astronomical_twilight_end: "20:33"
night_begin: "20:33"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:44"
moon_phase: "WAXING_CRESCENT"
moonrise: "09:30"
moonset: "23:05"
moon_status: "-"
application/xml:
schema:
$ref: '#/components/schemas/AstronomyLookupResponse'
example: |
<LinkedHashMap>
<location>
<latitude>40.76473</latitude>
<longitude>-74.00084</longitude>
<country_name>United States</country_name>
<state_prov>New York</state_prov>
<city>New York</city>
<locality>Midtown West</locality>
<elevation>9</elevation>
</location>
<astronomy>
<date>2026-03-18</date>
<current_time>15:54:15.261</current_time>
<mid_night>01:03</mid_night>
<night_end>05:31</night_end>
<morning>
<astronomical_twilight_begin>05:31</astronomical_twilight_begin>
<astronomical_twilight_end>06:03</astronomical_twilight_end>
<nautical_twilight_begin>06:03</nautical_twilight_begin>
<nautical_twilight_end>06:35</nautical_twilight_end>
<civil_twilight_begin>06:35</civil_twilight_begin>
<civil_twilight_end>07:02</civil_twilight_end>
<blue_hour_begin>06:24</blue_hour_begin>
<blue_hour_end>06:46</blue_hour_end>
<golden_hour_begin>06:46</golden_hour_begin>
<golden_hour_end>07:38</golden_hour_end>
</morning>
<sunrise>07:02</sunrise>
<sunset>19:06</sunset>
<evening>
<golden_hour_begin>18:30</golden_hour_begin>
<golden_hour_end>19:22</golden_hour_end>
<blue_hour_begin>19:22</blue_hour_begin>
<blue_hour_end>19:44</blue_hour_end>
<civil_twilight_begin>19:06</civil_twilight_begin>
<civil_twilight_end>19:33</civil_twilight_end>
<nautical_twilight_begin>19:33</nautical_twilight_begin>
<nautical_twilight_end>20:05</nautical_twilight_end>
<astronomical_twilight_begin>20:05</astronomical_twilight_begin>
<astronomical_twilight_end>20:38</astronomical_twilight_end>
</evening>
<night_begin>20:38</night_begin>
<sun_status>-</sun_status>
<solar_noon>13:04</solar_noon>
<day_length>12:04</day_length>
<sun_altitude>33.35169743090959</sun_altitude>
<sun_distance>148782269.19009596</sun_distance>
<sun_azimuth>234.07341944671086</sun_azimuth>
<moon_phase>NEW_MOON</moon_phase>
<moonrise>06:44</moonrise>
<moonset>18:57</moonset>
<moon_status>-</moon_status>
<moon_altitude>31.430127664137917</moon_altitude>
<moon_distance>374392.1525559059</moon_distance>
<moon_azimuth>237.27212480757834</moon_azimuth>
<moon_parallactic_angle>39.582319837764366</moon_parallactic_angle>
<moon_illumination_percentage>-0.07</moon_illumination_percentage>
<moon_angle>357.01360045404493</moon_angle>
</astronomy>
</LinkedHashMap>
"400":
description: |
Bad Request – Possible reasons include:
- If the provided IPv4 or IPv6 address is invalid.
- If special character(s) `( ) [ ] { } | ^ \`` is passed in the
API URL either as a parameter or its value.
- If `dateStart` or `dateEnd` is not in the format `yyyy-MM-dd`.
- If the span between `dateStart` and `dateEnd` is greater than
**90 days**.
- If the provided values for `lat` and `long` are not numbers,
or fall outside the acceptable ranges.
- If the provided `elevation` value exceeds **10,000 meters**.
- If the provided `time_zone` is invalid or unrecognized.
- If an invalid or unsupported `lang` parameter is provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Invalid IPv4 or IPv6 address
value:
message: "Provided name, service or IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Invalid characters in request
value:
message: "Invalid character found in the request target."
invalidDateFormat:
summary: Invalid date format
value:
message: "You must provide date in the 'yyyy-MM-dd' format"
dateRangeExceeded:
summary: Date range exceeds 90 days
value:
message: "Date range cannot exceed 90 days."
invalidCoordinates:
summary: Coordinates out of range
value:
message: "Longitude must be between -180 and 180 or latitude must be between -90 and 90."
invalidElevation:
summary: Elevation exceeds maximum
value:
message: "Elevation cannot be greater than 10000 meters."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
invalidLang:
summary: Unsupported language parameter
value:
message: "This 'xx' lang is not valid. Please use 'en' as the default language."
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key.
- If your account has been disabled or locked by the admin.
- When the request is made using an API key for a database
subscription.
- When the request is made on a paused subscription.
- If your subscription trial has expired.
- If your active-until date has passed.
- A language other than English is specified in the `lang`
parameter while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at [email protected]"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at [email protected]"
databaseSubscription:
summary: Database subscription key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
pausedSubscripti
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ipgeolocation/refs/heads/main/openapi/ipgeolocation-astronomy-openapi.yml