# EarthLocation¶

class astropy.coordinates.EarthLocation[source] [edit on github]

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 with for the location of this object at the default obstime. lat Longitude of the location, for the default ellipsoid. latitude lon Longitude of the location, for the default ellipsoid. longitude 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]) Generates an ITRS object with the location of this object at the requested obstime. get_site_names() 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]) Return an object of this class for a given address by querying the Google maps geocoding API. of_site(site_name) 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 with for the location of this object at the default obstime.

lat

Longitude of the location, for the default ellipsoid.

latitude

Deprecated since version 2.0: The latitude property is deprecated and may be removed in a future version. Use lat instead.

Latitude of the location, for the default ellipsoid.

lon

Longitude of the location, for the default ellipsoid.

longitude

Deprecated since version 2.0: The longitude property is deprecated and may be removed in a future version. Use lon instead.

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)[source] [edit on github]

Location on Earth, initialized from geocentric coordinates.

Parameters: x, y, z : Quantity or array-like Cartesian coordinates. If not quantities, unit should be given. unit : UnitBase object or None Physical unit of the coordinate values. If x, y, and/or z are quantities, they will be converted to this unit. 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)[source] [edit on github]

Location on Earth, initialized from geodetic coordinates.

Parameters: lon : Longitude or float Earth East longitude. Can be anything that initialises an Angle object (if float, in degrees). lat : Latitude or float Earth latitude. Can be anything that initialises an Latitude object (if float, in degrees). height : Quantity or float, optional Height above reference ellipsoid (if float, in meters; default: 0). ellipsoid : str, optional Name of the reference ellipsoid to use (default: ‘WGS84’). Available ellipsoids are: ‘WGS84’, ‘GRS80’, ‘WGS72’. 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 https://github.com/liberfa/erfa

get_gcrs(obstime)[source] [edit on github]

GCRS position with velocity at obstime as a GCRS coordinate.

Parameters: obstime : Time The obstime to calculate the GCRS position/velocity at. gcrs : GCRS instance With velocity included.
get_gcrs_posvel(obstime)[source] [edit on github]

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. obsgeoloc : CartesianRepresentation The GCRS position of the object obsgeovel : CartesianRepresentation The GCRS velocity of the object
get_itrs(obstime=None)[source] [edit on github]

Generates an ITRS object with the location of this object at the requested obstime.

Parameters: obstime : Time or None The obstime to apply to the new ITRS, or if None, the default obstime will be used. itrs : ITRS The new object in the ITRS frame
classmethod get_site_names()[source] [edit on github]

Get list of names of observatories for use with of_site.

Note

When this function is called, it will first attempt to download site information from the astropy data server. If it cannot (i.e., an internet connection is not available), it will fall back on the list included with astropy (which is a limited and dated set of sites). If you think a site should be added, issue a pull request to the astropy-data repository .

Returns: names : list of 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={})[source] [edit on github]

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 : 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 : dict of str to 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. redshift : Quantity Gravitational redshift in velocity units at given obstime.
classmethod of_address(address, get_height=False)[source] [edit on github]

Return an object of this class for a given address by querying the Google maps geocoding API.

This is intended as a quick convenience function to get fast access to locations. In the background, this just issues a query to the Google maps geocoding API. It is not meant to be abused! Google uses IP-based query limiting and will ban your IP if you send more than a few thousand queries per hour [R5].

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 : 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) Use the retrieved location to perform a second query to the Google maps elevation API to retrieve the height of the input address [R6]. location : This class (a EarthLocation or subclass) The location of the input address.

References

classmethod of_site(site_name)[source] [edit on github]

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.

Note

When this function is called, it will attempt to download site information from the astropy data server. If you would like a site to be added, issue a pull request to the astropy-data repository . If a site cannot be found in the registry (i.e., an internet connection is not available), it will fall back on a built-in list, In the future, this bundled list might include a version-controlled list of canonical observatories extracted from the online version, but it currently only contains the Greenwich Royal Observatory as an example case.

Parameters: site_name : str Name of the observatory (case-insensitive). site : This class (a EarthLocation or subclass) The location of the observatory.

See also

get_site_names
the list of sites that this function can access
to_geocentric()[source] [edit on github]

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

to_geodetic(ellipsoid=None)[source] [edit on github]

Convert to geodetic coordinates.

Parameters: ellipsoid : str, optional Reference ellipsoid to use. Default is the one the coordinates were initialized with. Available are: ‘WGS84’, ‘GRS80’, ‘WGS72’ (lon, lat, height) : tuple The tuple contains instances of Longitude, Latitude, and Quantity 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 https://github.com/liberfa/erfa