# API Reference — Time

See the Dates and Time guide for a careful and detailed discussion of the several time scales used by astronomers, and of how you can convert time to and from familiar time scales like UTC and the worldwide time zones that are adapted from it.

## Calendar date

1. When building a `Time` from a calendar date, you can not only designate a single moment by its time and date, but you can also build a `Time` representing a whole array of moments by supplying a Python list or NumPy array for either the year, month, day, hour, minute, or second. See Date arrays.

2. By default, Skyfield uses the modern Gregorian calendar for all dates — even dates before the Gregorian calendar was introduced in 1582.

3. You can instead opt to use the old Julian calendar for ancient dates, which is the most common practice among historians. See Ancient and modern dates.

## Timescale, for building and converting times

class skyfield.timelib.Timescale(delta_t_recent, leap_dates, leap_offsets)

  The data necessary to express dates in different timescales.

  A `Timescale` provides time objects with the data tables they need to translate between different time scales: the schedule of UTC leap seconds, and the value of ∆T over time. Most programs create a single `Timescale` which they use to build their `Time` objects:

      >>> from skyfield.api import load
      >>> ts = load.timescale()
      >>> t = ts.utc(1980, 3, 1, 9, 30)
      >>> t
      <Time tt=2444299.896425741>

  See UT1 and downloading IERS data if you are interested in checking how recent the data is in the files loaded by the timescale.

  now()

    Return the current date and time as a `Time` object.

  from_datetime(datetime)

    Return a `Time` for a Python `datetime`.

    The `datetime` must be “timezone-aware”: it must have a time zone object as its `tzinfo` attribute instead of `None`.

    Added in version 1.24.

  from_datetimes(datetime_list)

    Return a `Time` for a list of Python `datetime` objects.

    The `datetime` objects must each be “timezone-aware”: they must each have a time zone object as their `tzinfo` attribute instead of `None`.

    Added in version 1.24.

  utc(year, month=1, day=1, hour=0, minute=0, second=0.0)

    Build a `Time` from a UTC Calendar date.

    Added in version 1.24: Passing a Python `datetime` or a list of datetimes as the first argument has been deprecated (and was never supported for the other time scale methods). Instead, use the methods `from_datetime()` and `from_datetimes()`.

  tai(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

    Build a `Time` from an International Atomic Time Calendar date.

    Added in version 1.6: Passing a Julian date with `jd=` has been deprecated; instead, use `tai_jd()`.

  tai_jd(jd, fraction=None)

    Build a `Time` from an International Atomic Time Julian date.

  tt(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

    Build a `Time` from a Terrestrial Time Calendar date.

    Added in version 1.6: Passing a Julian date with `jd=` has been deprecated; instead, use `tt_jd()`.

  tt_jd(jd, fraction=None)

    Build a `Time` from a Terrestrial Time Julian date.

  J(year)

    Build a `Time` from a Terrestrial Time Julian year or array.

    Julian years are convenient uniform periods of exactly 365.25 days of Terrestrial Time, centered on 2000 January 1 12h TT = Julian year 2000.0.

  tdb(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

    Build a `Time` from a Barycentric Dynamical Time Calendar date.

    Added in version 1.6: Passing a Julian date with `jd=` has been deprecated; instead, use `tdb_jd()`.

  tdb_jd(jd, fraction=None)

    Build a `Time` from a Barycentric Dynamical Time Julian date.

  ut1(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

    Build a `Time` from a UT1 Universal Time Calendar date.

    Added in version 1.6: Passing a Julian date with `jd=` has been deprecated; instead, use `ut1_jd()`.

  ut1_jd(jd)

    Build a `Time` from a UT1 Universal Time Julian date.

  from_astropy(t)

    Build a Skyfield `Time` from an AstroPy time object.

  linspace(t0, t1, num=50)

    Return `num` times spaced uniformly between `t0` to `t1`.

    This routine is named after, and powered by, the NumPy routine linspace().

## The Time object

class skyfield.timelib.Time(ts, tt, tt_fraction=None)

  A single moment in history, or an array of several moments.

  Skyfield programs don’t usually instantiate this class directly, but instead build time objects using one of the timescale methods listed at Time scales. If you do attempt the low-level operation of building a time object yourself, either leave `tt_fraction` at its default value of `None` — in which case Skyfield will assume the fraction is zero — or provide a `tt_fraction` array that has exactly the same dimensions as your `tt` array.

  Four basic floating-point values can be directly accessed as attributes:

  tai

    International Atomic Time (TAI) as a Julian date.

  tt

    Terrestrial Time (TT) as a Julian date.

  J

    Terrestrial Time (TT) as a floating point number of Julian years.

  tdb

    Barycentric Dynamical Time (TDB) as a Julian date.

  ut1

    Universal Time (UT1) as a Julian date.

  Two standard differences between time scales are also available as attributes:

  delta_t

    The difference TT − UT1 measured in seconds.

  dut1

    The difference UT1 − UTC measured in seconds.

  All of the other ways of expressing the time and converting it to typical human systems like UTC and world time zones are offered through methods:

  astimezone(tz)

    Convert to a Python `datetime` in a particular timezone `tz`.

    If this time is an array, then an array of datetimes is returned instead of a single value.

  astimezone_and_leap_second(tz)

    Convert to a Python `datetime` and leap second in a timezone.

    Convert this time to a Python `datetime` and a leap second:

        dt, leap_second = t.astimezone_and_leap_second(tz)

    The argument `tz` should be a `datetime` compatible timezone.

    The leap second value is provided because a Python `datetime` can only number seconds `0` through `59`, but leap seconds have a designation of at least `60`. The leap second return value will normally be `0`, but will instead be `1` if the date and time are a UTC leap second. Add the leap second value to the `second` field of the `datetime` to learn the real name of the second.

    If this time is an array, then an array of `datetime` objects and an array of leap second integers is returned, instead of a single value each.

  toordinal()

    Return the proleptic Gregorian ordinal of the UTC date.

    This method makes Skyfield `Time` objects compatible with Python datetime objects, which also provide a `toordinal()` method. Thanks to this method, a `Time` can often be used directly as a coordinate for a plot.

  utc_datetime()

    Convert to a Python `datetime` in UTC.

    If this time is an array, then a list of datetimes is returned instead of a single value.

  utc_datetime_and_leap_second()

    Convert to a Python `datetime` in UTC, plus a leap second value.

    Convert this time to a datetime object and a leap second:

        dt, leap_second = t.utc_datetime_and_leap_second()

    The leap second value is provided because a Python `datetime` can only number seconds `0` through `59`, but leap seconds have a designation of at least `60`. The leap second return value will normally be `0`, but will instead be `1` if the date and time are a UTC leap second. Add the leap second value to the `second` field of the `datetime` to learn the real name of the second.

    If this time is an array, then an array of `datetime` objects and an array of leap second integers is returned, instead of a single value each.

  utc_iso(delimiter='T', places=0)

    Convert to an ISO 8601 string like `2014-01-18T01:35:38Z` in UTC.

    If this time is an array of dates, then a sequence of strings is returned instead of a single string.

  utc_jpl()

    Convert to a string like `A.D. 2014-Jan-18 01:35:37.5000 UTC`.

    Returns a string for this date and time in UTC, in the format used by the JPL HORIZONS system. If this time is an array of dates, then a sequence of strings is returned instead of a single string.

  utc_strftime(format='%Y-%m-%d %H:%M:%S UTC')

    Format the UTC time using a Python datetime formatting string.

    This calls Python’s `time.strftime()` to format the date and time. A single string is returned or else a whole array of strings, depending on whether this time object is an array. The most commonly used formats are:

    - `%Y` four-digit year, `%y` two-digit year

    - `%m` month number, `%B` name, `%b` abbreviation

    - `%d` day of month

    - `%H` hour

    - `%M` minute

    - `%S` second

    - `%A` day of week, `%a` its abbreviation

    The `%Z` and `%z` formats are not supported; instead, simply use the literal characters `'UTC'` in your format string.

    If the smallest time unit in your format is minutes or seconds, then the time is rounded to the nearest minute or second. Otherwise the value is truncated rather than rounded.

  tai_calendar()

    TAI as a (year, month, day, hour, minute, second) Calendar date.

  tt_calendar()

    TT as a (year, month, day, hour, minute, second) Calendar date.

  tdb_calendar()

    TDB as a (year, month, day, hour, minute, second) Calendar date.

  ut1_calendar()

    UT1 as a (year, month, day, hour, minute, second) Calendar date.

  tai_strftime(format='%Y-%m-%d %H:%M:%S TAI')

    Format TAI with a datetime strftime() format string.

  tt_strftime(format='%Y-%m-%d %H:%M:%S TT')

    Format TT with a datetime strftime() format string.

  tdb_strftime(format='%Y-%m-%d %H:%M:%S TDB')

    Format TDB with a datetime strftime() format string.

  ut1_strftime(format='%Y-%m-%d %H:%M:%S UT1')

    Format UT1 with a datetime strftime() format string.

  M()

    3×3 rotation matrix: ICRS → equinox of this date.

  MT()

    3×3 rotation matrix: equinox of this date → ICRS.

  J()

    Return a floating point Julian year or array of years for this date.

    Julian years are convenient uniform periods of exactly 365.25 days of Terrestrial Time, centered on 2000 January 1 12h TT = Julian year 2000.0.

  utc()

    A tuple `(year, month, day, hour, minute, second)` in UTC.

  gmst()

    Greenwich Mean Sidereal Time (GMST) in hours.

  gast()

    Greenwich Apparent Sidereal Time (GAST) in hours.

  nutation_matrix()

    Compute the 3×3 nutation matrix N for this date.

  precession_matrix()

    Compute the 3×3 precession matrix P for this date.

  to_astropy()

    Return an AstroPy object representing this time.

## Time utilities

skyfield.timelib.compute_calendar_date(jd_integer, julian_before=None)

  Convert Julian day `jd_integer` into a calendar (year, month, day).

  Uses the proleptic Gregorian calendar unless `julian_before` is set to a specific Julian day, in which case the Julian calendar is used for dates older than that.