Astronomy API

The Astronomy API can used to get the location-based rise and set times for the Sun and the Moon, including current position, angle, and distance of the Sun and the Moon for a date. You can call the Astronomy API for two ways:

  • For Location Coordinates (latitude & longitude)
  • For any IP address

Here is the full response from Astronomy API:

{
    "location": {
        "country_code2": "AU",
        "country_name": "Australia",
        "state_prov": "Queensland",
        "district": "South Brisbane",
        "city": "South Brisbane",
        "latitude": -27.4748,
        "longitude": 153.017
    },
    "date": "2018-12-06",
    "sunrise": "04:45",
    "sunset": "18:34",
    "solar_noon": "11:35",
    "day_length": "13:49",
    "sun_altitude": -21.143545645150947,
    "sun_distance": 147428191.06042647,
    "sun_azimuth": 228.41594409984202,
    "moonrise": "04:37",
    "moonset": "18:24",
    "moon_altitude": -31.73549899631431,
    "moon_distance": 390566.89126533194,
    "moon_azimuth": 225.04049104588287,
    "moon_parallactic_angle": 115.40880127316198
}

Response in Multiple Languages

The geolocation information in the response from Astronomy API can be retreived in the following languages:

  • English (en)
  • German (de)
  • Russian (ru)
  • Japanese (ja)
  • French (fr)
  • Chinese Simplified (cn)
  • Spanish (es)
  • Czech (cs)
  • Italian (it)

By default, the API responds in English. You can change the response language by passing the language code as a query parameter lang. Here are a few curl examples:

# Get astronomical information for an IPv4 IP Address = 1.1.1.1 in Chinese language
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1&lang=cn'

Only the paid plan subscriptions can get the response in languages other than English. All the other users will only get the response in English.

Astronomy API has three different variations. Here is the detail for each. The response in each variation remains the same, however, the different input source is passed in each variation.

Getting Astronomical Information for Location Coordinates

You can pass the latitude and longitude of a location as query parameters to get the astronomical information. Here is a curl example:

# Get astronomical information for -27.4748, 153.017 coordinates
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&lat=-27.4748&long=153.017'

{
    "location": {
        "latitude": -27.4748,
        "longitude": 153.017
    },
    "date": "2018-12-06",
    "sunrise": "04:45",
    "sunset": "18:34",
    "solar_noon": "11:36",
    "day_length": "13:49",
    "sun_altitude": -21.588394029942094,
    "sun_distance": 147428191.06042644,
    "sun_azimuth": 227.94952581447723,
    "moonrise": "04:37",
    "moonset": "18:24",
    "moon_altitude": -32.13780841569351,
    "moon_distance": 390575.48307261645,
    "moon_azimuth": 224.48040542423513,
    "moon_parallactic_angle": 115.68236335346243
}

Getting Astronomical Information for an IPv4 or IPv6 Address

You can pass any IPv4 or IPv6 address as a query parameter to get the astronomical information. Here is a curl example:

# Get astronomical information for an IP address '1.1.1.1'
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1'

{
    "location": {
        "country_code2": "AU",
        "country_name": "Australia",
        "state_prov": "Queensland",
        "district": "South Brisbane",
        "city": "South Brisbane",
        "latitude": -27.4748,
        "longitude": 153.017
    },
    "date": "2018-12-06",
    "sunrise": "04:45",
    "sunset": "18:34",
    "solar_noon": "11:36",
    "day_length": "13:49",
    "sun_altitude": -21.829528786363543,
    "sun_distance": 147428191.06042647,
    "sun_azimuth": 227.69315006727666,
    "moonrise": "04:37",
    "moonset": "18:24",
    "moon_altitude": -32.35541529251305,
    "moon_distance": 390580.16648038325,
    "moon_azimuth": 224.1723473685741,
    "moon_parallactic_angle": 115.83663304882123
}

Note: When you get the astronomical information through an IP address, API will also return the extra fields about place information along with the astronomical information.

Using Client or Machine IP Address

You can call the astronomy API without passing any coordinates or IP address as well. It will use the calling machine's IP address to return the regional astronomical information. Here is a curl example:

$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY'

Note: In above example, we used API Key everywhere. Astronomy API can be called from client side JavaScript with Request Origin authentication as well on paid plans.

Getting Astronomical Information for a Specific Date

Along with the above two variations, there is a third variation that you can get the astronomical information for a specific date. You can pass date query parameter with the date value. Here are the curl example calls:

# Get astronomical information for -27.4748, 153.017 coordinates
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&lat=-27.4748&long=153.017&date=2018-01-01'

# Get astronomical information for an IP address
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1&date=2018-01-01'

Note: Date must be in 'YYYY-MM-DD' format. No other format will be accepted and by default, current date will be used.