Raku Land

API::USNavalObservatory

github:cbk

perl6-API-USNavalObservatory Build Status

SYNOPSIS

This module is a simple Perl 6 interface to the U.S. Naval Observatory, Astronomical Applications API v2.2.0 which can be found at http://aa.usno.navy.mil/data/docs/api.php

You may choose to use an 8 character alphanumeric identifier in your forms or scripts. This API has a default of "P6mod" which is registered with the U.S. Naval Observatory as the default ID of this API. The 'AA' ID is used internally by the U.S. Naval Observatory and thus can not be used. It is recommended that you override the default apiID You may use any other identifier you want for apiID. Information about the ID and how to register your own can be found here.

Example:

the following example creates a new API::NavalObservatory object called $webAgent and sets the apiID to 'MyID'.

my $webAgent = API::USNavalObservatory.new( apiID => "MyID" );

Returns

Methods

There are currently 9 methods which are used to interact with this API.

The API uses UTC time for all time based calls. When crafting your method calls add the .utc method on the DateTime object to convert a local time to UTC.

Below is a list of the current methods in this module:

Day and Night Across the Earth - Cylindrical Projection

Generates a cylindrical map of the Earth (similar to a Mercator projection) with daytime and nighttime areas appropriately shaded.

Examples:

The following example shows a request using a date only.

say $webAgent.cylindrical( :dateObj( Date.today  ) );

This example shows a request that uses both date and time.

say $webAgent.cylindrical( :dateTimeObj( DateTime.now ) );

Return:

This method returns a .png image in the current working directory.

Day and Night Across the Earth - Spherical Projections

Creates a .png image view of the Earth with daytime and nighttime areas shaded appropriately. The image generated is of the apparent disk you would see if you were in a spacecraft looking back at Earth. This method takes two named pramaters: dateTimeObj which is a DateTime object and view which is a View subset.

Example:

 say $webAgent.spherical(
    :dateTimeObj( DateTime.now ),
	:view("sun")
);

Return:

This method returns a .png image in the current working directory.

Apparent Disk of a Solar System Object

Produces an apparent disk of a solar system object oriented as if you were viewing it through a high-powered telescope.

Example:

 say $webAgent.apparentDisk(
	:dateTimeObj( DateTime.now ),
	:body('moon')
);

Return:

This method returns a png image in the current working directory.

Phases of the Moon

Returns the dates and times of a list of primary moon phases.
This method has two signatures:

Examples:

The following example shows a request for a given date and number of phases.

say $webAgent.moonPhase(
	:dateObj( Date.today() ),
	:numP( 5 )
);

The following example shows a request for a given year.

 say $webAgent.moonPhase( 2019 );

Return:

This method returns a JSON formatted text blob.

Complete Sun and Moon Data for One Day

Returns the rise, set, and transit times for the Sun and the Moon on the requested date at the specified location.

Examples:

The following example shows a request using date, coordinates, and time zone.

say $webAgent.oneDayData(
	:dateObj( Date.today() ),
	:coords( "41.98N, 12.48E" ),
	:tz(-6)
);

The following example shows a request using date amd location.

say $webAgent.oneDayData(
	:dateObj( Date.today()),
	:loc("San Diego, CA")
);

Return:

This method returns a JSON formatted text blob.

Sidereal Time

Provides the greenwich mean and apparent sidereal time, local mean and apparent sidereal time, and the Equation of the Equinoxes for a given date & time.

Examples:

The following example shows a request using a location string.

say $webAgent.siderealTime(
    :dateTimeObj(DateTime.new(
        year => 2019,
        month => 2,
        day => 2,
        hour => 2,
        minute => 2,
        second => 1,)),
    :loc("Denver,CO"),
    :reps(90),
    :intvMag(5),
    :intvUnit('minutes')
);

The following example shows a request using coordinates.

say $webAgent.siderealTime(
    :dateTimeObj( DateTime.new(
        year => 2019,
        month => 2,
        day => 2,
        hour => 2,
        minute => 2,
        second => 1,)),
    :coords("41.98N, 12.48E"),
    :reps(90),
    :intvMag(5),
    :intvUnit('minutes')
);

Return:

This method returns a JSON formatted text blob.

Solar Eclipse Calculator

This data service provides local circumstances for solar eclipses, and also provides a means for determining dates and types of eclipses in a given year.

Examples:

The following example shows a request using a U.S. based location (San Francisco CA) for the current day.

say $webAgent.solarEclipses(
	:loc("San Francisco CA"),
	:dateObj( Date.today() ),
	:height(50),
	:format("json") 
    );

The following example shows a request using lat and long.

say $webAgent.solarEclipses(
	:coords("46.67N, 1.48E" ),
	:dateObj( Date.today() ),
	:height(50),
	:format("json") 
	);

The following example shows a request providing only the year in the range of 1800 to 2050.

say $webAgent.solarEclipses( 2019 );

Return:

All these method signatures return an JSON formatted text blob.

Selected Religious Observances

Single method to handle all three calender types; christan, jewish, islamic

Example:

say $webAgent.observances( :year(2019), :cal('christian') );

Return:

This method returns a JSON formatted text blob.

Julian Date Converter

This data service converts dates between the Julian/Gregorian calendar and Julian date. Data will be provided for the years 4713 B.C. through A.D. 9999, or Julian dates of 0 through 5373484.5.

To use the .julianDate method, you must provide a valid DateTime object and a valid Era OR an unsigned integer.

This method returns a JSON text blob of the request converted into ether a Julian or calendar date.

Examples:

say $webAgent.julianDate( 2457892.312674 );
say $webAgent.julianDate( :dateTimeObj(DateTime.now), :era('AD') );

Return:

Both of these methods returns an JSON formatted text blob.

Earth's Seasons and Apsides

Example:

say $webAgent.seasons( :year(2019), :tz(-6), :dst(False) );

Return:

This method returns a JSON formatted text blob.

Sample code

use v6;
use API::USNavalObservatory;
my $webAgent = API::NavalObservatory.new( apiID => "MyID" );
my $output = $webAgent.solarEclipses( 2019 );
say $output;

OUTPUT:

{
  "error" : false,
  "year" : 2019,
  "apiversion" : "2.2.0",
  "eclipses_in_year" : [
    {
      "event" : "Partial Solar Eclipse of 6 January 2019",
      "day" : 6,
      "year" : 2019,
      "month" : 1
    },
    {
      "event" : "Total Solar Eclipse of 2 July 2019",
      "month" : 7,
      "year" : 2019,
      "day" : 2
    },
    {
      "event" : "Annular Solar Eclipse of 26 December 2019",
      "month" : 12,
      "year" : 2019,
      "day" : 26
    }
  ]
}

AUTHOR