Skyfield: HomeTable of ContentsChangelogAPI Reference

API Reference — Topocentric Locations

skyfield.toposlib.wgs84 = <skyfield.toposlib.Geoid object>

World Geodetic System 1984 Geoid.

This is the standard geoid used by the GPS system, and is likely the standard that’s intended if you are supplied a latitude and longitude that don’t specify an alternative geoid.

skyfield.toposlib.iers2010 = <skyfield.toposlib.Geoid object>

International Earth Rotation Service 2010 Geoid.

class skyfield.toposlib.Geoid(name, radius_m, inverse_flattening)

An Earth ellipsoid; maps latitudes and longitudes to x,y,z positions.

latlon(latitude_degrees, longitude_degrees, elevation_m=0.0, cls=<class 'skyfield.toposlib.GeographicPosition'>)

Return the geographic position of a given latitude and longitude.

Longitude is positive towards the east, so supply a negative number for west:

from skyfield.api import wgs84
observatory = wgs84.latlon(37.3414, -121.6429)

You can avoid remembering which directions are negative by using Skyfield’s compass direction constants, which have the values +1 and −1:

from skyfield.api import N, S, E, W
observatory = wgs84.latlon(37.3414 * N, 121.6429 * W)

Return Earth latitude and longitude beneath a celestial position.

The input position should have a center of 399, the geocenter. The return value is a GeographicPosition whose latitude and longitude are the spot on the Earth’s surface directly beneath the given position, and whose elevation is the position’s distance above (or depth below) mean sea level.

The underlying computation is based on Dr. T.S. Kelso’s quite helpful article Orbital Coordinate Systems, Part III.

class skyfield.toposlib.GeographicPosition(model, latitude, longitude, elevation, itrs_xyz)

The position of a latitude and longitude on Earth.

Each instance of this class holds an x,y,z vector for a geographic position on (or above, or below) the Earth’s surface, in the ITRS reference frame: the international standard for an Earth-centered Earth-fixed (ECEF) reference frame. Instead of instantiating this class directly, Skyfield users usually give a reference geoid the longitude and latitude they are interested in:

from skyfield.api import wgs84
topos = wgs84.latlon(37.3414, -121.6429)

Once a geographic position has been created, here are its attributes and methods:


An Angle object specifying the latitude of the topocentric position.


An Angle object specifying the longitude of the topocentric position.


A Distance object specifying the elevation of the topocentric position above mean sea level on a WGS-84 globe.


A Distance object giving the spatial x,y,z coordinates of this location in the ITRS Earth-centered Earth-fixed (“ECEF”) reference frame.


The integer 399, which identifies this topocentric position’s vector as having its origin at the center of the Earth.


Return the position of this Earth location at time t.


Return this position’s Local Sidereal Time in hours at time t.

refract(altitude_degrees, temperature_C, pressure_mbar)

Predict how the atmosphere will refract a position.

Given a body that is standing altitude_degrees above the true horizon, return an Angle predicting its apparent altitude given the supplied temperature and pressure, either of which can be the string 'standard' to use 10°C and a pressure of 1010 mbar adjusted for the elevation of this geographic location.


Compute rotation from GCRS to this location’s altazimuth system.