Astronomy API: Astro Event Service

Legacy Notice

Our Astro Event Service used to be called astronomy. This is why the service still uses the request handle astronomy. For legacy reasons, we will keep this handle. The content itself has not changed, only the name of the service has been updated.

Documentation

The Astro Event Service can be used retrieve the sunrise, sunset, moonrise, moonset, solar noon and twilight times for all locations in our database. The service also returns the azimuth of the events, the altitude, and the distance to the sun for the noon event.

Further information about several other parameters, including the various twilight events can be found on the About the Sunrise and Sunset Calculator page.

Note: For locations north of the arctic circle, or south of the antarctic circle, the assumptions that there is exactly one sunrise and one sunset event per day, or that the sun will rise before it sets, are not true! The same is the case for twilight events. Depending on the date, there may be two sunset events on the same day or the sun first sets and rises shortly thereafter. For an example of this unusual sequence, please see the sunrise and sunset times for Svalbard during the month of August.

This service can be tested with the Query Builder.

Request Parameters:

NameDescriptionRequired
object

Specify which astronomical object you are interested in. Currently, only sun and moon are supported.

Type: String / Astronomical Object Id

Yes
placeid

Specify the ID of the location you would like to retrieve information for. To retrieve the information for multiple places, the corresponding IDs can either be specified as a comma separated list, or by supplying the parameter multiple times (or any combination). There is a limit of maximum 10 locations per requests.

Note: It is also possible to specify coordinates or IATA/ICAO codes for airports, see the documentation for the type Location Id for detailed information.

Type: String / Location Id

Yes
startdt

Specify the ISO 8601 date for the first date you are interested in.

Type: String / ISO8601 Date

Yes
enddt

The last date you are interested in. The service can be used to calculate data for a maximum of 31 days in a row. If the end date is omitted, only one day is retrieved.

Type: String / ISO8601 Date

No
types

Selection of which astronomical events you are interested in. To combine multiple classes, either separate them with commas or repeat the parameter with a different value. A negation can be expressed by prefixing the value with a tilde (~) character. Values are combined in the order they are supplied.

Type: String / Astronomy Event Class

No
geo

Return longitude and latitude for the geo object.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
isotime

Adds time stamps (local time) in ISO 8601 format to all events.

Type: Boolean

Accepted values: 0 or 1

Default value: 0

No
lang

The preferred language for the texts. An error will be raised if the language code cannot be recognized. In case the text for a specific event cannot be retrieved in the requested language it will be returned in English instead. This is also the default language.

In case you have specific needs for a certain language/translation, please contact us.

Type: String / ISO639 Language Code

Default value: en

Note: Due to technical limitations, time zone names cannot be translated at the moment.
No
radius

Search radius for translating coordinates (parameter placeid) to locations. Coordinates that could not be translated will yield results for the actual geographical position – if you would like to query for times at an exact location, specify a radius of zero (0).

Type: Integer

Default value: infinite (but only locations within the same country and time zone are considered)

No
utctime

Adds UTC time stamps in ISO 8601 format to all events.

Type: Boolean

Accepted values: 0 or 1

Default value: 0

No
template

Specify the name of a template if you want the result rendered in a specific format (e.g. CSV). The number at the end of the value specifies what types of column you want returned.

Type: String

Accepted values: csvN or csvsimpleN (where N is a number between 1 and 4, see Supported Text Templates below)

Default value: None

No
csvstyle

When returning a CSV template you can set this parameter to choose whether the result should be separated by a comma or a semicolon.

Type: Number

Accepted values: 1 (comma, US-style) or 2 (semicolon, Euro-style)

Default value: 1

No

See also the section “General Parameters”.

Response Elements:

NameDescription
location (XML), locations (JSON)

This element wraps the information for the locations in the request. For the XML format, it will be repeated multiple times, while for JSON, it is modeled as an array of objects with the same content.

Type: Array of LocationAstroType

Supported Text Templates:

In addition to retrieving these text templates via our API, you can also try out and download this data from our Data Download page.

csvsimpleN

To use this template, specify this parameter combination: out=text&template=csvsimpleN, where N is the identifier for which columns you want returned (see Table 4.1 below).

This CSV-template returns a simplified format of the requested astronomy result. In this template, there will be only one row per date for the requested country and year. By default, the result will be formatted in US CSV-format (comma as separator). It is possible to return the CSV in European CSV-format (semicolon as separator) by including csvstyle=2 in the request. Several different options are available to define which columns you want to include in your result. Some options are only available for the sun object type. See Table 4.1 below to see which columns are included for which object types.

csvN

To use this template, specify this parameter combination: out=text&template=csvN, where N is the identifier for which columns you want returned (see Table 4.1 below).

This CSV-template returns a more advanced format of the requested astronomy result. In this template, there will be multiple lines per date. This is useful for cases where there can be more than one rise and set in a day. The Line column will contain a number for each row in a date. By default, the result will be formatted in US CSV-format (comma as separator). It is possible to return the CSV in European CSV-format (semicolon as separator) by including csvstyle=2 in the request. Several different options are available to define which columns you want to include in your result. Some options are only available for the sun object type. See Table 4.1 below to see which columns are included for which object types.

Table 4.1. Supported Columns for astronomy CSV Templates

This table shows the supported columns for the given Astronomical Object Id. template parameters are shown horizontally, columns included in the result are shown vertically.

Columncsv1 / csvsimple1csv2 / csvsimple2csv3 / csvsimple3csv4 / csvsimple4
Date sun | moonsun | moonsunsun | moon
Rise sun | moonsun | moonsunsun | moon
Set sun | moonsun | moonsunsun | moon
DayLength sunsun sun
DayLengthDiff sunsun sun
Meridian sun | moon  sun | moon
Altitude sun | moon  sun | moon
Distance sun | moon  sun | moon
Illuminated moon  moon
Phase moonmoon moon
Phasetime moonmoon moon
PosAngle moon  moon
RiseAzimuth  sun | moon sun | moon
SetAzimuth  sun | moon sun | moon
Twi18Begin   sunsun
Twi18Duration    sun
Twi18End   sunsun
Twi12Begin   sunsun
Twi12Duration    sun
Twi12End   sunsun
Twi6Begin   sunsun
Twi6Duration    sun
Twi6End   sunsun
Line sun | moonsun | moonsun | moonsun | moon

Example JSON Request:

https://api.xmltime.com/astronomy?object=sun&placeid=152&startdt=2012-03-19&enddt=2012-03-20&types=all&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response:


{
  "version": 3,
  "billing": {
    "credits": 1
  },
  "locations": [
    {
      "id": "152",
      "geo": {
        "name": "Melbourne",
        "state": "Victoria",
        "country": {
          "id": "au",
          "name": "Australia"
        },
        "latitude": -37.814,
        "longitude": 144.963
      },
      "matchparam": "152",
      "astronomy": {
        "objects": [
          {
            "name": "sun",
            "days": [
              {
                "date": "2012-03-19",
                "events": [
                  {
                    "type": "antimeridian",
                    "hour": 1,
                    "min": 28,
                    "sec": 3
                  },
                  {
                    "type": "twi18_start",
                    "hour": 5,
                    "min": 53,
                    "sec": 58
                  },
                  {
                    "type": "twi12_start",
                    "hour": 6,
                    "min": 25,
                    "sec": 9
                  },
                  {
                    "type": "twi6_start",
                    "hour": 6,
                    "min": 55,
                    "sec": 51
                  },
                  {
                    "type": "rise",
                    "hour": 7,
                    "min": 22,
                    "sec": 5,
                    "azimuth": 91.3
                  },
                  {
                    "type": "meridian",
                    "hour": 13,
                    "min": 27,
                    "sec": 55,
                    "altitude": 52.6,
                    "distance": 148947000
                  },
                  {
                    "type": "set",
                    "hour": 19,
                    "min": 33,
                    "sec": 5,
                    "azimuth": 268.9
                  },
                  {
                    "type": "twi6_end",
                    "hour": 19,
                    "min": 59,
                    "sec": 16
                  },
                  {
                    "type": "twi12_end",
                    "hour": 20,
                    "min": 29,
                    "sec": 53
                  },
                  {
                    "type": "twi18_end",
                    "hour": 21,
                    "min": 0,
                    "sec": 58
                  }
                ],
                "daylength": "12:11:00",
                "moonphase": "waningcrescent"
              },
              {
                "date": "2012-03-20",
                "events": [
                  {
                    "type": "antimeridian",
                    "hour": 1,
                    "min": 27,
                    "sec": 46
                  },
                  {
                    "type": "twi18_start",
                    "hour": 5,
                    "min": 55,
                    "sec": 1
                  },
                  {
                    "type": "twi12_start",
                    "hour": 6,
                    "min": 26,
                    "sec": 9
                  },
                  {
                    "type": "twi6_start",
                    "hour": 6,
                    "min": 56,
                    "sec": 48
                  },
                  {
                    "type": "rise",
                    "hour": 7,
                    "min": 23,
                    "sec": 1,
                    "azimuth": 90.8
                  },
                  {
                    "type": "meridian",
                    "hour": 13,
                    "min": 27,
                    "sec": 37,
                    "altitude": 52.2,
                    "distance": 148989000
                  },
                  {
                    "type": "set",
                    "hour": 19,
                    "min": 31,
                    "sec": 34,
                    "azimuth": 269.4
                  },
                  {
                    "type": "twi6_end",
                    "hour": 19,
                    "min": 57,
                    "sec": 44
                  },
                  {
                    "type": "twi12_end",
                    "hour": 20,
                    "min": 28,
                    "sec": 19
                  },
                  {
                    "type": "twi18_end",
                    "hour": 20,
                    "min": 59,
                    "sec": 20
                  }
                ],
                "daylength": "12:08:33",
                "moonphase": "waningcrescent"
              }
            ],
            "current": {
              "azimuth": 235.3,
              "altitude": -17.2,
              "distance": 148493808
            }
          }
        ]
      }
    }
  ]
}
    

Example XML Request:

https://api.xmltime.com/astronomy?object=sun&placeid=152&startdt=2012-03-19&enddt=2012-03-20&types=all&version=3&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example XML response:


<?xml version="1.0" encoding="UTF-8"?>
<data version="3">
  <billing>
    <credits>1</credits>
  </billing>
  <location id="152" matchparam="152">
    <geo>
      <name>Melbourne</name>
      <state>Victoria</state>
      <country id="au">Australia</country>
      <latitude>-37.814</latitude>
      <longitude>144.963</longitude>
    </geo>
    <astronomy>
      <object name="sun">
        <day date="2012-03-19" daylength="12:11:00" moonphase="waningcrescent">
          <event type="antimeridian" hour="1" min="28" sec="3"/>
          <event type="twi18_start" hour="5" min="53" sec="58"/>
          <event type="twi12_start" hour="6" min="25" sec="9"/>
          <event type="twi6_start" hour="6" min="55" sec="51"/>
          <event type="rise" hour="7" min="22" sec="5" azimuth="91.3"/>
          <event type="meridian" hour="13" min="27" sec="55" altitude="52.6" distance="148947000"/>
          <event type="set" hour="19" min="33" sec="5" azimuth="268.9"/>
          <event type="twi6_end" hour="19" min="59" sec="16"/>
          <event type="twi12_end" hour="20" min="29" sec="53"/>
          <event type="twi18_end" hour="21" min="0" sec="58"/>
        </day>
        <day date="2012-03-20" daylength="12:08:33" moonphase="waningcrescent">
          <event type="antimeridian" hour="1" min="27" sec="46"/>
          <event type="twi18_start" hour="5" min="55" sec="1"/>
          <event type="twi12_start" hour="6" min="26" sec="9"/>
          <event type="twi6_start" hour="6" min="56" sec="48"/>
          <event type="rise" hour="7" min="23" sec="1" azimuth="90.8"/>
          <event type="meridian" hour="13" min="27" sec="37" altitude="52.2" distance="148989000"/>
          <event type="set" hour="19" min="31" sec="34" azimuth="269.4"/>
          <event type="twi6_end" hour="19" min="57" sec="44"/>
          <event type="twi12_end" hour="20" min="28" sec="19"/>
          <event type="twi18_end" hour="20" min="59" sec="20"/>
        </day>
        <current>
          <azimuth>234.8</azimuth>
          <altitude>-17.6</altitude>
          <distance>148493744</distance>
        </current>
      </object>
    </astronomy>
  </location>
</data>
    

Example Simple CSV Request:

https://api.xmltime.com/astronomy?object=moon&placeid=152&startdt=2015-01-01&enddt=2015-01-20&types=all&version=3&out=text&template=csvsimple4&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example Simple CSV (template=csvsimple4&object=moon) response


Date,Rise,Set,RiseAzimuth,SetAzimuth,Meridian,Altitude,Distance,Illuminated,Phase,PhaseTime,PosAngle
2015-01-01,16:58:14,02:51:54,69.9,288.2,22:18:14,35.2,385166,86.0%,waxinggibbous,,163.5
2015-01-02,17:57:02,03:34:53,67.3,291.4,23:10:07,33.5,388647,92.6%,waxinggibbous,,165.2
2015-01-03,18:52:14,04:21:20,66.1,293.3,,,,,waxinggibbous,,
2015-01-04,19:43:02,05:11:11,66.3,294.0,00:01:52,32.8,392056,97.1%,waxinggibbous,,164.2
2015-01-05,20:29:03,06:03:50,67.7,293.3,00:52:51,33.1,395346,99.4%,fullmoon,15:53:13,148.5
2015-01-06,21:10:26,06:58:20,70.1,291.4,01:42:27,34.4,398426,99.6%,waninggibbous,,54.9
2015-01-07,21:47:45,07:53:41,73.5,288.5,02:30:16,36.5,401160,97.8%,waninggibbous,,28.6
2015-01-08,22:21:47,08:49:07,77.5,284.8,03:16:12,39.2,403370,94.2%,waninggibbous,,24.8
2015-01-09,22:53:30,09:44:12,81.9,280.5,04:00:25,42.5,404854,88.8%,waninggibbous,,24.3
2015-01-10,23:23:50,10:38:54,86.7,275.8,04:43:22,46.1,405408,82.1%,waninggibbous,,24.3
2015-01-11,23:53:44,11:33:29,91.5,270.9,05:25:37,50.0,404853,74.2%,waninggibbous,,24.2
2015-01-12,,12:28:21,,266.0,06:07:52,53.9,403066,65.3%,waninggibbous,,23.7
2015-01-13,00:24:14,13:24:02,96.4,261.1,06:50:54,57.8,399999,55.7%,thirdquarter,20:46:27,22.6
2015-01-14,00:56:24,14:21:00,101.0,256.6,07:35:29,61.5,395708,45.7%,waningcrescent,,20.9
2015-01-15,01:31:23,15:19:25,105.3,252.5,08:22:25,64.8,390371,35.6%,waningcrescent,,18.6
2015-01-16,02:10:30,16:19:06,109.0,249.2,09:12:18,67.5,384294,25.8%,waningcrescent,,15.7
2015-01-17,02:55:02,17:19:12,111.8,247.1,10:05:29,69.5,377908,16.7%,waningcrescent,,12.5
2015-01-18,03:46:05,18:18:18,113.4,246.3,11:01:47,70.4,371748,9.1%,waningcrescent,,9.8
2015-01-19,04:44:02,19:14:43,113.5,247.3,12:00:24,70.1,366392,3.5%,waningcrescent,,9.7
2015-01-20,05:48:15,20:07:08,111.8,249.9,13:00:06,68.4,362376,0.5%,waningcrescent,,27.6
        

Example Advanced CSV Request:

https://api.xmltime.com/astronomy?object=moon&placeid=152&startdt=2015-01-01&enddt=2015-01-20&types=all&version=3&out=text&template=csv4&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example Advanced CSV (template=csv4&object=moon) response


Date,Line,Rise,Set,RiseAzimuth,SetAzimuth,Meridian,Altitude,Distance,Illuminated,Phase,PhaseTime,PosAngle
2015-01-01,1,,02:51:54,,288.2,22:18:14,35.2,385166,86.0%,waxinggibbous,,163.5
2015-01-01,2,16:58:14,,0.00,,,,,,,,
2015-01-02,1,,03:34:53,,291.4,23:10:07,33.5,388647,92.6%,waxinggibbous,,165.2
2015-01-02,2,17:57:02,,0.00,,,,,,,,
2015-01-03,1,,04:21:20,,293.3,,,,,waxinggibbous,,
2015-01-03,2,18:52:14,,0.00,,,,,,,,
2015-01-04,1,,05:11:11,,294.0,00:01:52,32.8,392056,97.1%,waxinggibbous,,164.2
2015-01-04,2,19:43:02,,0.00,,,,,,,,
2015-01-05,1,,06:03:50,,293.3,00:52:51,33.1,395346,99.4%,fullmoon,15:53:13,148.5
2015-01-05,2,20:29:03,,0.00,,,,,,,,
2015-01-06,1,,06:58:20,,291.4,01:42:27,34.4,398426,99.6%,waninggibbous,,54.9
2015-01-06,2,21:10:26,,0.00,,,,,,,,
2015-01-07,1,,07:53:41,,288.5,02:30:16,36.5,401160,97.8%,waninggibbous,,28.6
2015-01-07,2,21:47:45,,0.00,,,,,,,,
2015-01-08,1,,08:49:07,,284.8,03:16:12,39.2,403370,94.2%,waninggibbous,,24.8
2015-01-08,2,22:21:47,,0.00,,,,,,,,
2015-01-09,1,,09:44:12,,280.5,04:00:25,42.5,404854,88.8%,waninggibbous,,24.3
2015-01-09,2,22:53:30,,0.00,,,,,,,,
2015-01-10,1,,10:38:54,,275.8,04:43:22,46.1,405408,82.1%,waninggibbous,,24.3
2015-01-10,2,23:23:50,,0.00,,,,,,,,
2015-01-11,1,,11:33:29,,270.9,05:25:37,50.0,404853,74.2%,waninggibbous,,24.2
2015-01-11,2,23:53:44,,0.00,,,,,,,,
2015-01-12,1,,12:28:21,,266.0,06:07:52,53.9,403066,65.3%,waninggibbous,,23.7
2015-01-13,1,00:24:14,13:24:02,96.4,261.1,06:50:54,57.8,399999,55.7%,thirdquarter,20:46:27,22.6
2015-01-14,1,00:56:24,14:21:00,101.0,256.6,07:35:29,61.5,395708,45.7%,waningcrescent,,20.9
2015-01-15,1,01:31:23,15:19:25,105.3,252.5,08:22:25,64.8,390371,35.6%,waningcrescent,,18.6
2015-01-16,1,02:10:30,16:19:06,109.0,249.2,09:12:18,67.5,384294,25.8%,waningcrescent,,15.7
2015-01-17,1,02:55:02,17:19:12,111.8,247.1,10:05:29,69.5,377908,16.7%,waningcrescent,,12.5
2015-01-18,1,03:46:05,18:18:18,113.4,246.3,11:01:47,70.4,371748,9.1%,waningcrescent,,9.8
2015-01-19,1,04:44:02,19:14:43,113.5,247.3,12:00:24,70.1,366392,3.5%,waningcrescent,,9.7
2015-01-20,1,05:48:15,20:07:08,111.8,249.9,13:00:06,68.4,362376,0.5%,waningcrescent,,27.6