Astronomy API: Documentation

Get Started with our Astronomy APIs

Get information on astronomical events and the position of celestial objects – with a few lines of code in your language of choice.

Install Official Libraries

To get started, use one of timeanddate.com's official API libraries for your programming language. If your language isn't supported, you can send the requests manually over HTTP. If you would like to request an official library for your language, please contact us.

$ git clone https://github.com/timeanddate/libtad-net


    $ git clone https://github.com/timeanddate/libtad-net

Build Query

The API library is now installed. Next, you specify the data you want, the location, and the dates you are querying for. To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account.

Don't have a key? Sign up for our free trial and receive an access key to try it out.

var coordinates = new Coordinates(59.743m, 10.204m);
var place = new LocationId(coordinates);
var date = new DateTime(2015, 1, 1);
var service = new AstronomyService('accessKey', 'secretKey');

service.Types = AstronomyEventClass.Meridian | AstronomyEventClass.Phase;


    var coordinates = new Coordinates(59.743m, 10.204m);
    var place = new LocationId(coordinates);
    var date = new DateTime(2020, 11, 26);
    var service = new AstronomyService('accessKey', 'secretKey');

    service.Types = AstronomyEventClass.Meridian | AstronomyEventClass.Phase;

Get Result

The astro_info variable will now contain the following information when the Moon is at the Meridian as well as it's phase on 2020-11-26: time, altitude, distance, and illumination of the Moon at its highest point in the night sky.

var astroInfo = service.GetAstronomicalInfo(AstronomyObjectType.Moon, place, date);


    var astroInfo = service.GetAstronomicalInfo(AstronomyObjectType.Moon, place, date);

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.

<repository>
    <id>github</id>
    <name>Time and Date API Packages</name>
    <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
</repository>
<dependency>
    <groupId>com.timeanddate</groupId>
    <artifactId>services</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

Coordinates coordinates = new Coordinates(59.743m, 10.204m);
LocationId place = new LocationId(coordinates);
TADDateTime date = new TADDateTime(2015, 1, 1);
AstronomyService service = new AstronomyService('accessKey', 'secretKey');

service.Types = EnumSet.of(AstronomyEventClass.MERIDIAN, AstronomyEventClass.MERIDIAN);


    Coordinates coordinates = new Coordinates(59.743m, 10.204m);
    LocationId place = new LocationId(coordinates);
    TADDateTime date = new TADDateTime(2015, 1, 1);
    AstronomyService service = new AstronomyService('accessKey', 'secretKey');
    
    service.Types = EnumSet.of(AstronomyEventClass.MERIDIAN, AstronomyEventClass.MERIDIAN);

Get Result

List<AstronomyLocation> astroInfo = service.getAstronomicalInfo(AstronomyObjectType.Moon, place, date);


    List<AstronomyLocation> astroInfo = service.getAstronomicalInfo(AstronomyObjectType.Moon, place, date);

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.

# Carthage
github "TimeAndDate/TadApi"
# CocoaPods
pod 'libtad-swift', '~> 1.0'


    # Carthage
    github "TimeAndDate/TadApi"
    # CocoaPods
    pod 'libtad-swift', '~> 1.0'

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

let astronomyService = AstronomyService(accessKey: "accessKey", secretKey:"secretKey")
let astronomyRequest = AstronomyRequest()
astronomyRequest.objects = [AstroObjectType.moon]
astronomyRequest.placeId = "+59.743-10.204m"
astronomyRequest.startDate = Date()
astronomyRequest.types = [EventClass.meridian, EventClass.phase]


    let astronomyService = AstronomyService(accessKey: "accessKey", secretKey:"secretKey")
    let astronomyRequest = AstronomyRequest()
    astronomyRequest.objects = [AstroObjectType.moon]
    astronomyRequest.placeId = "+59.743-10.204m"
    astronomyRequest.startDate = Date()
    astronomyRequest.types = [EventClass.meridian, EventClass.phase]

Get Result

    
astronomyService.getAstronomicalInfo(request:astronomyRequest) { (result, error) in 
    print(result)
}


    astronomyService.getAstronomicalInfo(request:astronomyRequest) { (result, error) in 
        print(result)
    }

Where to go next?

See our GitHub repository for more information on the Swift Library.

gem 'libtad'


    gem 'libtad'

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

place = "norway/oslo"
date = TADDateTime.new(year: 2020, month: 11, day: 26)
types = [:meridian, :phase]
client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')


    place = "norway/oslo"
    date = TADDateTime.new(year: 2020, month: 11, day: 26)
    types = [:meridian, :phase]
    client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')

Get Result

result = client.get_astro_events(object: :moon, place_id: place, types: types, start_date: date)


    result = client.get_astro_events(object: :moon, place_id: place, types: types, start_date: date)

Where to go next?

See our GitHub repository for more information on the Ruby Library.

pip3 install libtad


    $ pip3 install libtad

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

from libtad import AstronomyService
from libtad.datatypes.places import Coordinates, LocationId
from libtad.datatypes.time import TADDateTime
from libtad.datatypes.astro import AstronomyEventClass, AstronomyObjectType

coordinates = Coordinates(59.743, 10.204)
place = LocationId(coordinates)
date = TADDateTime(2020, 11, 26)
service = AstronomyService("accessKey", "secretKey")
service.types = AstronomyEventClass.Meridian | AstronomyEventClass.Phase


    from libtad import AstronomyService
    from libtad.datatypes.places import Coordinates, LocationId
    from libtad.datatypes.time import TADDateTime
    from libtad.datatypes.astro import AstronomyEventClass, AstronomyObjectType
    
    coordinates = Coordinates(59.743, 10.204)
    place = LocationId(coordinates)
    date = TADDateTime(2020, 11, 26)
    service = AstronomyService("accessKey", "secretKey")
    service.types = AstronomyEventClass.Meridian | AstronomyEventClass.Phase

Get Result

astro_info = service.get_astronomical_info(AstronomyObjectType.Moon, place, date)


    astro_info = service.get_astronomical_info(AstronomyObjectType.Moon, place, date)

Where to go next?

See our GitHub repository for more information on the Python Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.

$ ACCESSKEY="<Your Access Key>"
$ SECRETKEY="<Your Secret Key>"
$ curl -G \
        --data-urlencode "version=3" \
        --data-urlencode "prettyprint=1" \
        --data-urlencode "accesskey=$ACCESSKEY" \
        --data-urlencode "secretkey=$SECRETKEY" \
        --data-urlencode "placeid=norway/oslo" \
        --data-urlencode "object=moon" \
        --data-urlencode "types=meridian,phase" \
        --data-urlencode "startdt=2020-11-26" \
        https://api.xmltime.com/astronomy


    $ ACCESSKEY="<Your Access Key>"
    $ SECRETKEY="<Your Secret Key>"
    $ curl -G \
        --data-urlencode "version=3" \
        --data-urlencode "prettyprint=1" \
        --data-urlencode "accesskey=$ACCESSKEY" \
        --data-urlencode "secretkey=$SECRETKEY" \
        --data-urlencode "placeid=norway/oslo" \
        --data-urlencode "object=moon" \
        --data-urlencode "types=meridian,phase" \
        --data-urlencode "startdt=2020-11-26" \
        https://api.xmltime.com/astronomy

Get Result

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.

{
  "version": 3,
  "billing": {
    "credits": 1
  },
  "locations": [{
    "id": "187",
    "geo": {
      "name": "Oslo",
      "country": {
        "id": "no",
        "name": "Norway"
      },
      "latitude": 59.913,
      "longitude": 10.740
    },
    "matchparam": "187",
    "astronomy": {
      "objects": [{
        "name": "moon",
        "days": [{
          "date": "2020-11-26",
          "events": [{
            "type": "meridian",
            "hour": 21,
            "min": 36,
            "sec": 35,
            "altitude": 35.6,
            "distance": 405882,
            "illuminated": 89.0,
            "posangle": 333.7
          }],
          "moonphase": "waxinggibbous"
        }]
      }]
    }
  }]
}


    {
      "version": 3,
      "billing": {
        "credits": 1
      },
      "locations": [{
        "id": "187",
        "geo": {
          "name": "Oslo",
          "country": {
            "id": "no",
            "name": "Norway"
          },
          "latitude": 59.913,
          "longitude": 10.740
        },
        "matchparam": "187",
        "astronomy": {
          "objects": [{
            "name": "moon",
            "days": [{
              "date": "2020-11-26",
              "events": [{
                "type": "meridian",
                "hour": 21,
                "min": 36,
                "sec": 35,
                "altitude": 35.6,
                "distance": 405882,
                "illuminated": 89.0,
                "posangle": 333.7
              }],
              "moonphase": "waxinggibbous"
            }]
          }]
        }
      }]
    }

Install Official Libraries

$ git clone https://github.com/timeanddate/libtad-net


    $ git clone https://github.com/timeanddate/libtad-net

Build Query

The API library is now installed. Next, you specify the data you want, the location and the optionally the date interval you are querying for. To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account.

Don't have a key? Sign up for our free trial and receive an access key to try it out.

var coordinates = new Coordinates(59.743m, 10.204m);
var place = new LocationId(coordinates);
var date = new DateTime(2020, 11, 26);
var service = new AstrodataService('accessKey', 'secretKey');


    var coordinates = new Coordinates(59.743m, 10.204m);
    var place = new LocationId(coordinates);
    var date = new DateTime(2021, 1, 1, 14, 14, 34);
    var service = new AstrodataService('accessKey', 'secretKey');

Get Result

The result variable will now data about the sun at the exact point in time that was requested.

var result = service.GetAstroData(AstronomyObjectType.Sun, place, date);


    var result = service.GetAstroData(AstronomyObjectType.Sun, place, date);

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.

pip3 install libtad


    $ pip3 install libtad

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

from libtad import AstrodataService
from libtad.datatypes.places import Coordinates, LocationId
from libtad.datatypes.time import TADDateTime
from libtad.datatypes.astro import AstronomyObjectType

coordinates = Coordinates(59.743, 10.204)
place = LocationId(coordinates)
date = TADDateTime(2020, 11, 26)
service = AstrodataService("accessKey", "secretKey")


    from libtad import AstrodataService
    from libtad.datatypes.places import Coordinates, LocationId
    from libtad.datatypes.time import TADDateTime
    from libtad.datatypes.astro import AstronomyObjectType
    
    coordinates = Coordinates(59.743, 10.204)
    place = LocationId(coordinates)
    date = TADDateTime(2020, 11, 26)
    service = AstrodataService("accessKey", "secretKey")

Get Result

The result variable will now data about the sun at the exact point in time that was requested.

result = service.get_astrodata(AstronomyObjectType.Sun, place, date)


    result = service.get_astrodata(AstronomyObjectType.Sun, place, date)

Where to go next?

See our GitHub repository for more information on the Python Library.

gem 'libtad'


    gem 'libtad'

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')
place = "norway/stavanger"
start_date = TADDateTime.new(year: 2021, month: 1, day: 1)
end_date = TADDateTime.new(year: 2021, month: 1, day: 3)


    client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')
    place = "norway/stavanger"
    interval = TADDateTime.new(year: 2021, month: 1, day: 1, hour: 14, minute: 14, second: 34)

Get Result

The result variable will now data about the sun at the exact point in time that was requested.

result = client.get_astro_position(object: :sun, place_id: place, interval: interval);


    result = client.get_astro_position(object: :sun, place_id: place, interval: interval);

Where to go next?

See our GitHub repository for more information on the Ruby Library.

Add libtad-rs as a dependency in Cargo.toml:

libtad-rs = "0.2"


    libtad-rs = "0.2"

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

let client = libtad_rs::ServiceClient.new("access_key".into(), "secret_key".into());
let request = AstroPositionRequest::new()
    .with_object(AstronomyObjectType::Sun)
    .with_placeid("norway/stavanger")
    .with_interval(DateTime::from("2021-01-01T14:14:34"));


    let client = libtad_rs::ServiceClient.new("access_key".into(), "secret_key".into());
    let request = AstroPositionRequest::new()
        .with_object(AstronomyObjectType::Sun)
        .with_placeid("norway/stavanger")
        .with_interval(DateTime::from("2021-01-01T14:14:34"));

Get Result

The result variable will now data about the sun at the exact point in time that was requested.

result = client.get_astro_position(&request);


    result = client.get_astro_position(&request);

Where to go next?

See our GitHub repository for more information on the Rust Library.

Install Official Libraries

$ git clone https://github.com/timeanddate/libtad-net


    $ git clone https://github.com/timeanddate/libtad-net

Build Query

The API library is now installed. Next, you specify the location and the optionally the date interval you are querying for. To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account.

Don't have a key? Sign up for our free trial and receive an access key to try it out.

var place = new LocationId("norway/stavanger");
var start_date = new DateTime(2021, 1, 1);
var end_date = new DateTime(2021, 1, 3);
var service = new TidesService('accessKey', 'secretKey');


    var place = new LocationId("norway/stavanger");
    var startDate = new DateTime(2021, 1, 1);
    var endDate = new DateTime(2021, 1, 3);
    var service = new TidesService('accessKey', 'secretKey');
    service.StartDate = startDate;
    service.EndDate = endDate;

Get Result

The result variable will now contain amplitude and time for tidal high and low points based on predictions for a tidal station. The result also contains information about the tidal station.

var result = service.GetTidalData(place);


    var result = service.GetTidalData(place);

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.

<repository>
    <id>github</id>
    <name>Time and Date API Packages</name>
    <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
</repository>
<dependency>
    <groupId>com.timeanddate</groupId>
    <artifactId>services</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

var place = new LocationId("norway/stavanger");
var startDate = new TADDateTime(2021, 1, 1);
var endDate = new TADDateTime(2021, 1, 3);
var service = new TidesService('accessKey', 'secretKey');
service.setStartDate(startDate);
service.setEndDate(endDate);


    var place = new LocationId("norway/stavanger");
    var startDate = new TADDateTime(2021, 1, 1);
    var endDate = new TADDateTime(2021, 1, 3);
    var service = new TidesService('accessKey', 'secretKey');
    service.setStartDate(startDate);
    service.setEndDate(endDate);

Get Result

The result variable will now contain amplitude and time for tidal high and low points based on predictions for a tidal station. The result also contains information about the tidal station.

var result = service.getTidalData(place);


    var result = service.getTidalData(place);

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.

gem 'libtad'


    gem 'libtad'

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')
place = "norway/stavanger"
start_date = TADDateTime.new(year: 2021, month: 1, day: 1)
end_date = TADDateTime.new(year: 2021, month: 1, day: 3)


    client = LibTAD::Client.new(access_key: 'access_key', secret_key: 'secret_key')
    place = "norway/stavanger"
    start_date = TADDateTime.new(year: 2021, month: 1, day: 1)
    end_date = TADDateTime.new(year: 2021, month: 1, day: 3)

Get Result

The result variable will now contain amplitude and time for tidal high and low points based on predictions for a tidal station. The result also contains information about the tidal station.

result = client.get_tidal_data(placeid: place, start_date: start_date, end_date: end_date);


    result = client.get_tidal_data(placeid: place, start_date: start_date, end_date: end_date);

Where to go next?

See our GitHub repository for more information on the Ruby Library.

Add libtad-rs as a dependency in Cargo.toml:

libtad-rs = "0.2"


    libtad-rs = "0.2"

Build Query

Don't have a key? Sign up for our free trial and receive an access key to try it out.

let client = libtad_rs::ServiceClient.new("access_key".into(), "secret_key".into());
let request = TidesRequest::new()
    .with_placeid("norway/stavanger")
    .set_startdt(DateTime::from("2021-01-01"))
    .set_enddt(DateTime::from("2021-01-03"));


    let client = libtad_rs::ServiceClient.new("access_key".into(), "secret_key".into());
    let request = TidesRequest::new()
        .with_placeid("norway/stavanger")
        .set_startdt(DateTime::from("2021-01-01"))
        .set_enddt(DateTime::from("2021-01-03"));

Get Result

The result variable will now contain amplitude and time for tidal high and low points based on predictions for a tidal station. The result also contains information about the tidal station.

result = client.get_tidal_data(&request);


    result = client.get_tidal_data(&request);

Where to go next?

See our GitHub repository for more information on the Rust Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.

$ ACCESSKEY="<Your Access Key>"
$ SECRETKEY="<Your Secret Key>"
$ curl -G \
        --data-urlencode "version=3" \
        --data-urlencode "prettyprint=1" \
        --data-urlencode "accesskey=$ACCESSKEY" \
        --data-urlencode "secretkey=$SECRETKEY" \
        --data-urlencode "placeid=norway/oslo" \
        --data-urlencode "startdt=2021-01-01" \
        --data-urlencode "enddt=2021-01-03" \
        https://api.xmltime.com/tides


    $ ACCESSKEY="<Your Access Key>"
    $ SECRETKEY="<Your Secret Key>"
    $ curl -G \
        --data-urlencode "version=3" \
        --data-urlencode "prettyprint=1" \
        --data-urlencode "accesskey=$ACCESSKEY" \
        --data-urlencode "secretkey=$SECRETKEY" \
        --data-urlencode "placeid=norway/stavanger" \
        --data-urlencode "startdt=2021-01-01" \
        --data-urlencode "enddt=2021-01-01T23:59:59" \
        https://api.xmltime.com/tides

Get Result

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.

{
	"version": 3,
	"billing": {
		"credits": 1
	},
	"stations": [{
		"source": {
			"name": "Stavanger",
			"latitude": 58.974339,
			"longitude": 5.730121,
			"type": "Reference Station",
			"distance": 0.740816
		},
		"matchparam": "norway/stavanger",
		"result": [{
			"time": {
				"iso": "2021-01-01T04:32:17",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 4,
					"minute": 32,
					"second": 17
				}
			},
			"amplitude": 0.494444,
			"phase": "low"
		},{
			"time": {
				"iso": "2021-01-01T10:55:47",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 10,
					"minute": 55,
					"second": 47
				}
			},
			"amplitude": 1.005585,
			"phase": "high"
		},{
			"time": {
				"iso": "2021-01-01T17:01:25",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 17,
					"minute": 1,
					"second": 25
				}
			},
			"amplitude": 0.478707,
			"phase": "low"
		},{
			"time": {
				"iso": "2021-01-01T23:21:00",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 23,
					"minute": 21,
					"second": 0
				}
			},
			"amplitude": 0.971725,
			"phase": "high"
		}]
	}]
}


    {
	"version": 3,
	"billing": {
		"credits": 1
	},
	"stations": [{
		"source": {
			"name": "Stavanger",
			"latitude": 58.974339,
			"longitude": 5.730121,
			"type": "Reference Station",
			"distance": 0.740816
		},
		"matchparam": "norway/stavanger",
		"result": [{
			"time": {
				"iso": "2021-01-01T04:32:17",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 4,
					"minute": 32,
					"second": 17
				}
			},
			"amplitude": 0.494444,
			"phase": "low"
		},{
			"time": {
				"iso": "2021-01-01T10:55:47",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 10,
					"minute": 55,
					"second": 47
				}
			},
			"amplitude": 1.005585,
			"phase": "high"
		},{
			"time": {
				"iso": "2021-01-01T17:01:25",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 17,
					"minute": 1,
					"second": 25
				}
			},
			"amplitude": 0.478707,
			"phase": "low"
		},{
			"time": {
				"iso": "2021-01-01T23:21:00",
				"datetime": {
					"year": 2021,
					"month": 1,
					"day": 1,
					"hour": 23,
					"minute": 21,
					"second": 0
				}
			},
			"amplitude": 0.971725,
			"phase": "high"
		}]
	}]
}