API Reference¶

Opening files¶

# File you already have.

from skyfield.api import load_file
planets = load_file('~/Downloads/de405.bsp')

# File you want Skyfield to download automatically.

from skyfield.api import load
ts = load.timescale()
planets = load('de405.bsp')

Time scales¶

A Skyfield Timescale object is typically built at the beginning of each program:

from skyfield import api
ts = api.load.timescale()

It downloads and parses the data tables necessary to correctly convert between Universal Time and the more stable time scales used by astronomers.

If you want to skip downloading up-to-date time scale files, you can run:

ts = api.load.timescale(builtin=True)

This can avoid problems connecting to the servers from which the official files are distributed. Note that the time scale files distributed with any given version of Skyfield will fall gradually out of date.

Time objects¶

The Time class is Skyfield’s way of representing either a single time, or a whole array of times. Each object has four floating point attributes that present the time in several basic time scales.

A couple of offsets between time scales are also available.

Other time scales and conversions are available through its methods.

Vector Functions¶

The common API shared by planets, Earth locations, and Earth satellites.

Planetary Ephemerides¶

By downloading a SpiceKernel file, Skyfield users can build vector functions predicting the positions of the Moon, Sun, and planets.

Almanac¶

Routines to search for events like sunrise, sunset, and Moon phase.

Topocentric Locations¶

You can create a vector function that computes the location of any position on the Earth’s surface.

Earth Satellites¶

By downloading TLE satellite element sets, Skyfield users can build vector functions that predict their positions.

Stars and other distant objects¶

Astronomical positions¶

The ICRF three-dimensional position vector serves as the base class for all of the following position classes. Each class represents an (x,y,z) .position and .velocity in the International Terrestrial Reference Frame (ITRF), an inertial system that is an update to J2000 and that does not rotate with the Earth itself.

Positions are usually generated by the at(t) method of a vector function, rather than being constructed manually. But you can also build a position directly from a raw vector, or from right ascension and declination coordinates with skyfield.positionlib.position_from_radec().

Position methods and attributes¶

All position objects have three attributes which provide access to their raw data:

If a position lacks a velocity, then the attribute is simply the value None.

All positions support a basic set of methods:

Position methods specific to one class¶

Constellations¶

skyfield.api.load_constellation_map()¶

Load Skyfield’s constellation map and return a lookup function

Skyfield carries an internal constellation map that is optimized for quick position lookup. Call this function to load the map and return a function mapping position to constellation name.

>>> from skyfield.api import position_from_radec, load_constellation_map
>>> constellation_at = load_constellation_map()
>>> north_pole = position_from_radec(0, 90)
>>> constellation_at(north_pole)
'UMi'

If you pass an array of positions, you’ll receive an array of names.

Osculating Orbital Elements¶

This routine returns osculating orbital elements for an object’s instantaneous position and velocity.

Units¶

All three kinds of quantity support one or more methods.