Application Programming Interface
Astronomical Applications Dept. Astronomical Applications Dept.
 
Skip navigation

Astronomical Applications API v2.0

All Astronomical Applications Department Web-based services have a standard form which collects user input. Some of these services work within an application programming interface (or API) allowing users to query the calculators and receive results, which can be embedded within a Web page or mobile application.

This Web page describes how to use a URL to query the Astronomical Applications Department's API for data and images from our Web services. Detailed information about how to create URL requests for the services that are currently accessible through the API is found below.

The API is being modified over time as more services are added. Please see the changelog for modifications that have been made in new versions.

Each Web application supporting this API format is discussed separately with both instructions and examples. Template URLs and example URLs are indicated via text over a gray background. Certain components of the URLs presented will be in bold and colored red; these items are parameter variables to be set by the user (in the case of a URL template) and the parameters themselves (when example URLs are presented). To find instructions for a specific parameter or an example for a particular service, consult the table of contents below.



Application Parameter Formats

The Astronomical Applications Department's Web services use a variety of parameters to specify the output requested. Many parameters are used in multiple services, such as "date" and "time," which are found in nearly all of our services.

Please note: URL examples below may wrap over multiple lines due to screen width. Do not enter line breaks into URLs.

In general, an API request takes the form:

http://api.usno.navy.mil/<web_service>?<parameters>

where <web_service> is the particular web service being queried, and <parameters> is a list of parameters separated by the "&" character. Each parameter is presented as a "parameter-name"/"value" pair in the form:.

"parameter_name"="value"

To reduce confusion, the format of a single parameter is the same in every service that uses it. The formats for such "common parameters" will be discussed in the next section. Parameters that are unique to a single service will have their formats presented in the section devoted to that particular service.


"ID" Format

If you plan to write your own form or script to access the APIs, we encourage you to use the ID parameter in your API call. Using this parameter is optional. However, the use of user IDs allows us to keep track of how many unique users we have, and helps us justify our work on the web.

The ID you choose can be up to 8 characters. Please limit the ID to alphanumeric characters. The ID "AA" is used internally; therefore we recommend against using that for your ID. If you are setting up an ID for an institution, please e-mail us (aa-help@usno.navy.mil) and let us know what identifier you are using and who you are. Again, this helps us justify our work on the web.

Examples of correctly formatted date parameters are:



Back to the top

"Date" Format

Our web services are designed to accept a single date parameter. The month, day, and year are combined into one "date" component, which will be represented in all examples found on this page by DATE. The standard form of DATE is MM/DD/YYYY (the month, day, and year, respectively) for a specific day. Certain keywords are also accepted to request days relative to the current day. The keywords and how you enter them are:

date=today current day, according to Universal Time (UT)
date=yesterday day before current day, according to Universal Time (UT)
date=tomorrow day after current day, according to Universal Time (UT)

If one of the above listed keywords is not entered, then a properly formated date is expected. There are a few rules for how dates must be entered.

Examples of correctly formatted date parameters are:



Back to the top

"Year" Format

Some of our web services require only the input of a year.

Examples of correctly formatted year parameters are:



Back to the top

"Time" Format

Our web services combine the hour, minute, seconds, day period (i.e. "AM" or "PM"), and time zone into a single "time" component, which will be represented by TIME on this page. The TIME parameter can accept the following keywords that identify specific times:

time=now current time
time=midnight 00:00
time=noon 12:00

If one of the above keywords is not entered, a properly formatted time is expected. The rules for entering a valid time are

As implied by the above list of rules, the time interpreter is flexible. While not an exhaustive list of the time interpreter's capabilities, some examples of valid time strings are:

If you are attempting to obtain an image at a specific local time and are unsure of how to convert your desired local time to UT, you can visit our Time Zones and Daylight Savings Time pages.



Back to the top

"Time Zone" Format

While a time zone can be optionally encoded in the time parameter, some services require a time zone without a specific time of day. In those cases, the time zone parameter will be used; on this page the time zone parameter will be represented by TZ.

The rules for entering a valid, independent time zone are

Examples:



Back to the top

"Body" Format

Some web services allow the user to select a solar system object to be targeted, observed, or measured. In all services that make use of such a parameter, it will be referred to as BODY.

The current list of supported objects is:



Back to the top

Locations

For the services which require a location to be defined, two different input methods are available.

"Loc" Format

One way to specify a location is to provide a city and state. The city and state components are combined into a single parameter, which will be represented by LOC on this page. Once entered, the city and state are used to obtain the corresponding coordinates and time zone. (For locations outside of the U.S., use the COORDS parameter.)

The rules for entering valid US locations are

Some examples of valid location parameter are




"Coords" Format

The other way to specify a location is to provide a latitude and longitude (you also must provide a time zone). If the desired location is either outside the U.S. or a U.S. location missing from our database, this method must be used. The latitude and longitude components are combined into a single component, which will be represented by COORDS on this page.

The rules for entering valid coordinates are

Some examples of valid coordinate strings are



Back to the top

Time Interval Format

For the services which require time intervals, three inputs are required:

Interval units may be entered either as a word (day, hour, minute, second), or an integer (1, 2, 3, or 4, respectively). The computation in all data services is limited to no more than 9999 iterations, and if the combination of iterations and interval goes beyond the allowed date range, the output will be cut off at the extent of the allowable date range.

Some examples of valid interval strings are



Back to the top

Height Format

Some data services accept an input of height. Input is expected to be an integer in units of meters, and may range between -90 to 10999.

Some examples of valid height strings are



Back to the top

Format Format

Data services with a location accept an input of format, which indicates the format of data the user would like returned. At this time, 'json' is the only format available.

The example of a valid format string is



Back to the top



Web Service API Examples

Day and Night Across the Earth - Cylindrical Projection

This program generates a cylindrical map of the Earth (similar to a Mercator projection) with daytime and nighttime areas appropriately shaded. The image can be generated for any date in a year between 1700 and 2100 (inclusive). A complete description (and form) may be found here.

The template URL for querying such an image is

http://api.usno.navy.mil/imagery/earth.png?date=DATE&time=TIME

The date and time parameters are described in the above sections. Two examples of querying this service are

Example 1: generating cylindrical day/night map of Earth for tomorrow at 10:13 UT

http://api.usno.navy.mil/imagery/earth.png?date=tomorrow&time=10:13

Example 2: requesting cylindrical day/night map of Earth for June 17, 2012 at 0:00 UT

http://api.usno.navy.mil/imagery/earth.png?date=6/17/2012

In example 2, we have left the time parameter out of the URL to demonstrate that the server will default to a time of 0:00 UT.



Back to the top

Day and Night Across the Earth - Spherical Projections

This application creates a 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. The image can be generated for any date in a year between 1700 and 2100 (inclusive). A complete description (and form) may be found here.

The template URL for querying such an image is

http://api.usno.navy.mil/imagery/earth.png?view=VIEW&date=DATE&time=TIME

The date and time parameters are described in the above sections. The parameter VIEW specifies the view desired by the user. The following views are currently supported:

view=moon Viewing Earth as if you were between Earth and the Moon
view=sun Viewing Earth as if you were between Earth and the Sun
view=north Viewing Earth from a vantage point over the North Pole
view=south Viewing Earth from a point over the South Pole
view=east Viewing Earth's eastern hemisphere
view=west Viewing Earth's western hemisphere
view=rise Viewing Earth from above the terminator at sunrise
view=set Viewing Earth from above the terminator at sunset

Two examples querying this service are

Example 1: querying server for a simulated view of the Earth as if positioned over the north pole on April 9, 2012 at 20:18 UT:

http://api.usno.navy.mil/imagery/earth.png?view=north&date=4/9/2012&time=20:18

Example 2: requesting a view of the Earth from the perspective of the moon for today at 22:00 UT:

http://api.usno.navy.mil/imagery/earth.png?view=moon&time=22:00

In example 2, we have taken advantage of the fact that, if the date parameter is omitted from the URL, the server will default to the current date.



Back to the top

Apparent Disk of a Solar System Object

This program produces an apparent disk of a solar system object oriented as if you were viewing it through a high-powered telescope. The image can be generated for any date in a year between 1700 and 2100 (inclusive). More information about this application may be found here.

The template URL for querying such an image is

http://api.usno.navy.mil/imagery/BODY.png?date=DATE&time=TIME

The date, time, and body parameters are described in the sections above.

Example: query server for the apparent disk of the Moon on May 28, 1900 at 5:13 UT.

http://api.usno.navy.mil/imagery/moon.png?date=5/28/1900&time=5:13

Example: query server for the apparent disk of Jupiter on December 21, 2012 at 11:12 UT.

http://api.usno.navy.mil/imagery/jupiter.png?date=12/21/2012&time=11:12


Back to the top

Phases of the Moon

This program computes the dates and times of a list of primary moon phases. The user may specify either the starting date for the list and the number of phases calculated, or a calendar year for all phases during that year. The data can be generated for any year between 1700 and 2100 (inclusive). The program returns the data in JavaScript Object Notation format (or JSON), which can be decoded and reformatted.

The template URL for querying this service is

For date and number of phases:

http://api.usno.navy.mil/moon/phase?date=DATE&nump=NUMP

For calendar year:

http://api.usno.navy.mil/moon/phase?year=YEAR

The date parameter is described above. The parameter NUMP specifies the number of primary phases that the user wants, starting from the specified date. It is limited to a number between 1 and 99.

Example: query server for 48 primary phases (12 lunar phase cycles) starting from May 3, 2009.

http://api.usno.navy.mil/moon/phase?date=5/3/2009&nump=48

Example: query server for 4 primary phases (1 lunar phase cycle) starting from September 18, 1950.

http://api.usno.navy.mil/moon/phase?date=9/18/1950&nump=4

Optionally, time zone and daylight saving time information may be included. The time zone parameter is described above. The daylight saving time parameter DST is a boolean flag which specifies whether or not you would like to include U.S. daylight saving time in the calculations. Daylight saving time can be accounted for only for years 1967 and later, in accordance with the Uniform Time Act of 1966 and subsequent legislation.

Example: query server for all primary phases in 1984, with times listed in Eastern Time and accounting for daylight saving time.

http://api.usno.navy.mil/moon/phase?year=1984&tz=-4&dst=true

Example: query server for 12 primary phases (3 lunar phase cycles) starting from June 1, 2015, with a time zone of 7 hours East of Greenwich and not accounting for daylight saving time.

http://api.usno.navy.mil/moon/phase?date=6/1/2015&nump=12&tz=7&dst=false

JSON Notes:



Back to the top

Complete Sun and Moon Data for One Day

This program produces rise, set, and transit times for the Sun and the Moon on the requested date at the specified location. The data can be generated for any date in a year between 1700 and 2100 (inclusive). For the Sun, it also computes the times at which civil twilight begins and ends. For the Moon, it also computes the current phase and fraction of the Moon illuminated at noon in the local time zone on the date requested, along with the closest primary phase. In addition, it returns symbols indicating that a particular body is continuously above or below the horizon and symbols indicating that the Sun is continously above or below the twilight limit. The program returns the data as JSON, which can be decoded and reformatted.

This service requires a location. Since locations can be input two ways, two templates for querying this service are available depending on what location information the user is providing.

The URL template for a U.S. location in our database

http://api.usno.navy.mil/rstt/oneday?date=DATE&loc=LOC

The URL template for an location identified by coordinates, such as an international place

http://api.usno.navy.mil/rstt/oneday?date=DATE&coords=COORDS&tz=TZ

The date, loc, coords, and tz parameters are described above.

Example: query server for complete Sun and Moon data for January 5, 2005 in Los Angeles, California.

http://api.usno.navy.mil/rstt/oneday?date=1/5/2005&loc=Los Angeles, CA

Example: query server for complete Sun and Moon data for the location 41.89° N, 12.48° E on December 1, 2016 (1 hour east of Greenwich).

http://api.usno.navy.mil/rstt/oneday?date=12/1/2016&coords=41.89N,12.48E&tz=1

JSON Notes:


The computed phenomena are identified by the following abbreviations or symbols:



Back to the top

Sidereal Time

This data service provides the Greenwich mean and apparent sidereal time, local mean and apparent sidereal time, and the Equation of the Equinoxes for date(s) and time(s) specified in UT1.

Data will be provided for a three year period from 1 January of the year preceeding the current year through 31 December of the year following the current year. For dates outside of this range, see MICA.

This service requires a location, a date and a time (in UT1). Time interval information is optional, if none is provided, then a single iteration will be returned. Since locations can be input two ways, two templates for querying this service are available depending on what location information the user is providing.

The URL template for a U.S. location in our database

http://api.usno.navy.mil/sidtime?date=DATE&time=TIME&loc=LOC &reps=REPS&intv_mag=INTV_MAG&intv_unit=INTV_UNIT

The URL template for an location identified by coordinates, such as an international place

http://api.usno.navy.mil/sidtime?date=DATE&time=TIME&coords=COORDS &reps=REPS&intv_mag=INTV_MAG&intv_unit=INTV_UNIT

The date, time, loc, coords, and reps, intv_mag and intv_unit parameters are described above.

Example: query server for sidereal times in Toledo, Iowa daily at noon (UT1) for 30 days, starting on October 14, 2014.

http://api.usno.navy.mil/sidtime?date=10/14/2014&loc=Toledo, IA&reps=30&intv_mag=1&intv_unit=day&time=noon

Example: query server for sidereal time data for the location 41.89° N, 12.48° E on December 1, 2016 for 90 iterations, once every 5 minutes, starting at 9 pm (UT1).

http://api.usno.navy.mil/sidtime?date=today&coords=41.89N, 12.48E&reps=90&intv_mag=5&intv_unit=minutes&time=9:00:00 PM

GeoJSON Notes:



Back to the top

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.

For the local circumstances, data will be provided for the previous year through 2024. For dates outside of this range, see MICA.

This service requires a location and date, and may include height. Since locations can be input two ways, two templates for querying this service are available depending on what location information the user is providing.

For a list of eclipses in a selected year, data will be provided for 1800 through 2050.

The only information required to obtain the list of eclipses is a year. An example template is given below.

The URL template for a U.S. location in our database

http://api.usno.navy.mil/eclipses/solar?date=DATE&loc=LOC&height=HEIGHT&format=FORMAT

The URL template for a location identified by coordinates, such as an international place

http://api.usno.navy.mil/eclipses/solar?date=DATE&coords=COORDS&height=HEIGHT&format=FORMAT

The URL template for a list of eclipses in a given year

http://api.usno.navy.mil/eclipses/solar?year=YEAR

The date, loc, coords, height, and format parameters are described above.

Example: query server for solar eclipse local circumstances in Metropolis, Illinois during the eclipse of August 21, 2017.

http://api.usno.navy.mil/eclipses/solar?date=8/21/2017&loc=Metropolis, IL&height=117&format=json

Example: query server for solar eclipse local circumstances for the location 46.67° N, 1.48° E on March 20, 2015, which is at a height of 176 meters.

http://api.usno.navy.mil/eclipses/solar?date=3/20/2015&coords=46.67N, 1.48E&height=176&format=json

Example: query server for list of solar eclipses in the year 2024.

http://api.usno.navy.mil/eclipses/solar?year=2024

JSON Notes:

In the case of requesting local eclipse circumstances for a particular eclipse:

In the case of requesting a list of eclipses for a year:



Back to the top

Selected Christian Observances

This data service provides the dates of Ash Wednesday, Palm Sunday, Good Friday, Easter, Ascension Day, Whit Sunday, Trinity Sunday, and the First Sunday of Advent in a given year. Data will be provided for the years 1583 through 9999.

The only information required to obtain selected Christian observances is a year. An example template is given below.

The URL template

http://api.usno.navy.mil/christian?year=YEAR

The year parameter is described above.

Example: query server for selected Christian observances in the year 2016.

http://api.usno.navy.mil/christian?year=2016

JSON Notes:



Back to the top

Selected Jewish Observances

This data service provides the dates for the first day of Passover, Shavuot, Yom Kippur, Rosh Hashanah, the first day of Hanukkah, and the first day of Sukkot in a given year. Data will be provided for the years 360 C.E. (A.M. 4120) through 9999 C.E. (A.M. 13761).

The only information required to obtain selected Jewish observances is a year. An example template is given below.

The URL template

http://api.usno.navy.mil/jewish?year=YEAR

The year parameter is described above.

Example: query server for selected Jewish observances in the year 2018.

http://api.usno.navy.mil/jewish?year=2018

JSON Notes:



Back to the top

Selected Islamic Observances

This data service provides the dates for Islamic New Year, the first day of Ramadân, and the first day of Shawwál in a given year. Data will be provided for the years 622 C.E. (A.H. 1) through 9999 C.E. (A.H. 9666). No observances will be provided prior to A.H. 1 in 622 C.E..

The only information required to obtain the selected Islamic observances is a year. An example template is given below.

The URL template

http://api.usno.navy.mil/islamic?year=YEAR

The year parameter is described above.

Example: query server for selected Islamic observances in the year 2020.

http://api.usno.navy.mil/islamic?year=2020

JSON Notes:



Back to the top

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 get the Julian date corresponding to a given Gregorian or Julian calendar date, a date and time (in UT1) are needed, with optional era parameter:

The URL template

http://api.usno.navy.mil/jdconverter?date=DATE&time=TIME&era=ERA

The date and time parameters are described above. The parameter era specifies the era of the year requested; it accepts values of "AD", "CE", "BC" or "BCE". If no era parameter is provided, the era is assumed to be A.D.

Be aware that the year "A.D. 0" or "0 B.C." (or "C.E." or "B.C.E.") does not exist. If a date with a year 0 is entered without an era parameter, it will convert it to 1 B.C.

Example: query server for the Julian date corresponding to August 3, 2013 (A.D.) at 10:15:23.5 pm UT1.

http://api.usno.navy.mil/jdconverter?date=8/3/2013&time=22:15:23.5

Example: query server for the Julian date corresponding to March 26, 4 B.C. at 2:03 am UT1.

http://api.usno.navy.mil/jdconverter?date=3/26/4&time=2:03&era=BC

To get the Gregorian or Julian calendar date corresponding to a given Julian date, only the Julian date is a required parameter:

The URL template

http://api.usno.navy.mil/jdconverter?jd=JD

The parameter jd specifies the Julian date requested. It is limited to a number between 0 and 5373484.5.

Example: query server for the Gregorian date and the time corresponding to Julian date 2453124.1526

http://api.usno.navy.mil/jdconverter?jd=2453124.1526

JSON Notes:



Back to the top