Astronomical Applications API v4.0.1

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

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

The API is occasionally updated as more services are added. Please see the changelog for a list of modifications.

Each data service supporting this API format is discussed separately with both instructions and examples. Template URLs and example URLs are indicated using text over a gray background. Parameter variables to be set by the user in the URL templates, and the parameters themselves in the example URLs are indicated using bold text colored red. For instructions on a specific parameter, or an example of a particular service, consult the table of contents below.

• API Parameter Formats
• ID
• Date
• Year
• Time
• Time Zone
• Daylight Saving Time
• Body
• Location
• Time Interval
• Height
• Application-Specific Instructions
• Phases of the Moon
• Complete Sun and Moon Data for One Day
• Sidereal Time
• Solar Eclipse Computer
• Selected Christian Observances
• Selected Jewish Observances
• Selected Islamic Observances
• Julian Date Converter
• Earth's Seasons and Apsides
• Daylight Saving Time
• Celestial Navigation Data for Assumed Position and Time

Application Parameter Formats

The Astronomical Applications Department's data 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:

where <data_service> is the particular data 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:

The format of any single parameter is the same in every service that uses it. Those used in multiple services are 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.

Back to the top

"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 (usno-ops-center@us.navy.mil) and let us know what identifier you are using and who you are.

Examples of correctly formatted ID parameters are:

• ID=MC123
• ID=JohnDoe

Back to the top

"Date" Format

Our data services combine month, day, and year into a single "date" component, which will be represented by DATE on this page. The standard form of DATE is YYYY-MM-DD (year, month, and day respectively) for a specific day. The rules for entering a valid date are:

• a dash ("-") must be used to separate the month, day, and year
• month and day components do not require leading zeroes
• the year component must be in the range specified by the data service documentation

Examples of correctly formatted date parameters are:

• date=1700-9-5
• date=1801-09-25
• date=1937-9-05
• date=2049-09-05

Back to the top

"Year" Format

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

Examples of correctly formatted year parameters are:

• year=1937
• year=5

Back to the top

"Time" Format

Our data services combine the hour, minute, and seconds into a single "time" component, which will be represented by TIME on this page. The standard form of TIME is hh:mm:ss (hour, minute, and second, respectively). The rules for entering a valid time are:

• times must be entered in "24-hour time"
• a colon (":") must be used to separate the hour, minute, and seconds
• only the hour and minutes component is required for the input to be a valid time string; the seconds component will default to zero
• the hour and minute components must be two digits each; a single digit hour/minute therefore requires a leading zero (see examples below)
• the seconds component may be an integer or floating point number
• if the seconds component is an integer, it must be two digits
• if the seconds component is a floating point number, it must have two digits to the left of the decimal point and may have up to six digits to the right of the decimal point

Examples of correctly formatted time parameters are:

• time=17:13:05.512
• time=05:13:05
• time=05:13

Back to the top

"Time Zone" Format

Some of our data services require a time zone parameter. On this page the time zone parameter will be represented by TZ. The rules for entering a valid time zone are:

• time zones may be integer or a floating point numbers
• time zone is defined to be "east-positive", i.e., TZ = local time - UT1 (TZ is positive for east longitudes and negative for west longitudes)
• the allowed range is -12 (west) ≤ TZ ≤ +14 (east)

Examples of correctly formatted time zone parameters are:

• tz=0
• tz=-5.5
• tz=-12
• tz=14

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 UT1 Time, you can visit our Time Zones and Daylight Saving Time pages.

Back to the top

"DST" Format

Some of our data services have the option of including daylight saving time. The daylight saving time parameter DST is a boolean flag which specifies whether or not to include U.S. daylight saving time in the calculations. Daylight saving time can be accounted for only in the years 1967 and later, in accordance with the Uniform Time Act of 1966 and subsequent legislation. If no DST flag is provided, false is assumed.

Correctly formatted dst parameters are:

• dst=true
• dst=false

Back to the top

"Body" Format

Some data services allow the user to select a solar system object to be targeted, observed, or measured. On this page, the body parameter will be represented by BODY.

The current list of supported objects is:

• body=mercury
• body=venus
• body=venus-radar
• body=mars
• body=jupiter
• body=moon
• body=io
• body=europa
• body=ganymede
• body=callisto

Back to the top

"Coords" Format

Our data services combine latitude and longitude into a single location component which will be represented by COORDS on this page. The rules for entering valid coordinates are:

• latitude followed by longitude in one string separated by a comma
• coordinates are in decimal degrees
• coordinates are defined as "east-positive" and "north-positive"
• no sign is needed for positive values

Some examples of valid coordinate strings are:

• coords=38.89, -77.03
• coords=-38.89, 77.03

Back to the top

"Time Interval" Format

Some data services require a time interval during which to perform calculations. Specifying the time interval requires the following three components:

• reps — the number of iterations
• intv_mag — the magnitude of the time interval between iterations (i.e. if an interval of 5 minutes is desired, set as "5")
• intv_unit — the units of the time interval between iterations (days, hours, minutes, seconds)

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. 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:

• &reps=5&intv_mag=5&intv_unit=day
• &reps=500&intv_mag=1&intv_unit=4

Back to the top

"Height" Format

Some data services accept a height input in units of meters. On this page, the height parameter will be represented by HEIGHT. Height is measured relative to the ellipsoid, so a negative value indicates below the ellipsoid. The rules for entering a valid height are:

• height must be an integer
• the allowed range is between -90 and 10999

Examples of correctly formatted height parameters are:

• height=1234
• height=-12

Back to the top

---

Web Service API Examples

Phases of the Moon

This data service generates a list of primary moon phases with their dates and times. The user may specify either the starting date for the list and the number of phases to calculate, or a calendar year for all phases during that year. The data can be produced for any year between 1700 and 2100 inclusive. The service returns the data in JavaScript Object Notation (JSON) format, which can be decoded and reformatted. More information about this data service may be found here.

The URL templates for querying this service are:

For date and number of phases:

For calendar year:

The date and year parameters are described in the sections 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: generate a list of 48 primary phases (12 lunar phase cycles) starting from 3 May 2009.

Example: generate a list of all primary phases in 1984.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "year" — the starting year input
• "month" — the starting month input
• "day" — the starting day input
• "numphases" — the number of phases requested
• A list of the phases in follows the header information in "phasedata." Each entry in "phasedata" contains three pieces of data
1. "phase" — name of the phase
2. "year" — year of the phase
3. "month" — month of the phase
4. "day" — day of the phase
5. "time" — time of the phase (in Universal Time)

Back to the top

Complete Sun and Moon Data for One Day

This data service 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 a note indicating that a particular body is continuously above or below the horizon, as well as a note indicating that the Sun is continuously above or below the twilight limit. The program returns the data as GeoJSON, which can be decoded and reformatted. More information about this data service may be found here.

The URL template for querying this service is:

The date and coords parameters are described in the sections above.

Example: generate complete Sun and Moon data for the location 41.89° N, 12.48° E on 1 December 2016 (in UT1).

Optionally, time zone and daylight saving time information may be included. Both parameters are described in the sections above.

Example: generate complete Sun and Moon data for Seattle, WA (47.60° N, 122.33° W) on 20 September 2005 (8 hours west of Greenwich during standard time) and include daylight saving time.

GeoJSON Notes:

• The first items in the GeoJSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• A list of information about the location will be given in "geometry"
• "coordinates" — gives an array of the coordinates ([longitude,latitude])
• "type" — the type of geometry object
• "height" — the height requested (zero if not provided)
• A list of body information will be given in "properties"
• A list of sun and moon specific information will be given in "data"
• "closestphase," which contains information on the nearest primary phase to the date requested:
  1. "day" — the day of the primary phase
  2. "month" — the month of the primary phase
  3. "phase" — phase of the moon at the nearest primary phase to the date requested
  4. "time" — the time of the primary phase
  5. "year" — the year of the primary phase
• "curphase," which is the phase of the Moon on the date requested
• "day" — the day requested
• "day_of_week — the day of week requested
• "fracillum," which is the fraction of the Moon's apparent surface which is lit
• "isdst" — whether or not the location observes daylight saving time on the date requested
• "month" — the month requested
• a list of lunar phenomena on the date requested in "moondata"
• a list of solar phenomena on the date requested in "sundata"
• Each entry in "moondata," "sundata," contains two pieces of data:
  1. "phen" — phenomenon descriptor
  2. "time" — time of the phase in local time specified in header (see list below for special cases)
• "tz" — time zone of location requested
• "year" — the year requested
• "type" — the GeoJSON object type

If the body remains above or below the horizon or twilight limit, the time will be listed as "null"

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 the years 1800 through 2050.

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. More information about this data service may be found here.

The URL template for querying this service is:

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

Example: generate sidereal time data for the location 41.89° N, 12.48° E for 90 iterations, once every 5 minutes, starting on 4 March 2020 at 9 pm (UT1).

GeoJSON Notes:

• The first items in the GeoJSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the GeoJSON data
• "truncated" — "true" if the output is to stay within bounds since the iterations would go beyond the next year
• A list of information about the location will be given in "geometry"
• "type" — the type of geometry object
• "coordinates" — gives an array of the coordinates ([longitude,latitude])
• "height" — the height requested (zero if not provided)
• A list of sidereal time specific information will be given in "properties"
• A list of dates, local times, and sidereal times will be given in "data"
• "day" — the day requested, in UT1
• "month" — the month requested
• "year" — the year requested
• "ut1time" — time in UT1
• "gmst" — Greenwich mean sidereal time
• "gast" — Greenwich apparent sidereal time
• "lmst" — local mean sidereal time
• "last" — local apparent sidereal time
• "eqofeq" — equation of the equinoxes (seconds offset)

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 from 2017 through 2024. For dates outside of this range, see MICA.

This service requires a location and date, and may include height. More information about this data service may be found here.

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

The URL template for querying local circumstances of a given eclipse is:

The URL template for querying a list of eclipses in a given year is:

The date, coords, and height parameters are described in the sections above.

Example: generate solar eclipse local circumstances for 21 August 2017 at a location of 45.52° N, 122.65° W, which is at a height of 15 meters.

Example: generate a list of solar eclipses for the year 2024.

GeoJSON Notes:

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

• The first items in the GeoJSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• A list of information about the location will be given in "geometry"
• "coordinates" — gives an array of the coordinates ([longitude,latitude])
• "height" — the height requested (zero if not provided)
• "type" — the type of geometry object
• A list of eclipse information will be given in "properties"
• "deltaT" — the ΔT value used in the calculations
• "description" — the description of the event at the given location
• "duration" — the duration of the eclipse at this location
• "event" — the date and type of eclipse
• A list of eclipse phenomena will be listed in "local_data"
• "altitude" — the altiude of the Sun during this event
• "azimuth" — the azimuth of the Sun during this event
• "day" — the day of the month (some eclipses occur over two days in UT1)
• "phenomenon" — the name of the eclipse event
• "position_angle" — the position angle of the event, not given for maximum eclipse or sunrise/sunset
• "time" — time (given in UT1)
• "duration_of_totality" — the duration of eclipse totality at this location, for locations where total eclipse occurs only
• "vertex_angle" — the vertex angle of the event, not given for maximum eclipse or sunrise/sunset
• "magnitude" — the magnitude of the eclipse
• "obscuration" — the percentage of obscuration of the Sun by the Moon
• "type" — the GeoJSON object type

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

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "year" — the Gregorian year of the maximum of the eclipse
• A list of eclipse phenomena will be provided in "eclipses_in_year"
• "year" — year of the eclipse date
• "month" — month of the eclipse date
• "day" — the day of the month (some eclipses occur over two days in UT1)
• "event" — the date and type of eclipse

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. More information about this data service may be found here.

The URL template for querying this service is:

The year parameter is described above.

Example: generate the list of selected Christian observances for the year 2016.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "year" — the year requested
• The dates will be listed in "data"
• "observance" — the name of the observance (Ash Wednesday, Easter, etc.)
• "year" — the Gregorian year
• "month" — the calendar month
• "day" — day of the month

Back to the top

Selected Jewish Observances

This data service provides the dates for Rosh Hashanah (Jewish New Year), Yom Kippur (Day of Atonement), first day of Succoth (Feast of Tabernacles), Hanukkah (Festival of Lights), first day of Pesach (Passover), and Shavuot (Feast of Weeks) in a given year. Data will be provided for the years 360 C.E. (A.M. 4120) through 9999 C.E. (A.M. 13761). More information about this data service may be found here.

The URL template for querying this service is:

The year parameter is described above.

Example: generate the list of selected Jewish observances for the year 2018.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "year" — the year requested
• The dates will be listed in "data"
• "observance" — the name of the observance (Rosh Hashanah, Yom Kippur, etc.)
• "year" — the Gregorian or Julian year (Julian calendar date returned for dates prior to 15 October 1582)
• "month" — the calendar month
• "day" — day of the month
• "jewishyear" — the Jewish calendar year of the observance

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.. More information about this data service may be found here.

The URL template for querying this service is:

The year parameter is described above.

Example: generate the list of selected Islamic observances in the year 2020.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "year" — the year requested
• The dates will be listed in "data"
• "observance" — the name of the observance (Islamic New Year, First Day of Ramadân, or Shawwál)
• "year" — the Gregorian or Julian year (Julian calendar date returned for dates prior to 15 October 1582)
• "month" — the calendar month
• "day" — day of the month
• "islamicyear" — the Islamic calendar year of the observance

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. More information about this data service may be found here.

The URL templates for querying this service are:

The date and time parameters are described above. Time is assumed to be in UT1. The paramter 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, the data service will convert it to 1 B.C.

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

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

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 for querying this service is:

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

Example: generate the Gregorian date and the time corresponding to Julian date 2453124.1526.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• The date information will be listed in "data"
• "month" — the month
• "day" — the day of the month
• "year" — the Gregorian or Julian year (Julian calendar date returned for dates prior to 15 October 1582)
• "era" — the era of the year (output will only list AD or BC, not CE or BCE)
• "time" — the time of day (in UT1)
• "tz" — the time zone (always 0 for this data service)
• "jd" — the Julian date
• "dayofweek" — the day of the week (only returned for Julian date to calendar date conversions)

Back to the top

Earth's Seasons - Equinoxes, Solstices, Perihelion, and Aphelion

This data service calculates the dates and times of Earth's seasons and apsides. Data will be provided for the years 1700 through 2100 inclusive. More information about this data service may be found here.

The URL template for querying this service is:

The year parameter is described in the sections above.

Example: generate the dates and times (UTC) of Earth's seasons and apsides in 1899.

Optionally, time zone and daylight saving time information may be included. Both parameters are described in the sections above.

Example: generate the dates and times of Earth's seasons and apsides in 2007 for Central Time (US), with times adjusted for daylight saving when appropriate.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• "tz" — the time zone
• "dst" — boolean flag indicating whether or not daylight saving time conversion is enabled
• The date information will be listed in "data"
• "phenom" — the name of the phenomenon (Perihelion, Aphelion, Solstice, or Equinox)
• "month" — the month
• "day" — the day of the month
• "year" — the year
• "time" — the time of day (in the time zone listed in "tz" above); if dst is true, either "ST" or "DT" will be specified

Back to the top

Daylight Saving Time

This data service calculates the start and end dates for U.S. Daylight Saving Time for the years 1967 through 9999 (assuming future years maintain the same rules for start and end dates). More information about this data service may be found here.

The URL template for querying this service is:

The year parameter is described above.

Example: generate the start and end dates for Daylight Saving Time in 1990.

JSON Notes:

• The first items in the JSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• The date information will be listed in "data"
• "event" — the name of the event (Start or End of Daylight Saving Time)
• "month" — the month
• "day" — the day of the month
• "year" — the year

Back to the top

Celestial Navigation Data for Assumed Position and Time

This data service provides all the astronomical information necessary to plot navigational lines of position from observations of the altitudes of celestial bodies. More information about this data service may be found here.

The URL template for querying this service is:

The date, time, and coords parameters are described above.

Example: generate celestial navigation data for August 30, 2021 at 16:11 at 36.8508° N, 75.2859° W.

GeoJSON Notes:

• The first items in the GeoJSON contain the following header information:
• "error" — only present if the computation didn't run correctly; no other data will be given
• "apiversion" — the API version used to generate the JSON data
• A list of information about the location will be given in "geometry"
• "coordinates" — gives an array of the coordinates ([longitude,latitude])
• "type" — the type of geometry object
• A list of information will be given in "properties"
• "year" — the year requested
• "month" — the month requested
• "day" — the day of the month requested
• "time" — the time (given in UT1)
• "tz" — the time zone (defaults to UT1)
• "moon_phase" — the phase of the moon at the given date and time; if visible
• "moon_illum" — the percentage illumination of the moon at the given date and time; if visible
• A list of celestial objects and their observational parameters will be listed in "data"
• "object" — the name of the celestial object
• "nav_star_number" — navigational star number of the object; if applicable
• "almanac_data"
Note: the given precision may exceed the accuracy of the values displayed on the webpage.
• "dec" — the declination in decimal degrees
• "gha" — the Greenwich Hour Angle in decimal degrees
• "hc" — the computed geocentric altitude in decimal degrees
• "zn" — the computed azimuth in decimal degrees
• "altitude_corrections"
Note: the given precision may exceed the accuracy of the values displayed on the webpage.
• "isCorrected" — boolean that indicates if altitude corrections are displayed
• "pa" — the parallax in altitude in decimal degrees
• "refr" — the atmospheric refraction in decimal degrees
• "sd" — the semidiameter in decimal degrees
• "sum" — the sum of the other three altitude corrections in decimal degrees
• "type" — the GeoJSON object type

Back to the top