JavaScript Ephemeris - Notes

Note: This is a mirror copy of the original web page, uploaded with permission of Peter Hayes

• Copyright Notice
• Usage Notes
• Location, Date and Time
• The Ephemeris Calculations
• Browser Notes
• References
• History
• Source Notes
• Links to Translations and Similar Sites

• If you find these pages or javascript functions useful you may save a copy for your personal use, the Source Notes describe how to save a copy and how a place is defined.
• If you want to publish a copy, translation or pages using any of my code on your internet web site you may do so, for non-commercial purposes, as long as you include this copyright notice and let me know so I can advise you of any corrections, my e-mail address is Peter Hayes.
• For commercial uses please contact me for permission, which will be given for any reasonable uses without charge other than a donation to a mutually agreed charity.
• The methods used in these JavaScript functions are derived from Astronomical Algorithms, first edition, by Jean Meeus, published by Willmann-Bell and the web pages of Paul Schlyter.

Location, Date and Time

• You can change the location, date, civil time, time zone & Daylight Saving Time fields in the table. The other time fields in the table will be updated when you use the tab key to move to another box or click on one of the buttons.

• The initial Location is set to Greenwich UK, other places are sorted with Europe and the USA first (because that is where most of my users are). If you select another location from the supplied list the latitude, longitude and UT offset (with some attempt at daylight saving correction) will be changed. You can also alter the place name, latitude and longitude (the location menu will change to unknown).

  You can pass a location to this web page by adding a query string to the URL. It should look something like these examples

  Cheltenham	?Name='Cheltenham'
  My Home in Winter	?Name='My%20Home'&Lat=51.88&Lon=-2.12&TZ=0&DST=false
  My Home in Summer	?Name='My%20Home'&Lat=51.88&Lon=-2.12&TZ=0&DST=true
  Chippewa Falls	?Name='Chippewa%20Falls'&Lat=+44.93&Lon=-91.39&TZ=-6

  • Name is any text string, note the way of putting a space in the examples.
    The script will do a pattern match against it's known locations so you only need to supply the name for places in the supplied list.
  • Latitude is positive if North.
  • Longitude and Time Zone are positive if East of Greenwich. Do NOT include daylight saving time in the TZ use DST.

• Date, shown as year:month:day, is the local date and Civil Time is the clock time including any daylight saving correction for the selected place. If you change the date by hand the DST tick box may change as well because of daylight saving.
• Time Zone is the correction as hours:minutes from your civil time to UT (Greenwich time). The value for London and Greenwich is 00:00. For Europe using Central European Time the value is 01:00 East. For Washington DC using EST the value is 05:00 West.
• DST is daylight Saving Time, tick if DST is on. The program will set it according to the date for most known locations. The rules changed in 2007 for the USA so you will need to set it if working on dates in 2006 or earlier. You can turn it on or off if the program does not set it as you want.

• The Julian Date is defined as days since noon GMT on January 1 4713 BC.

• The UTC Time is the Universal Time at Greenwich. Remember the date may be different.
  The Local Time is UTC Time corrected for your longitude. Remember the date may be different.
  The Sidereal Time is the local sidereal time, the Right Ascension of objects that are due south.
  The Equation of Time shows the difference between local time (without any daylight saving correction) and apparent solar time as shown by a sundial.

  The Ephemeris Computations

• The Sun button calculates the Sun's position and rise and set times. The rise/set calculations are based on the upper limb of the Sun being on the horizon and allows for refraction. This is equivalent to calculating the times when the Suns elevation is -0.833 degrees. The Civil, Nautical and Astronomical dawn and dusk calculations are done for the Sun being 6, 12 and 18 degrees below the horizon respectively. The output is ++++ if the Sun is always above the specified elevation (midnight Sun) and ---- if always below. It is possible, particularly for Astronomical dusk, for the time to be in the morning of the next day.

• The Moon button calculates the Moon's position, phase angle, % illuminated and rise and set times. The phase angle is related to percentage illuminated, a phase angle of 0° is a full moon, 90° is first quarter, 180° is a new moon and 270° is last quarter. The calculation of the rise & set times is slow because of the complexity of the moon position calculations and the number of iterations needed. The rise/set calculations are only done to about 1 minute accuracy and the possibility in polar latitudes of more than 1 moon rise or set is not allowed for, the web page by Paul Schlyter listed below explains more about this.

• The Planets buttons calculate the positions, altitude and azimuth, rise, transit and set times for the specified time and place. Because the mean elements of the planets are used the error for the outer planets can be almost a degree. The output is ++++ if the planet is always above the horizon and ---- if always below.

• The Bright Stars button creates a table of over 100 of the brightest stars based on code from Stephane Macrez.
  

• The Repeat buttons calculate the same as the fixed time ones for several days. You can select the number of days and interval.

• The User Defined Object RA/Dec and Alt/Az converters work in either direction, just change the entries and click the conversion direction button.

• Internet Explorer version 6 under Windows 2000 and version 7 under XP. I no longer have access to Microsoft Windows but as long as they support standards my code should work.
• Mozilla based browsers including FireFox under Mac OS X and Windows XP. But not iOS on iPad2 and iPhone5s where the result windows are blank.
• Safari under Mac OS X and iOS on an iPad2 and iPhone5s.
• Opera Coast gives the right results on iOS on iPad and iPhone5s but does not recognise the Javascript close button, scroll left and right to get back to the main page. Opera works on OS X but the calculated windows, Sun & Moon etc. need to be resized.
• Google Chrome I am not testing any more because I object to them spying on me.
• My home page also has problems with Safari and iOS, Opera Coast seems more stable.

The following references were of use in the coding.

• Astronomical Algorithms, first edition, by Jean Meeus, published by Willmann-Bell. The chapter numbers change in the second edition.
• The computing planetary positions and how to compute rise/set times web pages by Paul Schlyter.
• The Royal Greenwich Observatory FAQ pages.
• Astronomical Almanac, at last online
• David Flanagan's excellent book JavaScript The Definitive Guide published by O'Reilly and Associates, Inc.

Several people have kindly pointed out errors, suggested improvements and supplied code. The main contributors were Stephane Macrez and Nick Reid.

• 18 December 2011: Minor change to sun.js to fit iPad screen.
• 11 April 2011: Correct position of Capella in stars.js
• 06 January 2011: Correction to datetime.js to fix a typo.
• 20 December 2010: Minor changes to stars.js so constellation is listed first.
• 22 April 2010 correction in observer.js for DST changing on last day of month
• 31 December 2009 a small fix to index.html if a user changes latitude or longitude and update the copyright notices in case I need to chase astrologers for unauthorized usage.
• 11 March 2009 corrected observer.js for daylight saving time changes not on the last Sunday of the month
• 13 August 2008 added and changed some sites in observer.js based on stellarium sites list
• 21 April 2008 moved one line in index.html to correct DST
• Version 7.1 change to display the local time for the selected observatory.
  If you have a local copy you need to reload index.html, observer.js, datetime.js & util.js for the version 7 changes.
  • Removed the get date/time/zone button, use reset instead.
  • Added code to reset1 to convert to observers local time
• Version 7.0 support for user defined locations
  
  • Thanks to the webmaster at Muskegon Astronomical Society for suggesting this change and testing it.
  • Revised updateplace to reset to location on URL
  • Changed table1 to support user changing place name
  • Added updatename function
  • Changes to reset1, rewrite1 and updatell to support changes
  • In observer.js re-wrote the observatory function and initial value of observer
  • In util.js added llstring to convert latitude and longitude
• Change observer.js for new USA daylight saving rules (01/2007)
• Version 6.7 Changes to clockhandler and table for get date/time/timezone
  • Merge get date/time with get time zone buttons
  • Attempt to derive daylight saving info from browser's host system.
    Code based on method by Dr. J R Stockton
• Version 6.6 Changes to index.html updateplace so the time is kept consistent with using Name= on the URL.
• Version 6.5 corrections to index.html for time zones E of Greenwich.
  • Always display value of zone as positive, E/W flag shows sign.
  • Correct time differences for negative values.
• Version 6.4 mainly changes in index.html.
  • In reset1 added support for location name as parameter.
  • Removed onload from <head> as reset1 called later.
  • Added some missing convertra calls (following rewrite1).
  • Removed duplicate entry for Cheltenham in observer.js.
• Corrected some HTML in index.html to validate as 4.01 transitional.
• Version 6.3 corrections to time string routines in util.js
• Version 6.2 corrections to index.html
  • In function reset1 correct month to observer.month twice.
• Version 6.1 corrections to index.html and util.js
  • In function updatelocal check for a change to the timezone W/E option.
  • In function reset1 set the daylight saving flag correctly for all cases.
  • In function hmsstring correct a typo in the rounding code.
• Version 6.0 - major changes to display time zone and daylight saving time differently.
  The underlying code still uses a DST adjusted time zone. Changes in index.html
  • Change table1 replacing UTC-Civil Time with Time Zone and a DST button, and move UTC-Civil Time to a dropdown menu.
  • Changes to functions clockhandler, updatelocal, updateplace and reset1, for DST.
  • Changes to reset1 so the default time is done better.
  • Lots of changes to rewrite1 to support the changes.
• Version 5.5 - changes to index.html, util.js and observer.js
  • 'local time' is now UTC corrected for longitude WITHOUT any daylight saving. This is because of problems with 'unknown' locations.
  • Made a daylight saving correction to reset1.
  • Added Muskegon
• Version 5.4
  • Corrected minor bug in full month tables if the date is after a daylight saving change.
  • Updated the copyright notices.
• Version 5.3
  • Added check for moon up or down all day when neither rise or set found.
  • Fixed a silly bug in moon.js that missed a did not set during the day.
• Version 5.2
  • Change in index.html so the default is Greenwich CIVIL time with any daylight saving correction not UTC. This is purely a personal choice and people who make copies defaulting to other locations may wish to remove it. It is clearly marked in the source.
• Version 5.1
  • Corrected the location of Madrid and Malaga (West not East) and time zone for Anchorage in observer.js
• Version 5.0 (not really as major a change as version 3 to 4 was)
  • Corrections fromOle Nielsen in moon.js and planets.js for small terms to the obliquity of the ecliptic.
• Version 4.9 -
  • Changes to index.html to default to the current date and time at Greenwich and make the time differences more consistent.
• Version 4.8 -
  • Add support for a monthly table in planets.js
  • Add support for a monthly table in moon.js
  • Changes to sun.js
    • Add support for a monthly table.
    • Correction for repeats if they cross the daylight saving change.
  • Add the monthly buttons to index.html
• Version 4.7
  • Added default.css, the same style sheet as for my home page.
  • Correction fromOle Nielsen in planet.js to use the right refraction correction and more places in observer.js.
• Version 4.6 - Corrections from Dean Davis in moon.js
  • Correct my transcription of table T45BL
  • Correct my error in understanding the corrections for the eccentricity of the Earth's orbit.
  • Revised equations for Moons mean elongation and anomaly from Meeus second edition.
• Version 4.5 - In index.html
  • Add noon button for the solar observers.
  • Add table headers and change some button names.
  • Change the introductory documentation for button changes.
• Version 4.4 - In index.html and notes.html
  • change RTC button to Local Date/Time
  • commented out the reset button (and for a short time the time zone but restored that).
  • updated the documentation
• Version 4.3 - Changes to most files
  • Alter sun.js to create a sunrise routine
  • Ensure for loop variables are declared with var, this to prevent possible subtle bugs (yes I created one in doing the sunrise routine).
• Version 4.2 - Changes to index.html and datetime.js
  • Allow input of Julian date (based on code from Nick Reid).
  • Correct a possible 1 second error in time input.
• Version 4.1
  • Fixed a bug in planets.js due to changed order for repeated planets and tidied up the source in the same file.
• Version 4.0
  • Split the source into different files.
  • Fix in index.html for time differences near midnight.
  • Added other cities and towns to observer.js.
  • Changed order for repeated planets.
• Version 3.7
  • Fixed silly error with angular separation output.
  • Added equation of time.
  • Corrected Amsterdam location.
  • Include daylight saving adjustment in local time.
  • Made the table more compact by adding selection options for UTC, local and siderial time and the time differences.
• Version 3.6
  • Improved checking for crossing saving time changes.
  • Added local time and changed original local to civil time.
  • Change the initial setup of date, time and timezone.
  • Added the zone button and changed RTC.
• Version 3.5
  • Angular separations based on code from Stephane Macrez.
  • Alt/Az to RA/Dec code from Nick Reid.
  • Midnight button and more freedom inputting times not just hh:mm:ss but hh:mm or hh.
  • Check for daylight saving time changes after date input.
  • Allow for leap years in daylight saving and repeated tables. The astronomical calculations were always right.
  • Add latitude and longitude after location name to top of pages.
  • Express time zone as hours:minutes as most people know them that way.
• Version 3.4
  • output bright stars altitude & azimuth in degrees & minutes.
  • fixed bug for 'unknown' location date / time
  • fixed a bug in repeat code & allow user to specify date / time
• Version 3.3
  • Additions based on code from Stephane Macrez.
    
    • bright stars
    • RA/Dec to Alt/Az converter.
    • French locations, I only used a few places though.
  • Changed from monthly tables to repeat at user specified time, interval and repetition count.
• Version 3.2 Added monthly Sun and Moon tables.
• Version 3.1 Daylight saving bug fixes and cosmetic changes to source.
• Version 3.0 First attempts to handle daylight saving time.
• Version 2.9
  • Round to 24 hour clock for sunrise/set even if next day
  • Fix HTML errors shown by Netscape 6
  • Added the Default button and changed RTC to use Time Zone.
  • Added the moon phase angle as well as % illuminated.
• Version 2.8 Move the notes sections to a new page
• Version 2.7 Changes removed for version 3.3
• Version 2.6 Fix a silly bug in the moon rise /set calculations
• Version 2.5 Try to speed up moon rise / set calculations
• Version 2.4 Added the illuminated fraction of the moon.
• Version 2.3 corrected a Sun rise/set bug at the equinox.
• Version 2.2
  • Corrected moon azimuth/elevation bug
    
  • Used the full Meeus table 45 (see notes for credits)
• Version 2.1 Added references to other JavaScript authors in the notes.
• Version 2.0 First release to the world of the internet

• ephemeris.html Defines the front page and the table that drives everything else.
• default.css The style sheet I use.
• observer.js Defines the observers places and functions that define them.

  The atlas array defines the list of places. The code uses the first entry as the default location. Add any others you need. The place function defines how to describe other towns.

  function place(name,latitude,ns,longitude,we,zone,dss,dse)

  • latitude is degrees:minutes:seconds, ns is 0 for north and 1 for south
  • longitude is degrees:minutes:seconds, we is 0 for west and 1 for east
  • zone is the correction in minutes from local time to UT (Greenwich time) without daylight saving, west of Greenwich is positive. This is shown in the table as hours:minutes.
  • The daylight saving start and end (dss and dse) are strings month:week:day where month is 1:12, day is 0-6 (0=Sunday) and week is 1-5. week 1 is the first week containing 'day' and week 5 means the last occurence of day in the month (same as the Unix TZ rules). Set the string to a null string if you don't know the rules. WARNING the code to try to work out daylight saving is simple minded, it will probably get it wrong about the hour of the change.

  function observatory(dt,latitude,longitude)

  • dt is a javascript date object
  • latitude is in degrees, north is positive
  • longitude is in degrees, west is positive
  • values contained within observatory object
    • year
    • month values in range 1-12
    • day
    • hours
    • minutes
    • seconds
    • tz timezone in minutes with any daylight saving (summer time) correction. See place above.
    • latitude
    • longitude

• datetime.js Calendar and sidereal time functions.
• sun.js The functions that define the suns position and heliocentric co-ordinates and creates the Sun page.
• moon.js The functions that define the moons position and creates the moon page.
• planets.js The planet functions.
• stars.js The functions for the bright stars table.
• separation.js The functions for the angular separation table.
• math.js Math functions in degrees.
• util.js Utility routines for printing dates times etc.

Links to Translations and other sites

US Naval Observatory
heavens-above a site for all sorts of astronomical tables and diagrams.

For those who want skymaps on your own computer I have used and recommend Stellarium free for Mac OS X, Linux and Windows.
A graphical view of ephemeris data can be found at AstroTools
If you want sun and moon data with a map to set your location try The Photographers Ephemeris
El Astronomo Errante has an Ephemeris page in Spanish.

This web page was last updated 04/05/16