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.

>>> 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 formulae are from Mallama and Hilton “Computing Apparent Planetary Magnitude for the Astronomical Almanac” (2018). Two of the formulae have inherent limits:

• Saturn’s magnitude is unknown and the function will return nan (the floating-point value “Not a Number”) if the “illumination phase angle” — the angle of the vertex observer-Saturn-Sun — exceeds 6.5°.
• Neptune’s magnitude is unknown and will return nan if the illumination phase angle exceeds 1.9° and the position’s date is before the year 2000.

And one formula is not fully implemented (though contributions are welcome!):

• Skyfield does not compute which features on Mars are facing the observer, which can introduce an error of ±0.06 magnitude.

Planetary reference frames¶

Almanac¶

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

Geographic locations¶

Skyfield supports two Earth datums for translating between latitude/longitude and Cartesian coordinates. They each use a slightly different estimate of the Earth’s oblateness. The most popular is WGS84, which is used by the world’s GPS devices:

• wgs84
• iers2010

Each datum offers a method for taking a latitude and longitude and returning a GeographicPosition that knows its position in space:

Going in the other direction, there are several methods for converting an existing Skyfield position into latitude, longitude, and height:

Once you have used either of the above approaches to build a GeographicPosition, it offers several methods:

Kepler orbits¶

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

Kepler orbit data¶

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) .xyz 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.

You can also generate a position at the Solar System Barycenter.

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:

The .xyz attribute used to be named .position. To support older code, Skyfield will always recognize the original name as an alias.

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¶