The Astronomy Database provides various useful pieces of information about the perceived movement of the Sun and the Moon from the vantage point of a given latitude and longitude on Earth.

The Web API returns the time of: sunrise and sunset; solar noon and midnight; solar, civil, nautical, and astronomical dawn and dusk; and moonrise and moonset. If the optional dateTime parameter is specified in the query string of the API call, that date and time are used in place of the current date and time as the reference day. All times are given for the reference day and the day after it in local ISO 8601 date-time format (including the time zone offset annotation), and in UTC milliseconds since 1970. The current topocentric coordinates of the Sun and Moon are also reported, including the azimuth, zenith, right ascension, declination, and distance.

The Java and .NET Libraries offer greater flexibility, allowing queries at any time from 29 July 1899, to 9 October 2053, but all times are returned in UTC. When using the Java and .NET Library, you will also require the time zone of a given location in order to convert into local time. If you do not have the time zone information on hand, you might also be interested in the TimeZone Database.

The AskGeo Astronomy Database is extremely accurate. The Java and .NET Libraries at their core are ports and adaptations of the U.S. Naval Observatory's Vector Astrometry Software (NOVAS). For more information on why the AskGeo Astronomy Database is so much more accurate than most other solutions, please see the Accuracy Section below.

Need Additional Astronomy Information?

The AskGeo Astronomy Java and .NET Libraries expose only a small fraction of the potential of our port of NOVAS. If you need some astronomical functionality that is not exposed in the existing API, please email us at support@__remove_this_part__askgeo.com and we will try to help you out.

Accuracy

Accurately calculating the motion of the Sun and Moon is considerably more complicated that one might expect at first glance. The orbits of the Earth about the Sun and the Moon about the Earth are irregular, the spin axis of the Earth wobbles in two different ways (precession and nutation), and the time scales used by astronomers don't agree with coordinated universal time (UTC). On top of that, atmospheric refraction distorts the perceived position of celestial bodies (especially near the horizon); the rising and setting of the Sun and Moon are typically defined by the first appearance of the disk above the horizon, not the passing of the center of the disk; and the perceived size of the disk varies over time according to its distance from the observer. This section describes the models that are used by the Askgeo Astronomy Database to deliver extremely high accuracy results.

Planetary Ephemeris

An ephemeris is a model that specifies how the positions of astronomical objects change over time. The AskGeo Astronomy Database incorporates NASA's Jet Propulsion Laboratory's DE421 Ephemeris, the latest JPL ephemeris with fully consistent treatment of planetary and lunar laser ranging data. The JPL reports this ephemeris to have sub-meter accuracy for the orbit of the Moon and sub-kilometer accuracy for the orbit of the Earth. To put this into perspective, a the distance from the Earth to the Moon is 380 million meters and the distance from the Sun to the Earth is about 150 million kilometers.

Earth's Rotation

The irregular rotation of the Earth is modeled by tracking the right ascension (RA) of the Celestial Intermediate Origin (CIO). The AskGeo Astronomy Database incorporates the model for RA of the CIO adopted by the IAU (International Astronomical Union) in 2000.

Earth's Precession

Precession is the movement of the rotational axis of an astronomical body. The AskGeo Astronomy Database incorporates the International Astronomical Union's P03 model for the precession of the Earth (developed by Capitaine, Wallace, and Chapront in 2003).

Earth's Nutation

Compared to precession, nutation is a smaller wobble in the movement of the rotational axis of an astronomical body. Nutation is harder and more computationally intensive to model than precession, so we offer three models in the Java and .NET Libraries. The most accurate is the IAU 2000A model, which consists of 1,365 trigonometric terms, more than 10 times the number in the previous best model. To reduce computation times, we also offer a truncated version called IAU 2000K that consists of the 488 most significant terms in the 2000A model and is accurate to about 0.1 milliarcseconds. The least accurate model we offer is the IAU 2000B model, which consists of 77 terms and is accurate to about 1 milliarcsecond. The 2000B model, which is sufficiently accurate for most purposes, is used the Web API. All the models are available in the Java and .NET Libraries.

Time Scales

Astronomical computations require the use of a number of time scales that are not typically encountered in other fields. Coordinated Universal Time (UTC) is the worldwide basis for civil time and determines the times indicated on wall clocks, and digital devices of all sorts. International Atomic Time (TAI) is based on an extremely accurate atomic clock and differs from UTC by an integral number of leap seconds. Terrestrial Time (TT) is a constant offset of 32.184 seconds from TAI. Universal Time (UT1) is based on the rotation of the Earth and differs from TT by a floating point quantity called ΔT that varies smoothly over time. The AskGeo Astronomy Database incorporates the official record of leap seconds as published by the U.S. Naval Observatory (USNO). Historical values for ΔT are taken from the Astronomical Almanac and predicted values are taken from the USNO.

Atmospheric Refraction

Atmospheric refraction distorts the perceived position of celestial bodies, especially near the horizon. The AskGeo Astronomy Database incorporates the widely used atmospheric refraction model developed by G. Bennett in 1982.

Upper Limb

While astronomical models track the position of the centers of astronomical bodies, the rise and set of the Sun/Moon are typically defined by the first appearance of the top of the solar/lunar disk (called the upper limb) above the horizon. This distinction means that the angular radius of the disk must be accounted for. The AskGeo Astronomy Database correctly uses the distance to the body in question to compute the angular radius.

Search

Astronomical models such as NOVAS compute the perceived position of astronomical bodies. Computing the precise time of various key events (e.g., the rise and set of the Sun and Moon) requires a numerical search strategy to find when the position of a given body crosses a particular boundary (e.g., the horizon). Low quality implementations run into problems in the polar regions, where there are cases where the Sun and Moon just barely rise or just barely set. The AskGeo Astronomy Database solves the search problem rigorously: extrema in the topocentric elevation are computed first with a binary search; the rise, set, and various twilights are then computed using a golden section search with the aforementioned extrema as the initial bounds.

For more information about the inner workings, please see the original NOVAS project, which we have ported to Java and .NET and expanded to create the AskGeo Astronomy Database. If you are considering using a different commercial or open source solution and you care about accuracy, we encourage you inquire as to whether all of the above issues are handled correctly.

Returned Values

The AskGeo Astronomy Web API returns several values in response to a given query point. These values are listed below.

KeyDescriptionUnitsType
TodaySolarMidnightUtcMsecs Today's solar midnight: Sun's elevation at minimum (milliseconds since 1970: unix time) millisecondslong
TodaySolarMidnightIso8601 Today's solar midnight: Sun's elevation at minimum (ISO 8601 date-time format with time zone offset) -String
TodayAstronomicalDawnUtcMsecs Today's astronomical dawn: Sun 18° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TodayAstronomicalDawnIso8601 Today's astronomical dawn: Sun 18° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TodayNauticalDawnUtcMsecs Today's nautical dawn: Sun 12° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TodayNauticalDawnIso8601 Today's nautical dawn: Sun 12° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TodayCivilDawnUtcMsecs Today's civil dawn: Sun 6° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TodayCivilDawnIso8601 Today's civil dawn: Sun 6° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TodaySunriseUtcMsecs Today's sunrise: Sun's upper limb climbs above horizon (milliseconds since 1970: unix time) millisecondslong
TodaySunriseIso8601 Today's sunrise: Sun's upper limb climbs above horizon (ISO 8601 date-time format with time zone offset) -String
TodaySolarDawnUtcMsecs Today's solar dawn: Sun 6° above horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TodaySolarDawnIso8601 Today's solar dawn: Sun 6° above horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TodaySolarNoonUtcMsecs Today's solar noon: Sun's elevation at maximum (milliseconds since 1970: unix time) millisecondslong
TodaySolarNoonIso8601 Today's solar noon: Sun's elevation at maximum (ISO 8601 date-time format with time zone offset) -String
TodaySolarDuskUtcMsecs Today's solar dusk: Sun 6° above horizon and falling (milliseconds since 1970: unix time) millisecondslong
TodaySolarDuskIso8601 Today's solar dusk: Sun 6° above horizon and falling (ISO 8601 date-time format with time zone offset) -String
TodaySunsetUtcMsecs Today's sunset: Sun's upper limb falls below horizon (milliseconds since 1970: unix time) millisecondslong
TodaySunsetIso8601 Today's sunset: Sun's upper limb falls below horizon (ISO 8601 date-time format with time zone offset) -String
TodayCivilDuskUtcMsecs Today's civil dusk: Sun 6° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TodayCivilDuskIso8601 Today's civil dusk: Sun 6° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TodayNauticalDuskUtcMsecs Today's nautical dusk: Sun 12° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TodayNauticalDuskIso8601 Today's nautical dusk: Sun 12° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TodayAstronomicalDuskUtcMsecs Today's astronomical dusk: Sun 18° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TodayAstronomicalDuskIso8601 Today's astronomical dusk: Sun 18° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TodayMoonriseUtcMsecs Today's moonrise: Moon's upper limb climbs above horizon (milliseconds since 1970: unix time) millisecondslong
TodayMoonriseIso8601 Today's moonrise: Moon's upper limb climbs above horizon (ISO 8601 date-time format with time zone offset) -String
TodayMoonsetUtcMsecs Today's moonset: Moon's upper limb falls below horizon (milliseconds since 1970: unix time) millisecondslong
TodayMoonsetIso8601 Today's moonset: Moon's upper limb falls below horizon (ISO 8601 date-time format with time zone offset) -String
TomorrowSolarMidnightUtcMsecs Tomorrow's solar midnight: Sun's elevation at minimum (milliseconds since 1970: unix time) millisecondslong
TomorrowSolarMidnightIso8601 Tomorrow's solar midnight: Sun's elevation at minimum (ISO 8601 date-time format with time zone offset) -String
TomorrowAstronomicalDawnUtcMsecs Tomorrow's astronomical dawn: Sun 18° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TomorrowAstronomicalDawnIso8601 Tomorrow's astronomical dawn: Sun 18° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TomorrowNauticalDawnUtcMsecs Tomorrow's nautical dawn: Sun 12° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TomorrowNauticalDawnIso8601 Tomorrow's nautical dawn: Sun 12° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TomorrowCivilDawnUtcMsecs Tomorrow's civil dawn: Sun 6° below horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TomorrowCivilDawnIso8601 Tomorrow's civil dawn: Sun 6° below horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TomorrowSunriseUtcMsecs Tomorrow's sunrise: Sun's upper limb climbs above horizon (milliseconds since 1970: unix time) millisecondslong
TomorrowSunriseIso8601 Tomorrow's sunrise: Sun's upper limb climbs above horizon (ISO 8601 date-time format with time zone offset) -String
TomorrowSolarDawnUtcMsecs Tomorrow's solar dawn: Sun 6° above horizon and climbing (milliseconds since 1970: unix time) millisecondslong
TomorrowSolarDawnIso8601 Tomorrow's solar dawn: Sun 6° above horizon and climbing (ISO 8601 date-time format with time zone offset) -String
TomorrowSolarNoonUtcMsecs Tomorrow's solar noon: Sun's elevation at maximum (milliseconds since 1970: unix time) millisecondslong
TomorrowSolarNoonIso8601 Tomorrow's solar noon: Sun's elevation at maximum (ISO 8601 date-time format with time zone offset) -String
TomorrowSolarDuskUtcMsecs Tomorrow's solar dusk: Sun 6° above horizon and falling (milliseconds since 1970: unix time) millisecondslong
TomorrowSolarDuskIso8601 Tomorrow's solar dusk: Sun 6° above horizon and falling (ISO 8601 date-time format with time zone offset) -String
TomorrowSunsetUtcMsecs Tomorrow's sunset: Sun's upper limb falls below horizon (milliseconds since 1970: unix time) millisecondslong
TomorrowSunsetIso8601 Tomorrow's sunset: Sun's upper limb falls below horizon (ISO 8601 date-time format with time zone offset) -String
TomorrowCivilDuskUtcMsecs Tomorrow's civil dusk: Sun 6° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TomorrowCivilDuskIso8601 Tomorrow's civil dusk: Sun 6° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TomorrowNauticalDuskUtcMsecs Tomorrow's nautical dusk: Sun 12° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TomorrowNauticalDuskIso8601 Tomorrow's nautical dusk: Sun 12° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TomorrowAstronomicalDuskUtcMsecs Tomorrow's astronomical dusk: Sun 18° below horizon and falling (milliseconds since 1970: unix time) millisecondslong
TomorrowAstronomicalDuskIso8601 Tomorrow's astronomical dusk: Sun 18° below horizon and falling (ISO 8601 date-time format with time zone offset) -String
TomorrowMoonriseUtcMsecs Tomorrow's moonrise: Moon's upper limb climbs above horizon (milliseconds since 1970: unix time) millisecondslong
TomorrowMoonriseIso8601 Tomorrow's moonrise: Moon's upper limb climbs above horizon (ISO 8601 date-time format with time zone offset) -String
TomorrowMoonsetUtcMsecs Tomorrow's moonset: Moon's upper limb falls below horizon (milliseconds since 1970: unix time) millisecondslong
TomorrowMoonsetIso8601 Tomorrow's moonset: Moon's upper limb falls below horizon (ISO 8601 date-time format with time zone offset) -String
CurrentDateTimeIso8601 Current time (in ISO 8601 format) n/aString
CurrentDateTimeUtcMsecs Current time (UTC) millisecondslong
SunAzimuthDeg Current azimuth of the Sun degreesdouble
SunZenithDeg Current zenith of the Sun degreesdouble
SunRightAscensionHours Current right ascension of the Sun hoursdouble
SunDeclinationDeg Current declination of the Sun degreesdouble
SunDistanceAu Current distance to the Sun AUdouble
MoonAzimuthDeg Current azimuth of the Moon degreesdouble
MoonZenithDeg Current zenith of the Moon degreesdouble
MoonRightAscensionHours Current right ascension of the Moon hoursdouble
MoonDeclinationDeg Current declination of the Moon degreesdouble
MoonDistanceAu Current distance to the Moon AUdouble

Please note that if the optional dateTime parameter is specified in the query string of the API call, that date and time are used in place of the current date and time for all results given in the response to that query.

Java Library

All AskGeo Java Libraries are compatible with Java 6, have no external dependencies, and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

Documentation

There are five classes that you need to be aware of to use the AskGeo Astronomy Java Library.

class Earth

Provides the primary user-facing interface to the AskGeo Astronomy Java Library.

class TopocentricCoordinates

Embodies the topocentric coordinates of an astronomical body from the perspective of an observer on the surface of the Earth at a given location at a given time.

class ZenithEvent

Represents one of several meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer (e.g., the rising or setting of the Sun).

enum Accuracy

Enumerates the three available accuracy levels available when constructing an Earth instance.

enum ZenithEvent.Type

Enumerates the types of ZenithEvents that are available for query from an Earth instance.

They are described in further detail in the sections that follow.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo Astronomy Java Library.

For full documentation of the classes included, please see the:

Full Java Docs

Earth

An Earth instance allows queries of the sun and moon related events that have taken place during a given time interval at a given location, as well as queries of the topocentric positions of the Sun and Moon from a given vantage point at a given time. The events that may be queried are enumerated in the ZenithEvent.Type enum. The topocentric coordinates that are returned include the azimuth, zenith, declination, right ascension, and distance to the body from the observer.

All times are in UTC milliseconds since 1970 (standard Unix time). Angles are in degrees. In general, the units of a given variable are included as a suffix in the variable name.

class Earth {
 Earth(InputStream dataFileStream, Accuracy accuracy)
Constructs an Earth instance with a given accuracy level.
  • InputStream dataFileStream: Input Stream of the Data File to be read to create this object
  • Accuracy accuracy: the accuracy level (e.g., LOW_ACCURACY, MEDIUM_ACCURACY, or HIGH_ACCURACY)
ZenithEvent[] sunZenithEvents(long startTimeMsecs, long endTimeMsecs, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEvent.Type[] types)
Returns an array of ZenithEvent objects that occurred for the Sun during the given time interval and at the given location.
  • long startTimeMsecs: Start time of the closed interval in milliseconds since 1970
  • long endTimeMsecs: End time of the closed interval in milliseconds since 1970
  • long maxTimeErrorMsecs: Convergence criterion used in the numerical search methods
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • ZenithEvent.Type[] types: Array of ZenithEvent.Type enum values for the events that the user wishes to be returned
ZenithEvent[] moonZenithEvents(long startTimeMsecs, long endTimeMsecs, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEvent.Type[] types)
Returns an array of ZenithEvent objects that occurred for the Moon during the given time interval and at the given location.
  • long startTimeMsecs: Start time of the closed interval in milliseconds since 1970
  • long endTimeMsecs: End time of the closed interval in milliseconds since 1970
  • long maxTimeErrorMsecs: Convergence criterion used in the numerical search methods
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • ZenithEvent.Type[] types: Array of ZenithEvent.Type enum values for the events that the user wishes to be returned
TopocentricCoordinates sunTopocentricCoordinates(long msecsSince1970, double latDeg, double lonDeg, double heightM, boolean includeRefraction)
Returns the topocentric coordinates of the Sun at the given time and at the given location.
  • long msecsSince1970: Time of query in milliseconds since 1970
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • boolean includeRefraction: Set to true to include atmospheric refraction in the model
TopocentricCoordinates moonTopocentricCoordinates(long msecsSince1970, double latDeg, double lonDeg, double heightM, boolean includeRefraction)
Returns the topocentric coordinates of the Moon at the given time and at the given location.
  • long msecsSince1970: Time of query in milliseconds since 1970
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • boolean includeRefraction: Set to true to include atmospheric refraction in the model
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}

TopocentricCoordinates

The topocentric coordinates of a astronomical body are expressed in terms of an observer on the surface of the Earth at a given location at a given time. This object includes the azimuth (degrees), zenith (degrees), declination (degrees), right ascension (hours), and distance (astronomical units, AU).

The members of an instance are immutable and the constructor is not public. Instances of this class are returned by methods in the Earth class and can only be used by users in a read-only capacity.

The coordinates in this object may or may not include atmospheric refraction, depending on the parameters passed to the method that creates it. Please see the Earth class for more details.

class TopocentricCoordinates {
double getAzimuthDeg()
Returns the azimuth in degrees of an astronomical body at a particular time and from a particular location on the Earth.
double getZenithDeg()
Returns the zenith in degrees of an astronomical body at a particular time and from a particular location on the Earth.
double getRightAscensionHours()
Returns the right ascension in hours of an astronomical body at a particular time.
double getDeclinationDeg()
Returns the declination in degrees of an astronomical body at a particular time.
double getDistanceAu()
Returns distance to the astronomical body is given in astronomical units (AU).
}

ZenithEvent

A ZenithEvent object represents one of several particular and meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer. These include the rising and setting of the object in addition to a number of other important moments.

A full list of the zenith event types and their descriptions are given in the Java enumeration ZenithEvent.Type.

The elevation (also known as altitude) of an astronomical body is the complement of the zenith and represents the angle above the horizon of the body.

It should be noted that in polar regions of the globe some of these events do not occur for months at a time. The only events that occur every day at every location on the globe are MIN_ELEVATION and MAX_ELEVATION.

class ZenithEvent {
double getElevationDeg()
Returns the elevation of the body above the horizon in degrees.
long getTimeMsecs()
Returns the time at which the event occurred in milliseconds since 1970 (unix time).
ZenithEvent.Type getEventType()
Returns the event type as represented by a value of the ZenithEvent.Type Java enumeration.
String toString()
A String representation of the ZenithEvent, used internally for testing and suitable for debugging purposes in client code.
}

Accuracy

The accuracy of a new Earth instance is specified with this enumeration. Higher accuracy comes at the cost of longer computation times. The lowest accuracy is sufficient for most purposes.

The primary difference between the accuracy levels is in the number of terms used to represent the nutation of the Earth (described in each value below). In addition, the low and medium accuracy modes are less accurate in computing:

  • the complementary terms of the equation of the equinoxes
  • the geocentric position of a solar system body, as antedated for light-time
  • the total gravitational deflection of light for the observed body due to the major gravitating bodies in the solar system

The enumerated values are as follows:

LOW_ACCURACY

Uses the IAU 2000B nutation model that includes 77-terms and is accurate to about 1 milliarcsecond.

MEDIUM_ACCURACY

Uses the IAU 2000K nutation model that includes the largest 488 terms from the IAU 2000A model and is accurate to about 0.1 milliarcseconds.

HIGH_ACCURACY

Uses the IAU 2000A nutation model that includes 1,365 terms and is the most accurate model we make available.

Again, as the medium and high accuracy modes are more computationally expensive, it is important to emphasize that in most cases, the LOW_ACCURACY accuracy level will be sufficient.

ZenithEvent.Type

The ZenithEvent.Type enumerates the event types that mark important moments in the course of astronomical body's passage across the celestial sphere of an observer.

The enumerated values are listed in the JavaDocs

Java Example

The following is a complete example program demonstrating the use of the AskGeo Astronomy Java Library. It prints the sunrise and sunset times for the next 48 hours near San Francisco (latitude: 37 degrees, longitude: -122 degrees).

import com.askgeo.astronomy.*;
import java.io.FileInputStream;

public class AstronomyExample {
    static String license = "INSERT YOUR LICENSE STRING HERE";
    static String dataFilePath = "askgeo-astronomy-1.1.0.dat";

    public static void main(String[] args) {
        ZenithEvent.Type[] types = {
                ZenithEvent.Type.RISE_UPPER_LIMB,
                ZenithEvent.Type.SET_UPPER_LIMB
        };

        try {
            Earth earth = new Earth(new FileInputStream(dataFilePath), Accuracy.LOW_ACCURACY);
            earth.authorize(license);

            long start = System.currentTimeMillis();
            long end = start + 48L * 3600L * 1000L; // 48 hours later
            double latDeg = 37.0;
            double lonDeg = -122.0;
            double heightM = 0.0;

            ZenithEvent[] events = earth.sunZenithEvents(start, end, 1000L, latDeg, lonDeg, heightM, types);

            for (ZenithEvent event : events) {
                System.out.println(event.toString());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

.NET Library

All AskGeo .NET Libraries are compatible with .NET 4 and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures. Except for a few small changes to be more consistent with .NET style and coding conventions, the AskGeo .NET Libraries are a direct port of the AskGeo Java Libraries.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

Documentation

There are five classes that you need to be aware of to use the AskGeo Astronomy .NET Library.

class Earth

Provides the primary user-facing interface to the AskGeo Astronomy .NET Library.

class TopocentricCoordinates

Embodies the topocentric coordinates of an astronomical body from the perspective of an observer on the surface of the Earth at a given location at a given time.

class ZenithEvent

Represents one of several meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer (e.g., the rising or setting of the Sun).

enum Accuracy

Enumerates the three available accuracy levels available when constructing an Earth instance.

class ZenithEventType

Enumerates (with static public members) the types of ZenithEvents that are available for query from an Earth instance.

They are described in further detail in the sections that follow.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo Astronomy .NET Library.

For full documentation of the classes included, please see the:

Full .NET Docs

Earth

An Earth instance allows queries of the sun and moon related events that have taken place during a given time interval at a given location, as well as queries of the topocentric positions of the Sun and Moon from a given vantage point at a given time. The events that may be queried are enumerated (as static public members) in the ZenithEventType class. The topocentric coordinates that are returned include the azimuth, zenith, declination, right ascension, and distance to the body from the observer.

All times are as .NET DateTime objects. Angles are in degrees. In general, the units of a given variable are included as a suffix in the variable name.

class Earth {
 Earth(Accuracy accuracy)
Constructs an Earth instance with a given accuracy level.
  • Accuracy accuracy: the accuracy level (e.g., LowAccuracy, MediumAccuracy, or HighAccuracy)
ZenithEvent[] GetSunZenithEvents(DateTime start, DateTime end, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEventType[] types)
Returns an array of ZenithEvent objects that occurred for the Sun during the given time interval and at the given location.
  • DateTime start: Start time of the closed interval
  • DateTime end: End time of the closed interval
  • long maxTimeErrorMsecs: Convergence criterion used in the numerical search methods
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • ZenithEventType[] types: Array of ZenithEventType enum values for the events that the user wishes to be returned
ZenithEvent[] GetMoonZenithEvents(DateTime start, DateTime end, long maxTimeErrorMsecs, double latDeg, double lonDeg, double heightM, ZenithEventType[] types)
Returns an array of ZenithEvent objects that occurred for the Moon during the given time interval and at the given location.
  • DateTime start: Start time of the closed interval
  • DateTime end: End time of the closed interval
  • long maxTimeErrorMsecs: Convergence criterion used in the numerical search methods
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • ZenithEventType[] types: Array of ZenithEventType enum values for the events that the user wishes to be returned
TopocentricCoordinates GetSunTopocentricCoordinates(DateTime dateTime, double latDeg, double lonDeg, double heightM, boolean includeRefraction)
Returns the topocentric coordinates of the Sun at the given time and at the given location.
  • DateTime dateTime: Time of query
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • boolean includeRefraction: Set to true to include atmospheric refraction in the model
TopocentricCoordinates GetMoonTopocentricCoordinates(DateTime dateTime, double latDeg, double lonDeg, double heightM, boolean includeRefraction)
Returns the topocentric coordinates of the Moon at the given time and at the given location.
  • DateTime dateTime: Time of query
  • double latDeg: Latitude of the query point (degrees)
  • double lonDeg: Longitude of the query point (degrees)
  • double heightM: Height in meters above the geoid (i.e., theoretical sea level)
  • boolean includeRefraction: Set to true to include atmospheric refraction in the model
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

TopocentricCoordinates

The topocentric coordinates of a astronomical body are expressed in terms of an observer on the surface of the Earth at a given location at a given time. This object includes the azimuth (degrees), zenith (degrees), declination (degrees), right ascension (hours), and distance (astronomical units, AU).

The members of an instance are immutable and the constructor is not public. Instances of this class are returned by methods in the Earth class and can only be used by users in a read-only capacity.

The coordinates in this object may or may not include atmospheric refraction, depending on the parameters passed to the method that creates it. Please see the Earth class for more details.

class TopocentricCoordinates {
double GetAzimuthDeg()
Returns the azimuth in degrees of an astronomical body at a particular time and from a particular location on the Earth.
double GetZenithDeg()
Returns the zenith in degrees of an astronomical body at a particular time and from a particular location on the Earth.
double GetRightAscensionHours()
Returns the right ascension in hours of an astronomical body at a particular time.
double GetDeclinationDeg()
Returns the declination in degrees of an astronomical body at a particular time.
double GetDistanceAu()
Returns distance to the astronomical body is given in astronomical units (AU).
}

ZenithEvent

A ZenithEvent object represents one of several particular and meaningful moments in the course of an astronomical body's passage across the celestial sphere of an observer. These include the rising and setting of the object in addition to a number of other important moments.

A full list of the zenith event types and their descriptions are given in the static public members of the ZenithEventType class.

The elevation (also known as altitude) of an astronomical body is the complement of the zenith and represents the angle above the horizon of the body.

It should be noted that in polar regions of the globe some of these events do not occur for months at a time. The only events that occur every day at every location on the globe are MinElevation and MaxElevation.

class ZenithEvent {
double GetElevationDeg()
Returns the elevation of the body above the horizon in degrees.
DateTime GetDateTime()
Returns the time at which the event occurred in UTC as a DateTime object.
ZenithEventType GetEventType()
Returns the event type as represented by an instance of and static public member of the ZenithEventType class.
String ToString()
A String representation of the ZenithEvent, used internally for testing and suitable for debugging purposes in client code.
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

Accuracy

The accuracy of a new Earth instance is specified with this enumeration. Higher accuracy comes at the cost of longer computation times. The lowest accuracy is sufficient for most purposes.

The primary difference between the accuracy levels is in the number of terms used to represent the nutation of the Earth (described in each value below). In addition, the low and medium accuracy modes are less accurate in computing:

  • the complementary terms of the equation of the equinoxes
  • the geocentric position of a solar system body, as antedated for light-time
  • the total gravitational deflection of light for the observed body due to the major gravitating bodies in the solar system

The enumerated values are as follows:

LowAccuracy

Uses the IAU 2000B nutation model that includes 77-terms and is accurate to about 1 milliarcsecond.

MediumAccuracy

Uses the IAU 2000K nutation model that includes the largest 488 terms from the IAU 2000A model and is accurate to about 0.1 milliarcseconds.

HighAccuracy

Uses the IAU 2000A nutation model that includes 1,365 terms and is the most accurate model we make available.

Again, as the medium and high accuracy modes are more computationally expensive, it is important to emphasize that in most cases, the LowAccuracy accuracy level will be sufficient.

ZenithEventType

The ZenithEventType enumerates (as static public members) the event types that mark important moments in the course of astronomical body's passage across the celestial sphere of an observer.

The static public members (enumerated values) are listed in the .NET docs

.NET Example

The following is a complete example program demonstrating the use of the AskGeo Astronomy .NET Library. It prints the sunrise and sunset times for the next 48 hours near San Francisco (latitude: 37 degrees, longitude: -122 degrees).

using System;
using System.IO;
using AskGeo.Astronomy;

class Astronomy {
    static void Main(string[] args) {
        String license = "INSERT YOUR LICENSE STRING HERE";
        String dataFilePath = @"askgeo-astronomy-1.1.0.dat";
        
        ZenithEventType[] types = {
                ZenithEventType.RiseUpperLimb,
                ZenithEventType.SetUpperLimb
        };

        Earth earth = new Earth(new FileStream(dataFilePath, FileMode.Open), Accuracy.LowAccuracy);
        earth.Authorize(license);

        DateTime start = DateTime.Now;
        DateTime end = start.AddDays(2.0);
        double latDeg = 37.0;
        double lonDeg = -122.0;
        double heightM = 0.0;

        ZenithEvent[] events = earth.GetSunZenithEvents(start, end, 1000L, latDeg, lonDeg, heightM, types);

        foreach (ZenithEvent zenithEvent in events) {
            Console.WriteLine(zenithEvent.ToString());
        }
    }
}