Skip to main content
`Ctrl`+`K`

# EarthLocation

class astropy.coordinates.EarthLocation(*args, **kwargs)

  Bases: `Quantity`

  Location on the Earth.

  Initialization is first attempted assuming geocentric (x, y, z) coordinates are given; if that fails, another attempt is made assuming geodetic coordinates (longitude, latitude, height above a reference ellipsoid). When using the geodetic forms, Longitudes are measured increasing to the east, so west longitudes are negative. Internally, the coordinates are stored as geocentric.

  To ensure a specific type of coordinates is used, use the corresponding class methods (`from_geocentric` and `from_geodetic`) or initialize the arguments with names (`x`, `y`, `z` for geocentric; `lon`, `lat`, `height` for geodetic). See the class methods for details.

  Notes

  This class fits into the coordinates transformation framework in that it encodes a position on the `ITRS` frame. To get a proper `ITRS` object from this object, use the `itrs` property.

  Attributes Summary

  `ellipsoid` | The default ellipsoid used to convert to geodetic coordinates.
  `geocentric` | Convert to a tuple with X, Y, and Z as quantities.
  `geodetic` | Convert to geodetic coordinates for the default ellipsoid.
  `height` | Height of the location, for the default ellipsoid.
  `info` | Container for meta information like name, description, format.
  `itrs` | An `ITRS` object for the location of this object at the default `obstime`.
  `lat` | Latitude of the location, for the default ellipsoid.
  `lon` | Longitude of the location, for the default ellipsoid.
  `x` | The X component of the geocentric coordinates.
  `y` | The Y component of the geocentric coordinates.
  `z` | The Z component of the geocentric coordinates.

  Methods Summary

  `from_geocentric`(x, y, z[, unit]) | Location on Earth, initialized from geocentric coordinates.
  `from_geodetic`(lon, lat[, height, ellipsoid]) | Location on Earth, initialized from geodetic coordinates.
  `get_gcrs`(obstime) | GCRS position with velocity at `obstime` as a GCRS coordinate.
  `get_gcrs_posvel`(obstime) | Calculate the GCRS position and velocity of this object at the requested `obstime`.
  `get_itrs`([obstime, location]) | Generates an `ITRS` object with the location of this object at the requested `obstime`, either geocentric, or topocentric relative to a given `location`.
  `get_site_names`(*[, refresh_cache]) | Get list of names of observatories for use with `of_site`.
  `gravitational_redshift`(obstime[, bodies, masses]) | Return the gravitational redshift at this EarthLocation.
  `of_address`(address[, get_height, google_api_key]) | Return an object of this class for a given address by querying either the OpenStreetMap Nominatim tool [1] (default) or the Google geocoding API [2], which requires a specified API key.
  `of_site`(site_name, *[, refresh_cache]) | Return an object of this class for a known observatory/site by name.
  `to_geocentric`() | Convert to a tuple with X, Y, and Z as quantities.
  `to_geodetic`([ellipsoid]) | Convert to geodetic coordinates.

  Attributes Documentation

  ellipsoid

    The default ellipsoid used to convert to geodetic coordinates.

  geocentric

    Convert to a tuple with X, Y, and Z as quantities.

  geodetic

    Convert to geodetic coordinates for the default ellipsoid.

  height

    Height of the location, for the default ellipsoid.

  info

    Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.

  itrs

    An `ITRS` object for the location of this object at the default `obstime`.

  lat

    Latitude of the location, for the default ellipsoid.

  lon

    Longitude of the location, for the default ellipsoid.

  x

    The X component of the geocentric coordinates.

  y

    The Y component of the geocentric coordinates.

  z

    The Z component of the geocentric coordinates.

  Methods Documentation

  classmethod from_geocentric(x, y, z, unit=None)

    Location on Earth, initialized from geocentric coordinates.

    Parameters:
      x, y, z `Quantity` or numpy:array_like

        Cartesian coordinates. If not quantities, `unit` should be given.

      unit astropy:unit-like or `python:None`

        Physical unit of the coordinate values. If `x`, `y`, and/or `z` are quantities, they will be converted to this unit.

    Raises:
      `astropy.units.UnitsError`

        If the units on `x`, `y`, and `z` do not match or an invalid unit is given.

      `ValueError`

        If the shapes of `x`, `y`, and `z` do not match.

      `TypeError`

        If `x` is not a `Quantity` and no unit is given.

  classmethod from_geodetic(lon, lat, height=0.0, ellipsoid=None)

    Location on Earth, initialized from geodetic coordinates.

    Parameters:
      lon `Longitude` or `python:float`

        Earth East longitude. Can be anything that initialises an `Angle` object (if float, in degrees).

      lat `Latitude` or `python:float`

        Earth latitude. Can be anything that initialises an `Latitude` object (if float, in degrees).

      height `Quantity` [:ref: ‘length’] or `python:float`, optional

        Height above reference ellipsoid (if float, in meters; default: 0).

      ellipsoid `python:str`, optional

        Name of the reference ellipsoid to use (default: ‘WGS84’). Available ellipsoids are: ‘WGS84’, ‘GRS80’, ‘WGS72’.

    Raises:
      `astropy.units.UnitsError`

        If the units on `lon` and `lat` are inconsistent with angular ones, or that on `height` with a length.

      `ValueError`

        If `lon`, `lat`, and `height` do not have the same shape, or if `ellipsoid` is not recognized as among the ones implemented.

    Notes

    For the conversion to geocentric coordinates, the ERFA routine `gd2gc` is used. See liberfa/erfa

  get_gcrs(obstime)

    GCRS position with velocity at `obstime` as a GCRS coordinate.

    Parameters:
      obstime `Time`

        The `obstime` to calculate the GCRS position/velocity at.

    Returns:
      gcrs `GCRS` instance

        With velocity included.

  get_gcrs_posvel(obstime)

    Calculate the GCRS position and velocity of this object at the requested `obstime`.

    Parameters:
      obstime `Time`

        The `obstime` to calculate the GCRS position/velocity at.

    Returns:
      obsgeoloc `CartesianRepresentation`

        The GCRS position of the object

      obsgeovel `CartesianRepresentation`

        The GCRS velocity of the object

  get_itrs(obstime=None, location=None)

    Generates an `ITRS` object with the location of this object at the requested `obstime`, either geocentric, or topocentric relative to a given `location`.

    Parameters:
      obstime `Time` or `python:None`

        The `obstime` to apply to the new `ITRS`, or if None, the default `obstime` will be used.

      location `EarthLocation` or `python:None`

        A possible observer’s location, for a topocentric ITRS position. If not given (default), a geocentric ITRS object will be created.

    Returns:
      itrs `ITRS`

        The new object in the ITRS frame, either geocentric or topocentric relative to the given `location`.

  classmethod get_site_names(*, refresh_cache=False)

    Get list of names of observatories for use with `of_site`.

    Note

    This function is meant to access the site registry from the astropy data server, which is saved in the user’s local cache. If you would like a site to be added there, issue a pull request to the astropy-data repository . If the cache already exists the function will use it even if the version in the astropy-data repository has been updated unless the `refresh_cache=True` option is used.

    Parameters:
      refresh_cache bool, optional

        If `True`, force replacement of the cached registry with a newly downloaded version. (Default: `False`)

        Added in version 5.3.

    Returns:
      names `python:list` of `python:str`

        List of valid observatory names

    See also

    `of_site`

      Gets the actual location object for one of the sites names this returns.

  gravitational_redshift(obstime, bodies=['sun', 'jupiter', 'moon'], masses={})

    Return the gravitational redshift at this EarthLocation.

    Calculates the gravitational redshift, of order 3 m/s, due to the requested solar system bodies.

    Parameters:
      obstime `Time`

        The `obstime` to calculate the redshift at.

      bodies python:iterable, optional

        The bodies (other than the Earth) to include in the redshift calculation. List elements should be any body name `get_body_barycentric` accepts. Defaults to Jupiter, the Sun, and the Moon. Earth is always included (because the class represents an Earth location).

      masses `python:dict`[`python:str`, `Quantity`], optional

        The mass or gravitational parameters (G * mass) to assume for the bodies requested in `bodies`. Can be used to override the defaults for the Sun, Jupiter, the Moon, and the Earth, or to pass in masses for other bodies.

    Returns:
      redshift `Quantity`

        Gravitational redshift in velocity units at given obstime.

  classmethod of_address(address, get_height=False, google_api_key=None)

    Return an object of this class for a given address by querying either the OpenStreetMap Nominatim tool [1] (default) or the Google geocoding API [2], which requires a specified API key.

    This is intended as a quick convenience function to get easy access to locations. If you need to specify a precise location, you should use the initializer directly and pass in a longitude, latitude, and elevation.

    In the background, this just issues a web query to either of the APIs noted above. This is not meant to be abused! Both OpenStreetMap and Google use IP-based query limiting and will ban your IP if you send more than a few thousand queries per hour [2].

    Warning

    If the query returns more than one location (e.g., searching on `address='springfield'`), this function will use the first returned location.

    Parameters:
      address `python:str`

        The address to get the location for. As per the Google maps API, this can be a fully specified street address (e.g., 123 Main St., New York, NY) or a city name (e.g., Danbury, CT), or etc.

      get_height bool, optional

        This only works when using the Google API! See the `google_api_key` block below. Use the retrieved location to perform a second query to the Google maps elevation API to retrieve the height of the input address [3].

      google_api_key `python:str`, optional

        A Google API key with the Geocoding API and (optionally) the elevation API enabled. See [4] for more information.

    Returns:
      location `EarthLocation` (or subclass) instance

        The location of the input address. Will be type(this class)

    References

    [1] (1,2)

    https://nominatim.openstreetmap.org/

    [2] (1,2,3)

    https://developers.google.com/maps/documentation/geocoding/start

    [3]

    https://developers.google.com/maps/documentation/elevation/start

    [4]

    https://developers.google.com/maps/documentation/geocoding/get-api-key

  classmethod of_site(site_name, *, refresh_cache=False)

    Return an object of this class for a known observatory/site by name.

    This is intended as a quick convenience function to get basic site information, not a fully-featured exhaustive registry of observatories and all their properties.

    Additional information about the site is stored in the `.info.meta` dictionary of sites obtained using this method (see the examples below).

    Note

    This function is meant to access the site registry from the astropy data server, which is saved in the user’s local cache. If you would like a site to be added there, issue a pull request to the astropy-data repository . If the cache already exists the function will use it even if the version in the astropy-data repository has been updated unless the `refresh_cache=True` option is used.

    Parameters:
      site_name `python:str`

        Name of the observatory (case-insensitive).

      refresh_cache bool, optional

        If `True`, force replacement of the cached registry with a newly downloaded version. (Default: `False`)

        Added in version 5.3.

    Returns:
      site `EarthLocation` (or subclass) instance

        The location of the observatory. The returned class will be the same as this class.

    See also

    `get_site_names`

      the list of sites that this function can access

    Examples

        >>> from astropy.coordinates import EarthLocation
        >>> keck = EarthLocation.of_site('Keck Observatory')
        >>> keck.geodetic
        GeodeticLocation(lon=<Longitude -155.47833333 deg>, lat=<Latitude 19.82833333 deg>, height=<Quantity 4160. m>)
        >>> keck.info
        name = W. M. Keck Observatory
        dtype = (float64, float64, float64)
        unit = m
        class = EarthLocation
        n_bad = 0
        >>> keck.info.meta
        {'source': 'IRAF Observatory Database', 'timezone': 'US/Hawaii'}

  to_geocentric()

    Convert to a tuple with X, Y, and Z as quantities.

  to_geodetic(ellipsoid=None)

    Convert to geodetic coordinates.

    Parameters:
      ellipsoid `python:str`, optional

        Reference ellipsoid to use. Default is the one the coordinates were initialized with. Available are: ‘WGS84’, ‘GRS80’, ‘WGS72’

    Returns:
      lon, lat, height `Quantity`

        The tuple is a `GeodeticLocation` namedtuple and is comprised of instances of `Longitude`, `Latitude`, and `Quantity`.

    Raises:
      `ValueError`

        if `ellipsoid` is not recognized as among the ones implemented.

    Notes

    For the conversion to geodetic coordinates, the ERFA routine `gc2gd` is used. See liberfa/erfa