astrodata – Calculate data on Astronomical Objects on Specific Times

The astrodata service can be used retrieve the altitude, azimuth and distance to the Moon and the Sun for all locations in our database. The service also returns the moon phase, the fraction of the Moons illuminated side as well as the midpoint angle of the Moons bright limb at any point in time. Unlike the astronomy service, the astrodata service can be queried on a specific point in time, down to the second.

Since you can query for multiple objects (2), multiple locations (10) and for multiple intervals (50) in a single query, the queries are billed differently for this service than for the astronomy service. In this service, you are billed per 300 data point. This means that if you request data for both the sun and the moon, for 10 locations and for 15 different times it will cost you two credits instead of one since 2 objects * 10 locations * 15 timestamps = 300 data points.

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. To retrieve the information for multiple objects, the corresponding names can either be specified as a comma separated list, or by supplying the parameter multiple times (or any combination). Currently, only sun and moon are supported as objects.

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
interval

Specify the point(s) in time you would like to calculate data for. Multiple results can be retrieved by specifying several timestamps separated by comma, maximum 50.

Type: String/ISO8601 Timestamp

Yes
localtime

Specify whether or not the intervals should be considered the local time for the place(s) or UTC time.

Type: Boolean

Accepted values: 0 or 1

Default value: 0

No
utctime

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

Type: Boolean

Accepted values: 0 or 1

Default value: 0

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 email api@timeanddate.com.

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

See also the section called “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

Example JSON Request. 

https://api.xmltime.com/astrodata?object=sun,moon&placeid=298,198&interval=2019-11-01T07:30:15,2019-11-02T08:30:15&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
	"version": 3,
	"billing": {
		"credits": 1
	},
	"locations": [{
		"id": "298",
		"geo": {
			"name": "Cardiff",
			"state": "Wales",
			"country": {
				"id": "gb",
				"name": "United Kingdom"
			},
			"latitude": 51.483,
			"longitude": -3.184
		},
		"matchparam": "298",
		"astronomy": {
			"objects": [{
				"name": "sun",
				"results": [{
					"azimuth": 117.2,
					"altitude": 2.9,
					"distance": 148498672
				},{
					"azimuth": 129.7,
					"altitude": 10.2,
					"distance": 148457440
				}]
			},{
				"name": "moon",
				"results": [{
					"azimuth": 78.7,
					"altitude": -38.8,
					"distance": 384358,
					"illuminated": 21,
					"posangle": 39.8,
					"moonphase": "waxingcrescent"
				},{
					"azimuth": 80.1,
					"altitude": -38.1,
					"distance": 390326,
					"illuminated": 30,
					"posangle": 35.2,
					"moonphase": "waxingcrescent"
				}]
			}]
		}
	},{
		"id": "198",
		"geo": {
			"name": "Philadelphia",
			"state": "Pennsylvania",
			"country": {
				"id": "us",
				"name": "United States"
			},
			"latitude": 39.952,
			"longitude": -75.164
		},
		"matchparam": "198",
		"astronomy": {
			"objects": [{
				"name": "sun",
				"results": [{
					"azimuth": 66.8,
					"altitude": -45.7,
					"distance": 148498672
				},{
					"azimuth": 79.6,
					"altitude": -34.9,
					"distance": 148457440
				}]
			},{
				"name": "moon",
				"results": [{
					"azimuth": 318.8,
					"altitude": -68.9,
					"distance": 384358,
					"illuminated": 21,
					"posangle": 325.2,
					"moonphase": "waxingcrescent"
				},{
					"azimuth": 321.5,
					"altitude": -69.7,
					"distance": 390326,
					"illuminated": 30,
					"posangle": 322.1,
					"moonphase": "waxingcrescent"
				}]
			}]
		}
	}]
}

Example XML Request. 

https://api.xmltime.com/astrodata?object=sun,moon&placeid=298,198&interval=2019-11-01T07:30:15,2019-11-02T08:30:15&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="298" matchparam="298">
    <geo>
      <name>Cardiff</name>
      <state>Wales</state>
      <country id="gb">United Kingdom</country>
      <latitude>51.483</latitude>
      <longitude>-3.184</longitude>
    </geo>
    <astronomy>
      <object name="sun">
        <result>
          <azimuth>117.2</azimuth>
          <altitude>2.9</altitude>
          <distance>148498672</distance>
        </result>
        <result>
          <azimuth>129.7</azimuth>
          <altitude>10.2</altitude>
          <distance>148457440</distance>
        </result>
      </object>
      <object name="moon">
        <result>
          <azimuth>78.7</azimuth>
          <altitude>-38.8</altitude>
          <distance>384358</distance>
          <illuminated>21</illuminated>
          <posangle>39.8</posangle>
          <moonphase>waxingcrescent</moonphase>
        </result>
        <result>
          <azimuth>80.1</azimuth>
          <altitude>-38.1</altitude>
          <distance>390326</distance>
          <illuminated>30</illuminated>
          <posangle>35.2</posangle>
          <moonphase>waxingcrescent</moonphase>
        </result>
      </object>
    </astronomy>
  </location>
  <location id="198" matchparam="198">
    <geo>
      <name>Philadelphia</name>
      <state>Pennsylvania</state>
      <country id="us">United States</country>
      <latitude>39.952</latitude>
      <longitude>-75.164</longitude>
    </geo>
    <astronomy>
      <object name="sun">
        <result>
          <azimuth>66.8</azimuth>
          <altitude>-45.7</altitude>
          <distance>148498672</distance>
        </result>
        <result>
          <azimuth>79.6</azimuth>
          <altitude>-34.9</altitude>
          <distance>148457440</distance>
        </result>
      </object>
      <object name="moon">
        <result>
          <azimuth>318.8</azimuth>
          <altitude>-68.9</altitude>
          <distance>384358</distance>
          <illuminated>21</illuminated>
          <posangle>325.2</posangle>
          <moonphase>waxingcrescent</moonphase>
        </result>
        <result>
          <azimuth>321.5</azimuth>
          <altitude>-69.7</altitude>
          <distance>390326</distance>
          <illuminated>30</illuminated>
          <posangle>322.1</posangle>
          <moonphase>waxingcrescent</moonphase>
        </result>
      </object>
    </astronomy>
  </location>
</data>

prev top | next >
Terms & Conditions Copyright © Time and Date AS
All data supplied by timeanddate.com