Astronomy API: Astro Position Service

Calculate Positions and Data for Astronomical Objects at Specific Times.

Legacy Notice

Our Astro Position Service used to be called astrodata. This is why the service still uses the request handle astrodata. 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 Position Service can be used to 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 Moon's illuminated side as well as the midpoint angle of the Moon's bright limb at any point in time. Unlike the Astro Event Service, the Astro Position 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 Astro Event Service. In this service, you are billed per 300 data points. 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 Endpoint

HTTP Endpoint: https://api.xmltime.com/astrodata

Request Parameters

Name	Description	Required
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 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

Response Elements:

Name	Description
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/astrodataobject=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>