close window

Javascript Ephemeris Tool Manual

Ephemeris Tool is a collection of javascript tools for calculating ephemerides etc of solar system objects and presenting the results as charts or lists. Ephemeris Tool can be used for calculating ephemerides of solar system objects, e.g. rise and set times of Sun, Moon, planets and much more.

This script, which has now become a part of the AstroTools suite, is a further development of Javascript Skyplanner.
Ephemeris Tool (and Skyplanner) was inspired by "Javascript Ephemeris" written by Peter Hayes. Although most code is new or rewritten some code here and there can be attributed to Peter's original code. Please see the copyright notices further below.

The application is written entirely in javascript and executed by the Javascript interpreter of standard web browsers. Thus all calculations take place on your own machine. There is no server interaction and you can actually download Ephemeris Tool and run it offline on your computer, see below.


Ephemeris Tool can be used to display astronomical data either as charts or as traditional ephemerides etc. Most tools are available in both a graphical mode and a text mode format but there are some differences in the information provided.

Brief instructions:
To use Ephemeris Tool set your location and time zone, specify start date and time, time span and step, then select the desired object, select graphical or text mode output and finally click the desired tool. The yellow fields are required inputs. For more details, read on.

The calculations can be slow depending on the speed of your computer, the browser used and the requested output. Don't panic if it looks like your browser hangs. It is just thinking! New versions of Mozilla (and Firefox) may occasionally show an alert box warning that "A script is causing mozilla to run slow" and offering you to abort it. Just click "Cancel" to continue running the script.

Location and time zone

Enter the name and latitude/longitude of your location here. Alternatively you can select one of the locations from the drop down list. It may be a good idea to first select a town near your place from the list to get the time zone correct and then manually edit the name and latitude/longitude as needed. For the latitude and longitude enter UNSIGNED values on the form DD or DD:MM (DD:MM:SS is also allowed). Remember to check the correct North/South and East/West radio buttons. Enter time zone as +/-H:MM. The time zone is positive east of Greenwich and negative if west of Greenwich (e.g. in the United States). You can easily switch between daylight saving time (DST) and standard time by checking/unchecking the DST box.
NB: If you select one of the places from the selection list the time zone for that location will be used including correction for DST if applicable (the algorithm for determining DST is not fool proof so please check if the time zone is correct).

You can save your home location to a cookie such that Ephemeris Tool will automatically use your place the next time you visit Ephemeris Tool. The cookie will also remember the time zone and if daylight saving time is in force. Press 'Store' to save the current location. 'Recall' will load the location data from the cookie and 'Delete cookie' will do exactly that. Obviously, your browser must allow cookies to be set for this function to work.

Date and time

Enter the desired start date and time. Use the format YYYY:MM:DD for date and HH:MM for time. Use the '+' and '-' buttons for quickly changing the date and time. The function of the 'Now', 'Midnight' and 'Noon' buttons should be obvious. The 'Now' button depends on the system clock so make sure that the system clock and time zone of your computer are correctly set. The 'Julian day' field shows the current date and time in julian day format, a format preferred for astronomical calculations. Ephemeris Tool uses julian days as its internal time representation. You may also enter a julian day, handy if you need to convert a julian day number into normal date and time format. The 'Sidereal time' field is 'read-only'. See glossary for explanation of sidereal time.

Select time span and step

Specify the desired time span (default 7 days) and the time step (default 1 day) for ephemerides etc. Some tools ignore these settings (Alt-Az and Separation) or only use the time span selection (Event searches). Daily Events and Twilight Altitude ignore time steps of less than one day.

Select object(s)

Select the desired object from the drop down list. In addition to the standard solar system objects you may also specify a User Object having fixed coordinates such as a star or deep sky object. Enter the RA/Dec coordinates and eventually a name of your choice. Alternatively you can select either a star or a deep sky object from the built-in catalogues. The data from the selected object will be copied into the user object fields. Only some tools support the User Object.
Comets: Select a comet from the comet drop menu. I will try to keep the list updated with currently interesting comets (those getting brighter than magn. 10 or so). If you download Ephemeris Tool to your own computer you may add comets of your own choice. You will need to add the orbital elements to the comet.js file, see the instructions in that file. One warning: Don't work with a comet at dates more than 1-2 years from the date of perihelion. The formulae used are not accurate far from perihelion. Also note that elements for periodic comets are only valid for one particular perihelion passage.
All Planets (incl. Sun and Moon): Supported by most chart mode tools but of the text mode tools only 'Daily Events', 'Data' and 'Positions' support it and only for a single time instant


Select the desired output mode (chart or text) using the radio buttons. Then click the desired tool.

Daily events (Visibility)

Chart: Displays a coloured bar for each day, the colours indicating the times of daylight, twilights and darkness. Yellow and green colours shows the visibility of the chosen object. The bars always start at 12:00 (noon) irrespective of the time setting. If the object is the Moon the illumination is shown to the right.
Text: Shows rise, transit and set times for the chosen object. If 'Sunrises/sets' checked all twilight and sunrise/set times will be shown as well.

Object Data

(Chart/Text) Shows distance to Sun (text only) and Earth, diameter, illumination and brightness for the chosen object.

Object Position

(Chart/Text) The charts are only able to show one parameter at a time, thus you must click the desired radio button (Declination (+ RA), Longitude (+ latitude) or Elongation). The text mode listing will show right ascension (RA), declination, altitude, azimuth, ecliptic longitude, latitude and elongation for chosen object. Positions are geocentric except for altitude and azimuth (topocentric).

Twilight Altitude

(Chart/Text) Shows the altitude and azimuth (text mode only) of the chosen object when the Sun is at the specified angle below the horizon. Also shows if the object is rising or setting. The elongation is shown in text mode. This tools is particularly useful for showing the visibility of objects having a small elongation like Mercury and Venus.


(Chart/Text) Shows topocentric altitude and azimuth for the chosen object. Further displays if it is day or night and if the Moon is up (text mode only). Select the time step (5 - 120 minutes) before clicking this tool. The table is always generated for a 24 hour period.


(Text only) Shows the apparent angular separation of two objects and the corresponding position angle (PA).
Topocentric altitude and azimuth are displayed for the first object, then the separation and PA, then 'yes' if the two objects "touch" and finally if it is daylight, twilight or dark. This tool uses the time step selection of 'Alt-Az' and always generates a table for 24 hours. This function is useful for investigating close mutual conjunctions and also as a crude tool for detecting solar eclipses, lunar occultations etc. Due to the limited precision contact times may be some minutes off the correct values. Always confirm results with other sources if you want to observe occultations and other "close" events.

Visible Stars/Deep sky objects

This tool is useful for finding observable objects at a given time.
Text mode: Shows all stars or deep sky objects visible at the selected time (text mode).
Chart mode: Show visibility through the day of all objects reaching the altitude limit (see below) at the observer's latitude are shown.
Controls: Use Minimum altitude to exclude objects lower than this altitude. If you check Sort in R.A the list of objects will be sorted in right ascension order starting with objects setting in the western sky and ending with objects rising in the eastern sky. Objects near transit (the optimal time for observation) can be found in the middle of the list. In chart mode the display will start with objects transiting just after noon. Look for objects having a transit near the desired observing time.


The program aims to present a quick overview of the desired data, not to provide high precision numbers. It trades precision for speed and size. Don't expect better precision than about 1-2 arcminutes on positions. A better precision than this would require other theories using large tables and correspondingly slow execution.

Ephemeris Tool uses the following theories for calculating planetary and lunar positions: Planetary calculations are based on the formulae in Paul Schlyter's article "Computing planetary positions". He claims a precision of about 2 arcminutes on positions. Lunar calculations use a truncated version of the method presented in "Astronomical Algorithms", 2nd edition by Jean Meeus. Lunar positions should be good to about 1 arcminute. "Astronomical Algorithms" is a strongly recommended book for anybody interested in performing astronomical calculations. It has helped me with various formulae for translating between coordinate systems, calculating rise and set times and much more. Please note that the theories only provide the specified precision between 1000 AD and 3000 AD or so. Outside this time interval errors will grow quickly.

Where is Pluto?

I have not included Pluto for various reasons: First of all Pluto requires a different theory than the other planets meaning extra code. Secondly Pluto only moves very slowly over the sky (it will stay in Serpens/Sagittarius for the next many years to come). It is also extremely faint and you will anyway need a detailed planetarium programme to locate it (and a big telescope to see it!). And finally: Is Pluto a planet?

Browser notes

Ephemeris Tool is demanding on the javascript interpreter of the browser and requires CSS2 support. Older browsers may crash or report errors. Most recent browsers should be able to run Ephemeris Tool. Recommended browsers are Mozilla 1.7, Firefox and Internet Explorer 6 or better. The script has been tested on various computers with the following browsers running under Windows 98 SE, ME, 2000 and XP:
Mozilla 1.7.3, Firefox 1.0 and Internet Explorer 6

Speed: The speed of Ephemeris Tool depends on the function and number of output lines. Most tools with reasonable combinations of time span and time step will finish within a couple of seconds on average hardware.