API Reference¶

Version¶

Skyfield offers a tuple skyfield.VERSION that lets your code determine the installed version of Skyfield.

import skyfield
print(skyfield.VERSION)

See Checking your Skyfield version.

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 script will typically start by building a single Skyfield Timescale to use for all date and time conversions:

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

Its methods are:

Time objects¶

The Time class is Skyfield’s way of representing either a single time, or a whole array of times. The same time can be represented in several different time scales.

A couple of offsets between time scales are also available.

Other time scales and conversions are available through its methods.

Time utilities¶

Vector functions¶

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

Either adding two vector functions v1 + v2 or subtracting them v1 - v2 produces a new function of time that, when invoked with .at(t), returns the sum or difference of the vectors returned by the two functions.

Planetary ephemerides¶

By downloading a SpiceKernel file, Skyfield users can build vector functions predicting the positions of the Moon, Sun, and planets. See Planets and their moons: JPL ephemeris files.

Kernels also support lookup using the Python kernel['Mars'] syntax, in which case they return a function of time that returns vectors from the Solar System barycenter to the named body.

Planetary magnitudes¶

skyfield.magnitudelib.planetary_magnitude(position)¶

Given the position of a planet, return its visual magnitude.

This prototype function — which so far only supports Mercury, Venus, Earth, Jupiter, and Uranus — computes the visual magnitude of a planet, given its position relative to an observer.

>>> from skyfield.api import load
>>> from skyfield.magnitudelib import planetary_magnitude
>>> ts = load.timescale()
>>> t = ts.utc(2020, 7, 31)
>>> eph = load('de421.bsp')
>>> astrometric = eph['earth'].at(t).observe(eph['jupiter barycenter'])
>>> print('%.2f' % planetary_magnitude(astrometric))
-2.73

The routine does not yet take into account whether the observer is facing the equator or poles of Uranus, so will only be accurate to within about 0.1 magnitudes.

Planetary reference frames¶

Almanac¶

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

Topocentric locations¶

You can ask Skyfield to compute the position of any geographic location on the Earth’s surface. First, choose a reference model of the Earth’s exact shape (click either name to learn more about them):

• wgs84
• iers2010

Then, call one of the model’s methods to build an object representing a specific longitude and latitude. Both of the above models are instances of the Geoid class and offer these methods:

Finally, the resulting GeographicPosition can compute its position at any specified time, by combining its coordinates with the orientation of the Earth at that moment:

Kepler orbits¶

See Kepler Orbits for computing the positions of comets, asteroids, and other minor planets.

Earth satellites¶

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

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 vector oriented to the axes of the International Celestial Reference System (ICRS), an inertial system that’s an update to J2000 and that does not rotate with respect to the universe.

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 position_of_radec().

All position objects offer five basic attributes:

All positions support these methods:

In addition to the methods above, several subclasses of the base position class provide unique methods of their own:

Reference frames¶

Constellations¶

skyfield.api.load_constellation_map()¶

Load Skyfield’s constellation boundaries and return a lookup function.

Skyfield carries an internal map of constellation boundaries 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_of_radec, load_constellation_map
>>> constellation_at = load_constellation_map()
>>> north_pole = position_of_radec(0, 90)
>>> constellation_at(north_pole)
'UMi'

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

skyfield.api.load_constellation_names()¶

Return a list of abbreviation-name tuples, like ('Aql', 'Aquila').

You can pass the list to Python’s dict() to build a dictionary that turns a constellation abbreviation into a full name:

>>> from skyfield.api import load_constellation_names
>>> d = dict(load_constellation_names())
>>> d['UMa']
'Ursa Major'

By swapping the order of the two items, you can map the other way, from a full name back to an abbreviation:

>>> f = dict(reversed(item) for item in load_constellation_names())
>>> f['Ursa Major']
'UMa'

skyfield.data.stellarium.parse_constellations(lines)¶

Return a list of constellation outlines.

Each constellation outline is a list of edges, each of which is drawn between a pair of specific stars:

[
    (name, [(star1, star2), (star3, star4), ...]),
    (name, [(star1, star2), (star3, star4), ...]),
    ...
]

Each name is a 3-letter constellation abbreviation; each star is an integer Hipparcos catalog number. See Drawing a finder chart for comet NEOWISE for an example of how to combine this data with the Hipparcos star catalog to draw constellation lines on a chart.

skyfield.data.stellarium.parse_star_names(lines)¶

Return the names in a Stellarium star_names.fab file.

Returns a list of named tuples, each of which offers a .hip attribute with a Hipparcos catalog number and a .name attribute with the star name. Do not depend on the tuple having only length two; additional fields may be added in the future.

Searching¶

skyfield.searchlib.find_discrete()¶

Find the times at which a discrete function of time changes value.

This routine is used to find instantaneous events like sunrise, transits, and the seasons. See Searching for the dates of astronomical events for how to use it yourself.

skyfield.searchlib.find_maxima()¶

Find the local maxima in the values returned by a function of time.

This routine is used to find events like highest altitude and maximum elongation. See Searching for the dates of astronomical events for how to use it yourself.

skyfield.searchlib.find_minima()¶

Find the local minima in the values returned by a function of time.

This routine is used to find events like minimum elongation. See Searching for the dates of astronomical events for how to use it yourself.

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.

Trigonometry¶