# API Reference — Units

When you ask positions to return distances, velocities, or angles, they return instances of the following classes.

class skyfield.units.Distance(au=None, km=None, m=None)

  A distance, stored internally as au and available in other units.

  You can initialize a `Distance` by providing a single float or a float array as either an `au=`, `km=`, or `m=` parameter.

  You can access the magnitude of the distance with its three attributes `.au`, `.km`, and `.m`. By default a distance prints itself in astronomical units (au), but you can take control of the formatting and choice of units yourself using standard Python numeric formatting:

      >>> d = Distance(au=1)
      >>> print(d)
      1.0 au
      >>> print('{:.2f} km'.format(d.km))
      149597870.70 km

  au(value)

    Astronomical units (the Earth-Sun distance of 149,597,870,700 m).

  km(value)

    Kilometers (1,000 meters).

  m(value)

    Meters.

  length()

    Compute the length when this is an (x,y,z) vector.

    The Euclidean vector length of this vector is returned as a new `Distance` object.

        >>> from skyfield.api import Distance
        >>> d = Distance(au=[1, 1, 0])
        >>> d.length()
        <Distance 1.41421 au>

  light_seconds()

    Return the length of this vector in light seconds.

  to(unit)

    Convert this distance to the given AstroPy unit.

class skyfield.units.Velocity(au_per_d=None, km_per_s=None)

  A velocity, stored internally as au/day and available in other units.

  You can initialize a `Velocity` by providing a float or float array to its `au_per_d=` parameter.

  au_per_d(value)

    Astronomical units per day.

  km_per_s(value)

    Kilometers per second.

  m_per_s(value)

    Meters per second.

  to(unit)

    Convert this velocity to the given AstroPy unit.

class skyfield.units.Angle(angle=None, radians=None, degrees=None, hours=None, preference=None, signed=False)
  radians(value)

    Radians (𝜏 = 2𝜋 in a circle).

  hours()

    Hours (24h in a circle).

  degrees()

    Degrees (360° in a circle).

  arcminutes()

    Return the angle in arcminutes.

  arcseconds()

    Return the angle in arcseconds.

  mas()

    Return the angle in milliarcseconds.

  hms(warn=True)

    Convert to a tuple (hours, minutes, seconds).

    All three quantities will have the same sign as the angle itself.

  signed_hms(warn=True)

    Convert to a tuple (sign, hours, minutes, seconds).

    The `sign` will be either +1 or -1, and the other quantities will all be positive.

  hstr(places=2, warn=True, format='{0}{1:02}h {2:02}m {3:02}.{4:0{5}}s')

    Return a string like `12h 07m 30.00s`; see Formatting angles.

    Added in version 1.39: Added the `format=` parameter.

  dms(warn=True)

    Convert to a tuple (degrees, minutes, seconds).

    All three quantities will have the same sign as the angle itself.

  signed_dms(warn=True)

    Convert to a tuple (sign, degrees, minutes, seconds).

    The `sign` will be either +1 or -1, and the other quantities will all be positive.

  dstr(places=1, warn=True, format=None)

    Return a string like `181deg 52' 30.0"`; see Formatting angles.

    Added in version 1.39: Added the `format=` parameter.

  to(unit)

    Convert this angle to the given AstroPy unit.

class skyfield.units.AngleRate

  The rate at which an angle is changing.

  radians()

    `Rate` of change in radians.

  degrees()

    `Rate` of change in degrees.

  arcminutes()

    `Rate` of change in arcminutes.

  arcseconds()

    `Rate` of change in arcseconds.

  mas()

    `Rate` of change in milliarcseconds.

class skyfield.units.Rate

  Measurement whose denominator is time.

  per_day()

    Units per day of Terrestrial Time.

  per_hour()

    Units per hour of Terrestrial Time.

  per_minute()

    Units per minute of Terrestrial Time.

  per_second()

    Units per second of Terrestrial Time.

## Formatting angles

To display an angle as decimal degrees or hours, ask the angle for its `.hours` or `.degrees` attribute and then use any normal Python mechanism for formatting a float. For example:

    ra, dec = Angle(hours=5.5877286), Angle(degrees=-5.38731536)

    print('RA {:.8f} hours'.format(ra.hours))
    print('Dec {:+.8f} degrees'.format(dec.degrees))

    RA 5.58772860 hours
    Dec -5.38731536 degrees

If you let Skyfield do the formatting instead, then hours are split into 60 minutes of 60 seconds each, and degrees are split into 60 arcminutes of 60 arcseconds each:

    print('RA', ra)
    print('Dec', dec)

    RA 05h 35m 15.82s
    Dec -05deg 23' 14.3"

If you want more control over the display of minutes and seconds, you can call an angle’s “hours as a string” method `hstr()` or “degrees as a string” method `dstr()`. The simplest adjustment you can make is to specify the number of decimal `places` that will be shown in the seconds field.

    print('RA', ra.hstr(places=4))
    print('Dec', dec.dstr(places=4))

    RA 05h 35m 15.8230s
    Dec -05deg 23' 14.3353"

In each of these examples you can see that Skyfield marks arcminutes with the ASCII apostrophe `'` and arcseconds with the ASCII quotation mark `"`. Using plain ASCII lets Skyfield support as many operating systems and output media as possible. But it would be more correct to denote arcseconds and arcminutes with the Unicode symbols PRIME and DOUBLE PRIME, and to use the Unicode DEGREE SIGN to mark the whole number:

−5°23′14.3″

If you want to override Skyfield’s default notation to create either the string above, or any other notation, then give `hstr()` or `dstr()` a `format=` string of your own. It should use the syntax of Python’s str.format() method. For example, here’s the exact string you would use to format an angle in degrees, arcminutes, and arcseconds using the traditional typographic symbols discussed above:

    print(dec.dstr(format=u'{0}{1}°{2:02}′{3:02}.{4:0{5}}″'))

    -5°23′14.3″

(Note that the leading `u`, for “Unicode”, is only mandatory in Python 2, not Python 3.)

Skyfield will call your string’s format method with these six arguments:

{0}

  An ASCII hyphen `'-'` if the angle is negative, else the empty string. If you want positive angles to be decorated with a plus sign, try using `{0:+>1}` which tells Python, “display positional parameter 0, padding the field to one character wide if it’s less than one character already, and use the `+` character to do the padding.”

{1}

  The number of whole hours or degrees.

{2}

  The number of whole minutes.

{3}

  The number of whole seconds.

{4}

  The fractions of a second. Be sure to pad this field to the number of `places=` you’ve requested, or else a fraction like `.0012` will format incorrectly as `.12`. If you have asked for `places=3`, for example, you’ll want to display this field as `{4:03}`. (See also the next item.)

{5}

  The number of `places=` you requested, which you will probably use like `{4:0{5}}` when formatting field 4. You can use this in case you might not know the number of places ahead of time, for example if the number of places is configured by your user.

It would have been nice if the `format=` string were the first option to `hstr()` or `dstr()` so that its keyword name could be omitted but, alas, it was only added in Skyfield 1.39, by which point the other options had already grabbed the first spots.