Skip Navigation

Horizons System

Horizons Tutorial

This page provides a brief description of how to use the web-interface to the Horizons system and gives an illustrative example of generating a topocentric ephemeris. If you are using the telnet or E-mail interface to Horizons, you should consult the Horizons documentation instead. An API is also available.

How to Generate an Ephemeris

The top-level form displays the current settings to be used in generating an ephemeris. The first time the form is displayed, default values are shown. To change the “Ephemeris Type”, simply select the desired type from the dropdown menu. To change an other setting, simply use the associated “EDIT” button. When an “EDIT” button is selected, a modal dialog will open providing forms allowing you to modify that particular item’s settings. Each setting item (1-5) is described the following sections. Once you have specified the desired settings, simply press the “Generate Ephemeris” button.

Horizons Main Interface

If after examining your ephemeris you would like to change any settings, simply use the “EDIT” button to make the desired changes and then generate a new ephemeris. Once you have the desired ephemeris, you can download it as a plain-text file using the “Download Results” button at the bottom of the resulting ephemeris panel.

1. Select the Ephemeris Type

There are three possible types of ephemerides available from the Horizons system. Most users will be interested in the “Observer Table” ephemeris which provides quantities (such as right ascension and declination) useful in observing solar system bodies. Tables of Cartesian vectors (e.g. xyz coordinates in a specific reference frame) are available using the “Vector Table” type. The third option provides a table of osculating orbital elements, selected using the “Orbital Elements” type.

2. Select a Target Body

To select a different body, use the “EDIT” button in the “Target Body” item “2” section. The resulting modal dialog provides different forms corresponding to the selected method for specifying the target body. The method is selected using the top dropdown menu which, by default, is “Search for a Specified Body”. Each method is described below.

Search for a Specified Body

This method is generally the most common and convenient. It provides a search form into which you can specify the name, designation, or ID of the desired target body. In the event your input matches more than one body, a list is presented from which you can select the desired body. For example, to select the asteroid 4 Vesta as the target body, simply enter “vesta” or “4”.

Select from a List of Major Bodies

This method provides lists of all major bodies available in Horizons grouped by category. Simply select the appropriate category and then select the body of interest.

Specify a target using TLEs

This method is typically used to select an Earth-orbiting spacecraft for which TLEs (two-line elements) are available but is not provided by Horizons directly.

Specify Small-Body using Elements

This method is typically used to provide a means of specifying a small-body (asteroid or comet) that is currently not available via Horizons. The related form allows input of osculating orbital elements for the small-body of interest.

3. Specify an Observer Location (or Coordinate Center)

The label for setting number 3 is “Observer Location” for the “Observer Table” ephemeris type of “Coordinate Center” for the other ephemeris types. We’ll use the term “location” to mean either “observer location” or “coordinate center”. To select a different location, use the “EDIT” button in section 3. The resulting modal dialog provides different forms corresponding to the selected method for specifying the location. The method is selected using the top dropdown menu which, by default, is “Search for a Location”. Each method is described below.

Search for a Location

This method is generally the most common and convenient. It provides a search form into which you can specify the name or code of the desired location. In the event your input matches more than one body, a list is presented from which you can select the desired location. For example, to select the Palomar observatory, enter its code “675”. Additional examples are provided on this form. See the Horizons documetation for more details.

Select from a list of Earth Locations

This method provides lists of cites and observatories from which you can select the most appropriate location. The top-most pulldown menu under this method is “Type” from which you can choose “Word Cities”, “Observatories”, or “Radar Observatories”.

World Cities

Under this “Type”, you can select the “City Group” of interest. Choose “U.S. cities by state (which also provides a pulldown menu for select the state of interest), “U.S. cities” (shows all available cities in the U.S.), “non-U.S. cities” (show all available cities outside the U.S.), or “all cities” (to show all available cities). Note that not all cities are provided. For most causul observer ephemerides, the precise observer location is not required. In fact for many cases, a geocentric ephemeris (the default) is sufficient.

Observatories

This list shows all observatories with a 3-character code assigned by the Minor Planet Center, sorted aphabetically.

Radar Observatories

This list, sorted alphabetically by name, includes both observatories with JPL codes (e.g., Green Bank, code -9) and without codes. Our use of the term “Radar Observatory” includes passive (non-transmitting) radio observing.

Specify Coordinates

This method provides a means of specifying arbitrary coordinates on the Earth or other major solar-system bodies. Either geodetic/planetodetic or cylindrical coordinates can be specified. For most users specifying a coordinates on the Earth, geodetic coordinates (longitude, latitude, and altitude) are appropriate.

To specify coordinates on a body other than Earth, use the “Change” button to specify the body before entering the coordinates. See the Horizons documetation for more details.

Specify using TLEs

This method is only useful in special cases where the location must be set to an Earth-orbiting spacecraft not already available to Horizons as a major body. In such cases, the appropriate Two-Line Elements (TLEs) can be specified. More details are available in the Horizons documentation.

4. Specify Time

The output time span of the requested ephemeris can be specified using a start/stop time with some interval or as a set of discrete times.

Specify Time Span

This the most common method of specifying output times. Simply enter a start time in an appropriate format (e.g., 2020-01-10 for January 1, 2020), a stop time, and a step size. For details on acceptable date/time formats, see the Horizons documentation.

For convenience, there are three “preset” buttons available which when pressed will set the start time to the current day (UT) and the stop time 10, 30, or 60 days later.

Specify List of Times

This method is most useful in cases where you want the ephemeris at one specific time (or a few specific times). You can enter up to 15 specific times. The order is not important since they are always output chronologically.

5. Table Settings

The available table settings are dependent on the “Ephemeris Type” selected (see step 1. above). The Horizons documentation provides addition details. The following sections describe settings for each type of ephemeris.

Observer Table Settings

The first section of the settings dialog allows for the selection of desired observer quantities. Each quantity can be select using the adjacent checkbox. There are also “preset” buttons (e.g., “planets”) that select associated default quantities. More information on each available observer quantity is provided in the Horizons documentation.

The next section of the dialog (“Additional Table Settings”) provides a form for several settings used to customize the ephemeris for your particular needs. For example, most optical observers will want to select the “skip daylight” checkbox to limit output to only when the sun is down. The question-mark symbol after each setting label can be clicked (or pressed) to get a short description for that particular setting.

Vector Table Settings

The first section of the settings dialog provides a pulldown menu (“Select Output Quantities”) for selecting the desired vector table output quantities. If output quantities 1 or 2 is selected, statistical uncertainties (only for small bodies) can requested using the appropriate checkboxes.

The last section (“Additional Table Settings”) provides a form for several settings used to customize the ephemeris for your particular needs. For example, choosing the desired units for your vector quantities. The question-mark symbol after each setting label can be clicked (or pressed) to get a short description for that particular setting.

Orbital Elements Settings

There are only a few settings available for customizing the output of the orbital elements ephemeris. For example, choosing the desired units for the set of elements. The question-mark symbol after each setting label can be clicked (or pressed) to get a short description for that particular setting.

Ephemeris Results

After using the “Generate Ephemeris” button, if the Horizons engine encounters any errors, they will be output in a red box. Usually, such errors are due to invalid/inconsistent settings and the error message should give some clue about what needs to be changed.

Assuming no errors were detected, the requested ephemeris will be displayed below in a panel labeled “Ephemeris Results”. You will also notice the “Generate Ephemeris” button becomes disabled to prevent inadvertent additional requests for the identical ephemeris. The button will become enabled as soon as any setting is changed or when the “Delete” button is used.

If you want to download the ephemeris results, use the “Download Results” button found at very bottom of the results panel.

Saved Settings and Defaults

Using the “Save/Load Settings…” button at the top of the page opens a dialog from which you can save your current settings in your web-browser’s local storage. These settings will be available to you only from that same web-browser (i.e., they are stored on the client and not the server). Previously-saved settings can similarly be loaded using the dialog.

If at any time you want to reset all settings to their defaults, simply use the “Set Defaults” button on the top/right area of the application.

Batch Data

There are many use-cases where a programatic batch-style interface to Horizons is far more convenient that an interactive interface. Two such interface modes are available: email and API. When getting started with these interfaces, it can be helpful to see the batch input file used to generate the ephemeris from this web-interface for a specific settings. This can be done by using the link show in the text below the settings controls and above the “Generate Ephemeris” button.


An Illustrative Example

Suppose you want to generate a topocentric observer ephemeris for comet 76P/West-Kohoutek-Ikemura for use at Kitt Peak from 1998 July 28 00:00 to 1998 July 30 00:00 (UT) at 1 hour intervals only when the comet is above the horizon and the sun is down. Here is what you should do.

If you followed the above example, you should get an ephemeris that looks something like this:

Ephemeris Results

*******************************************************************************
JPL/HORIZONS              76P/West-Kohoutek-Ikemura        2021-Mar-10 14:37:08
Rec #:90000811 (+COV) Soln.date: 2020-Aug-26_18:24:46   # obs: 1070 (1993-2020)
 
IAU76/J2000 helio. ecliptic osc. elements (au, days, deg., period=Julian yrs):
 
  EPOCH=  2455411.5 ! 2010-Aug-03.0000000 (TDB)    RMSW= n.a.
   EC= .5381593146648882   QR= 1.603229390694079   TP= 2456420.8454873632
   OM= 84.10847622986566   W= .05152338958200969   IN= 30.46740501321082
   A= 3.471390550035182    MA= 206.1885365594786   ADIST= 5.339551709376284
   PER= 6.4679019806099    N= .152387325           ANGMOM= .027013443
   DAN= 1.60323            DDN= 5.33955            L= 84.1528852
   B= .0261248             MOID= .61874902         TP= 2013-May-08.3454873632
 
Comet physical (GM= km^3/s^2; RAD= km):
   GM= n.a.                RAD= .330
   M1=  14.8     M2=  17.2     k1=  12.25  k2=  5.      PHCOF=  .030
 
Comet non-gravitational force model (AMRAT=m^2/kg;A1-A3=au/d^2;DT=days;R0=au):
   AMRAT=  0.                                      DT=  0.
   A1= 4.491002112627E-10  A2= -1.68660543859E-10  A3= 0.
 Standard model:
   ALN=  .1112620426   NK=  4.6142   NM=  2.15     NN=  5.093    R0=  2.808
 
COMET comments 
1: soln ref.= JPL#K195/6, data arc: 1993-07-20 to 2020-03-23
2: k1=12.25, k2=5., phase coef.=0.03;
*******************************************************************************


*******************************************************************************
Ephemeris / WWW_USER Wed Mar 10 14:37:08 2021 Pasadena, USA      / Horizons    
*******************************************************************************
Target body name: 76P/West-Kohoutek-Ikemura       {source: JPL#K195/6}
Center body name: Earth (399)                     {source: DE431}
Center-site name: Kitt Peak
*******************************************************************************
Start time      : A.D. 1998-Jul-28 00:00:00.0000 UT      
Stop  time      : A.D. 1998-Jul-30 00:00:00.0000 UT      
Step-size       : 60 minutes
*******************************************************************************
Target pole/equ : No model available
Target radii    : 0.3 km                                                       
Center geodetic : 248.405300,31.9584502,2.0709438 {E-lon(deg),Lat(deg),Alt(km)}
Center cylindric: 248.405300,5418.25536,3357.6195 {E-lon(deg),Dxy(km),Dz(km)}
Center pole/equ : High-precision EOP model        {East-longitude positive}
Center radii    : 6378.1 x 6378.1 x 6356.8 km     {Equator, meridian, pole}    
Target primary  : Sun
Vis. interferer : MOON (R_eq= 1737.400) km        {source: DE431}
Rel. light bend : Sun, EARTH                      {source: DE431}
Rel. lght bnd GM: 1.3271E+11, 3.9860E+05 km^3/s^2                              
Small-body perts: Yes                             {source: SB431-N16}
Atmos refraction: NO (AIRLESS)
RA format       : HMS
Time format     : CAL 
EOP file        : eop.210309.p210531                                           
EOP coverage    : DATA-BASED 1962-JAN-20 TO 2021-MAR-09. PREDICTS-> 2021-MAY-30
Units conversion: 1 au= 149597870.700 km, c= 299792.458 km/s, 1 day= 86400.0 s 
Table cut-offs 1: Elevation (-90.0deg=NO ),Airmass (>38.000=NO), Daylight (YES)
Table cut-offs 2: Solar elongation (  0.0,180.0=NO ),Local Hour Angle( 0.0=NO )
Table cut-offs 3: RA/DEC angular rate (     0.0=NO )                           
*******************************************************************************
Initial IAU76/J2000 heliocentric ecliptic osculating elements (au, days, deg.):
  EPOCH=  2455411.5 ! 2010-Aug-03.0000000 (TDB)    RMSW= n.a.                  
   EC= .5381593146648882   QR= 1.603229390694079   TP= 2456420.8454873632      
   OM= 84.10847622986566   W= .05152338958200969   IN= 30.46740501321082       
  Equivalent ICRF heliocentric equatorial cartesian coordinates (au, au/d):
   X= 2.099877624435176E-01  Y=-4.627735548908017E+00  Z=-2.484792399940155E+00
  VX= 4.393914137779511E-03 VY= 2.233200421207845E-03 VZ=-1.745071100342748E-03
Comet physical (GM= km^3/s^2; RAD= km):                                        
   GM= n.a.                RAD= .330                                           
   M1=  14.8     M2=  17.2     k1=  12.25  k2=  5.      PHCOF=  .030           
Comet non-gravitational force model (AMRAT=m^2/kg;A1-A3=au/d^2;DT=days;R0=au): 
   AMRAT=  0.                                      DT=  0.                     
   A1= 4.491002112627E-10  A2= -1.68660543859E-10  A3= 0.                      
 Standard model:                                                               
   ALN=  .1112620426   NK=  4.6142   NM=  2.15     NN=  5.093    R0=  2.808    
****************************************************************************************************************
 Date__(UT)__HR:MN     R.A._____(ICRF)_____DEC   T-mag   N-mag            delta      deldot    S-O-T /r    S-T-O
****************************************************************************************************************
$$SOE

>..... Daylight Cut-off Requested .....<

 1998-Jul-28 03:00 Nm  19 24 54.92 -40 56 30.7  25.747  23.504 3.66921948551934   3.1540756 154.1868 /T   5.5081
 1998-Jul-28 04:00 Am  19 24 52.65 -40 56 37.8  25.747  23.504 3.66929627057339   3.2298186 154.1538 /T   5.5148
 1998-Jul-28 05:00  m  19 24 50.38 -40 56 44.7  25.747  23.505 3.66937503574960   3.3179246 154.1207 /T   5.5216
 1998-Jul-28 06:00     19 24 48.10 -40 56 51.6  25.747  23.505 3.66945602383104   3.4137287 154.0875 /T   5.5283
 1998-Jul-28 07:00     19 24 45.83 -40 56 58.4  25.747  23.505 3.66953935829056   3.5120372 154.0544 /T   5.5351
 1998-Jul-28 08:00     19 24 43.55 -40 57 05.1  25.747  23.505 3.66962503481358   3.6074847 154.0213 /T   5.5418
 1998-Jul-28 09:00     19 24 41.28 -40 57 11.7  25.746  23.505 3.66971292158853   3.6949016 153.9882 /T   5.5485
 1998-Jul-28 10:00     19 24 39.02 -40 57 18.2  25.746  23.506 3.66980276834442   3.7696692 153.9551 /T   5.5552
 1998-Jul-28 11:00     19 24 36.77 -40 57 24.6  25.746  23.506 3.66989422351484   3.8280361 153.9221 /T   5.5619
 1998-Jul-28 12:00 N   19 24 34.53 -40 57 31.0  25.746  23.506 3.66998685835022   3.8673761 153.8892 /T   5.5685

>..... Daylight Cut-off Requested .....<

 1998-Jul-29 03:00 Nm  19 24 01.53 -40 59 11.1  25.745  23.509 3.67131606261191   3.6388925 153.3930 /T   5.6688
 1998-Jul-29 04:00  m  19 23 59.28 -40 59 17.8  25.745  23.509 3.67140452642148   3.7155500 153.3591 /T   5.6757
 1998-Jul-29 05:00  m  19 23 57.02 -40 59 24.5  25.745  23.509 3.67149498821703   3.8042153 153.3252 /T   5.6826
 1998-Jul-29 06:00     19 23 54.76 -40 59 31.1  25.745  23.509 3.67158768155494   3.9001716 153.2911 /T   5.6895
 1998-Jul-29 07:00     19 23 52.50 -40 59 37.6  25.744  23.510 3.67168271977086   3.9982017 153.2571 /T   5.6964
 1998-Jul-29 08:00     19 23 50.24 -40 59 43.9  25.744  23.510 3.67178008819725   4.0929459 153.2231 /T   5.7032
 1998-Jul-29 09:00     19 23 47.99 -40 59 50.2  25.744  23.510 3.67187964516312   4.1792697 153.1891 /T   5.7101
 1998-Jul-29 10:00     19 23 45.75 -40 59 56.4  25.744  23.510 3.67198113170702   4.2526159 153.1552 /T   5.7169
 1998-Jul-29 11:00     19 23 43.51 -41 00 02.5  25.744  23.510 3.67208418933620   4.3093174 153.1213 /T   5.7237
 1998-Jul-29 12:00 N   19 23 41.29 -41 00 08.6  25.744  23.511 3.67218838461281   4.3468486 153.0875 /T   5.7305

>..... Daylight Cut-off Requested .....<

$$EOE
****************************************************************************************************************
Column meaning:
 
TIME

  Times PRIOR to 1962 are UT1, a mean-solar time closely related to the
prior but now-deprecated GMT. Times AFTER 1962 are in UTC, the current
civil or "wall-clock" time-scale. UTC is kept within 0.9 seconds of UT1
using integer leap-seconds for 1972 and later years.

  Conversion from the internal Barycentric Dynamical Time (TDB) of solar
system dynamics to the non-uniform civil UT time-scale requested for output
has not been determined for UTC times after the next July or January 1st.
Therefore, the last known leap-second is used as a constant over future
intervals.

  Time tags refer to the UT time-scale conversion from TDB on Earth
regardless of observer location within the solar system, although clock
rates may differ due to the local gravity field and no analog to "UT"
may be defined for that location.

  Any 'b' symbol in the 1st-column denotes a B.C. date. First-column blank
(" ") denotes an A.D. date. Calendar dates prior to 1582-Oct-15 are in the
Julian calendar system. Later calendar dates are in the Gregorian system.

  NOTE: "n.a." in output means quantity "not available" at the print-time.
 
SOLAR PRESENCE (OBSERVING SITE)
  Time tag is followed by a blank, then a solar-presence symbol:

        '*'  Daylight (refracted solar upper-limb on or above apparent horizon)
        'C'  Civil twilight/dawn
        'N'  Nautical twilight/dawn
        'A'  Astronomical twilight/dawn
        ' '  Night OR geocentric ephemeris

LUNAR PRESENCE (OBSERVING SITE)
  The solar-presence symbol is immediately followed by a lunar-presence symbol:

        'm'  Refracted upper-limb of Moon on or above apparent horizon
        ' '  Refracted upper-limb of Moon below apparent horizon OR geocentric
             ephemeris
 
 '' =
  Astrometric right ascension and declination of the target center with
respect to the observing site (coordinate origin) in the reference frame of
the planetary ephemeris (ICRF). Compensated for down-leg light-time delay
aberration.

  Units: RA  in hours-minutes-seconds of time,    HH MM SS.ff{ffff}
         DEC in degrees-minutes-seconds of arc,  sDD MN SC.f{ffff}
 
 '' =
   Comets' apparent visual total magnitude ("T-mag") and nuclear magnitude
("N-mag") using the standard IAU model:

   T-mag= M1 + 5*log10(delta) + k1*log10(r)
   N-mag= M2 + 5*log10(delta) + k2*log10(r) + phcof*beta

   Units: MAGNITUDES
 
 '' =
   Apparent range ("delta", light-time aberrated) and range-rate ("delta-dot")
of the target center relative to the observer. A positive "deldot" means the
target center is moving away from the observer, negative indicates movement
toward the observer.  Units: AU and KM/S
 
 'S-O-T /r' =
   Sun-Observer-Target apparent SOLAR ELONGATION ANGLE seen from the observers'
location at print-time.

   The '/r' column provides a code indicating the targets' apparent position
relative to the Sun in the observers' sky, as described below:

   Case A: For an observing location on the surface of a rotating body, that
body rotational sense is considered:

    /T indicates target TRAILS Sun   (evening sky: rises and sets AFTER Sun)
    /L indicates target LEADS Sun    (morning sky: rises and sets BEFORE Sun)

   Case B: For an observing point that does not have a rotational model (such
as a spacecraft), the "leading" and "trailing" condition is defined by the
observers' heliocentric ORBITAL motion:

    * If continuing in the observers' current direction of heliocentric
       motion would encounter the targets' apparent longitude first, followed
       by the Sun's, the target LEADS the Sun as seen by the observer.

    * If the Sun's apparent longitude would be encountered first, followed
       by the targets', the target TRAILS the Sun.

   Two other codes can be output:
    /* indicates observer is Sun-centered    (undefined)
    /? Target is aligned with Sun center     (no lead or trail)

   The S-O-T solar elongation angle is numerically the minimum separation
angle of the Sun and target in the sky in any direction. It does NOT indicate
the amount of separation in the leading or trailing directions, which would
be defined along the equator of a spherical coordinate system.

   Units: DEGREES
 
 '' =
   The Sun-Target-Observer angle; the interior vertex angle at target center
formed by a vector from the target to the apparent center of the Sun (at
reflection time on the target) and the apparent vector from target to the
observer at print-time. Slightly different from true PHASE ANGLE (requestable
separately) at the few arcsecond level in that it includes stellar aberration
on the down-leg from target to observer.  Units: DEGREES


 Computations by ...
     Solar System Dynamics Group, Horizons On-Line Ephemeris System
     4800 Oak Grove Drive, Jet Propulsion Laboratory
     Pasadena, CA  91109   USA
     Information  : https://ssd.jpl.nasa.gov/
     Documentation: https://ssd.jpl.nasa.gov/?horizons_doc
     Connect      : https://ssd.jpl.nasa.gov/?horizons (browser)
                    telnet ssd.jpl.nasa.gov 6775       (command-line)
                    e-mail command interface available
                    Script and CGI interfaces available
     Author       : Jon.D.Giorgini@jpl.nasa.gov

****************************************************************************************************************