CRS

CRS

class pyproj.crs.CRS(projparams: Optional[Any] = None, **kwargs)[source]

A pythonic Coordinate Reference System manager.

New in version 2.0.0.

The functionality is based on other fantastic projects:

srs

The string form of the user input used to create the CRS.

Type

str

__init__(projparams: Optional[Any] = None, **kwargs) → None[source]
Initialize a CRS class instance with:

  • PROJ string

  • Dictionary of PROJ parameters

  • PROJ keyword arguments for parameters

  • JSON string with PROJ parameters

  • CRS WKT string

  • An authority string [i.e. ‘epsg:4326’]

  • An EPSG integer code [i.e. 4326]

  • A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

  • An object with a to_wkt method.

  • A pyproj.crs.CRS class

Example usage:

>>> from pyproj import CRS
>>> crs_utm = CRS.from_user_input(26915)
>>> crs_utm
<Projected CRS: EPSG:26915>
Name: NAD83 / UTM zone 15N
Axis Info [cartesian]:
- E[east]: Easting (metre)
- N[north]: Northing (metre)
Area of Use:
- name: North America - 96°W to 90°W and NAD83 by country
- bounds: (-96.0, 25.61, -90.0, 84.0)
Coordinate Operation:
- name: UTM zone 15N
- method: Transverse Mercator
Datum: North American Datum 1983
- Ellipsoid: GRS 1980
- Prime Meridian: Greenwich

>>> crs_utm.area_of_use.bounds
(-96.0, 25.61, -90.0, 84.0)
>>> crs_utm.ellipsoid
ELLIPSOID["GRS 1980",6378137,298.257222101,
    LENGTHUNIT["metre",1],
    ID["EPSG",7019]]
>>> crs_utm.ellipsoid.inverse_flattening
298.257222101
>>> crs_utm.ellipsoid.semi_major_metre
6378137.0
>>> crs_utm.ellipsoid.semi_minor_metre
6356752.314140356
>>> crs_utm.prime_meridian
PRIMEM["Greenwich",0,
    ANGLEUNIT["degree",0.0174532925199433],
    ID["EPSG",8901]]
>>> crs_utm.prime_meridian.unit_name
'degree'
>>> crs_utm.prime_meridian.unit_conversion_factor
0.017453292519943295
>>> crs_utm.prime_meridian.longitude
0.0
>>> crs_utm.datum
DATUM["North American Datum 1983",
    ELLIPSOID["GRS 1980",6378137,298.257222101,
        LENGTHUNIT["metre",1]],
    ID["EPSG",6269]]
>>> crs_utm.coordinate_system
CS[Cartesian,2],
    AXIS["(E)",east,
        ORDER[1],
        LENGTHUNIT["metre",1,
            ID["EPSG",9001]]],
    AXIS["(N)",north,
        ORDER[2],
        LENGTHUNIT["metre",1,
            ID["EPSG",9001]]]
>>> print(crs_utm.coordinate_operation.to_wkt(pretty=True))
CONVERSION["UTM zone 15N",
    METHOD["Transverse Mercator",
        ID["EPSG",9807]],
    PARAMETER["Latitude of natural origin",0,
        ANGLEUNIT["degree",0.0174532925199433],
        ID["EPSG",8801]],
    PARAMETER["Longitude of natural origin",-93,
        ANGLEUNIT["degree",0.0174532925199433],
        ID["EPSG",8802]],
    PARAMETER["Scale factor at natural origin",0.9996,
        SCALEUNIT["unity",1],
        ID["EPSG",8805]],
    PARAMETER["False easting",500000,
        LENGTHUNIT["metre",1],
        ID["EPSG",8806]],
    PARAMETER["False northing",0,
        LENGTHUNIT["metre",1],
        ID["EPSG",8807]],
    ID["EPSG",16015]]
>>> crs = CRS(proj='utm', zone=10, ellps='WGS84')
>>> print(crs.to_wkt(pretty=True))
PROJCRS["unknown",
    BASEGEOGCRS["unknown",
        DATUM["Unknown based on WGS84 ellipsoid",
            ELLIPSOID["WGS 84",6378137,298.257223563,
                LENGTHUNIT["metre",1],
                ID["EPSG",7030]]],
        PRIMEM["Greenwich",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8901]]],
    CONVERSION["UTM zone 10N",
        METHOD["Transverse Mercator",
            ID["EPSG",9807]],
        PARAMETER["Latitude of natural origin",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8801]],
        PARAMETER["Longitude of natural origin",-123,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8802]],
        PARAMETER["Scale factor at natural origin",0.9996,
            SCALEUNIT["unity",1],
            ID["EPSG",8805]],
        PARAMETER["False easting",500000,
            LENGTHUNIT["metre",1],
            ID["EPSG",8806]],
        PARAMETER["False northing",0,
            LENGTHUNIT["metre",1],
            ID["EPSG",8807]],
        ID["EPSG",16010]],
    CS[Cartesian,2],
        AXIS["(E)",east,
            ORDER[1],
            LENGTHUNIT["metre",1,
                ID["EPSG",9001]]],
        AXIS["(N)",north,
            ORDER[2],
            LENGTHUNIT["metre",1,
                ID["EPSG",9001]]]]
>>> geod = crs.get_geod()
>>> f"+a={geod.a:.0f} +f={geod.f:.8f}"
'+a=6378137 +f=0.00335281'
>>> crs.is_projected
True
>>> crs.is_geographic
False
property area_of_use: Optional[pyproj.aoi.AreaOfUse]

returns: The area of use object with associated attributes. :rtype: AreaOfUse

property axis_info: List[pyproj._crs.Axis]

Retrieves all relevant axis information in the CRS. If it is a Bound CRS, it gets the axis list from the Source CRS. If it is a Compound CRS, it gets the axis list from the Sub CRS list.

Returns

The list of axis information.

Return type

List[Axis]

property coordinate_operation: Optional[pyproj._crs.CoordinateOperation]

New in version 2.2.0.

Return type

CoordinateOperation

property coordinate_system: Optional[pyproj._crs.CoordinateSystem]

New in version 2.2.0.

Return type

CoordinateSystem

cs_to_cf() → List[dict][source]

New in version 3.0.0.

This converts all coordinate systems (cs) in the CRS to a list of Climate and Forecast (CF) Version 1.8 dicts.

Managing CRS to and from CF

Returns

CF-1.8 version of the coordinate systems.

Return type

List[dict]

property datum: Optional[pyproj._crs.Datum]

New in version 2.2.0.

Return type

Datum

property ellipsoid: Optional[pyproj._crs.Ellipsoid]

New in version 2.2.0.

Returns

The ellipsoid object with associated attributes.

Return type

Ellipsoid

equals(other: Any, ignore_axis_order: bool = False) → bool[source]

New in version 2.5.0.

Check if the CRS objects are equivalent.

Parameters

  • other (Any) – Check if the other object is equivalent to this object. If the other object is not a CRS, it will try to create one. On Failure, it will return False.

  • ignore_axis_order (bool, default=False) – If True, it will compare the CRS class and ignore the axis order.

Return type

bool

classmethod from_authority(auth_name: str, code: Union[str, int]) → pyproj.crs.crs.CRS[source]

New in version 2.2.0.

Make a CRS from an authority name and authority code

Parameters

  • auth_name (str) – The name of the authority.

  • code (int or str) – The code used by the authority.

Return type

CRS

static from_cf(in_cf: dict, ellipsoidal_cs: Optional[Any] = None, cartesian_cs: Optional[Any] = None, vertical_cs: Optional[Any] = None, errcheck=False) → pyproj.crs.crs.CRS[source]

New in version 2.2.0.

New in version 3.0.0: ellipsoidal_cs, cartesian_cs, vertical_cs

Deprecated since version 3.2.0: errcheck

This converts a Climate and Forecast (CF) Grid Mapping Version 1.8 dict to a pyproj.crs.CRS object.

Managing CRS to and from CF

Parameters
Return type

CRS

classmethod from_dict(proj_dict: dict) → pyproj.crs.crs.CRS[source]

New in version 2.2.0.

Make a CRS from a dictionary of PROJ parameters.

Parameters

proj_dict (str) – PROJ params in dict format.

Return type

CRS

classmethod from_epsg(code: Union[str, int]) → pyproj.crs.crs.CRS[source]

Make a CRS from an EPSG code

Parameters

code (int or str) – An EPSG code.

Return type

CRS

classmethod from_json(crs_json: str) → pyproj.crs.crs.CRS[source]

New in version 2.4.0.

Create CRS from a CRS JSON string.

Parameters

crs_json (str) – CRS JSON string.

Return type

CRS

classmethod from_json_dict(crs_dict: dict) → pyproj.crs.crs.CRS[source]

New in version 2.4.0.

Create CRS from a JSON dictionary.

Parameters

crs_dict (dict) – CRS dictionary.

Return type

CRS

classmethod from_proj4(in_proj_string: str) → pyproj.crs.crs.CRS[source]

New in version 2.2.0.

Make a CRS from a PROJ string

Parameters

in_proj_string (str) – A PROJ string.

Return type

CRS

classmethod from_string(in_crs_string: str) → pyproj.crs.crs.CRS[source]

Make a CRS from:

Initialize a CRS class instance with:

  • PROJ string

  • JSON string with PROJ parameters

  • CRS WKT string

  • An authority string [i.e. ‘epsg:4326’]

Parameters

in_crs_string (str) – An EPSG, PROJ, or WKT string.

Return type

CRS

classmethod from_user_input(value: Any, **kwargs) → pyproj.crs.crs.CRS[source]
Initialize a CRS class instance with:

  • PROJ string

  • Dictionary of PROJ parameters

  • PROJ keyword arguments for parameters

  • JSON string with PROJ parameters

  • CRS WKT string

  • An authority string [i.e. ‘epsg:4326’]

  • An EPSG integer code [i.e. 4326]

  • A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

  • An object with a to_wkt method.

  • A pyproj.crs.CRS class

Parameters

value (obj) – A Python int, dict, or str.

Return type

CRS

classmethod from_wkt(in_wkt_string: str) → pyproj.crs.crs.CRS[source]

New in version 2.2.0.

Make a CRS from a WKT string

Parameters

in_wkt_string (str) – A WKT string.

Return type

CRS

property geodetic_crs: Optional[pyproj.crs.crs.CRS]

New in version 2.2.0.

Returns

The geodeticCRS / geographicCRS from the CRS.

Return type

CRS

get_geod() → Optional[pyproj.geod.Geod][source]
Returns

Geod object based on the ellipsoid.

Return type

pyproj.geod.Geod

property is_bound: bool

returns: True if CRS is bound. :rtype: bool

property is_compound: bool

New in version 3.1.0.

Returns

True if CRS is compound.

Return type

bool

property is_derived

New in version 3.2.0.

Returns

True if CRS is a Derived CRS.

Return type

bool

property is_engineering: bool

New in version 2.2.0.

Returns

True if CRS is local/engineering.

Return type

bool

is_exact_same(other: Any) → bool[source]

Check if the CRS objects are the exact same.

Parameters

other (Any) – Check if the other CRS is the exact same to this object. If the other object is not a CRS, it will try to create one. On Failure, it will return False.

Return type

bool

property is_geocentric: bool

This checks if the CRS is geocentric and takes into account if the CRS is bound.

Returns

True if CRS is in geocentric (x/y) coordinates.

Return type

bool

property is_geographic: bool

This checks if the CRS is geographic. It will check if it has a geographic CRS in the sub CRS if it is a compount CRS and will check if the source CRS is geographic if it is a bound CRS.

Returns

True if the CRS is in geographic (lon/lat) coordinates.

Return type

bool

property is_projected: bool

This checks if the CRS is projected. It will check if it has a projected CRS in the sub CRS if it is a compount CRS and will check if the source CRS is projected if it is a bound CRS.

Returns

True if CRS is projected.

Return type

bool

property is_vertical: bool

New in version 2.2.0.

This checks if the CRS is vertical. It will check if it has a vertical CRS in the sub CRS if it is a compount CRS and will check if the source CRS is vertical if it is a bound CRS.

Returns

True if CRS is vertical.

Return type

bool

list_authority(auth_name: Optional[str] = None, min_confidence: int = 70) → List[importlib._bootstrap.AuthorityMatchInfo][source]

New in version 3.2.0.

Return the authority names and codes best matching the CRS.

Example:

>>> from pyproj import CRS
>>> ccs = CRS("epsg:4328")
>>> ccs.list_authority()
[AuthorityMatchInfo(auth_name='EPSG', code='4326', confidence=100)]

If the CRS is bound, you can get an authority from the source CRS:

>>> from pyproj import CRS
>>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
>>> ccs.list_authority()
[]
>>> ccs.source_crs.list_authority()
[AuthorityMatchInfo(auth_name='EPSG', code='4978', confidence=70)]
>>> ccs == CRS.from_authorty('EPSG', '4978')
False
Parameters
Returns

List of authority matches for the CRS.

Return type

List[AuthorityMatchInfo]

property name: str

returns: The name of the CRS (from proj_get_name()). :rtype: str

property prime_meridian: Optional[pyproj._crs.PrimeMeridian]

New in version 2.2.0.

Returns

The prime meridian object with associated attributes.

Return type

PrimeMeridian

property remarks: str

New in version 2.4.0.

Returns

Remarks about object.

Return type

str

property scope: str

New in version 2.4.0.

Returns

Scope of object.

Return type

str

property source_crs: Optional[pyproj.crs.crs.CRS]

The base CRS of a BoundCRS or a DerivedCRS/ProjectedCRS, or the source CRS of a CoordinateOperation.

Return type

CRS

property sub_crs_list: List[pyproj.crs.crs.CRS]

If the CRS is a compound CRS, it will return a list of sub CRS objects.

Return type

List[CRS]

property target_crs: Optional[pyproj.crs.crs.CRS]

New in version 2.2.0.

Returns

The hub CRS of a BoundCRS or the target CRS of a CoordinateOperation.

Return type

CRS

to_3d(name: Optional[str] = None) → pyproj.crs.crs.CRS[source]

New in version 3.1.0.

Convert the current CRS to the 3D version if it makes sense.

New vertical axis attributes:

  • ellipsoidal height

  • oriented upwards

  • metre units

Parameters

name (str, optional) – CRS name. Defaults to use the name of the original CRS.

Return type

CRS

to_authority(auth_name: Optional[str] = None, min_confidence: int = 70)[source]

New in version 2.2.0.

Return the authority name and code best matching the CRS or None if it a match is not found.

Example:

>>> from pyproj import CRS
>>> ccs = CRS("epsg:4328")
>>> ccs.to_authority()
('EPSG', '4328')

If the CRS is bound, you can get an authority from the source CRS:

>>> from pyproj import CRS
>>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
>>> ccs.to_authority()
>>> ccs.source_crs.to_authority()
('EPSG', '4978')
>>> ccs == CRS.from_authorty('EPSG', '4978')
False
Parameters
Returns

The best matching (<auth_name>, <code>) for the confidence level.

Return type

tuple(str, str) or None

to_cf(wkt_version: Union[pyproj.enums.WktVersion, str] = WktVersion.WKT2_2019, errcheck: bool = False) → dict[source]

New in version 2.2.0.

This converts a pyproj.crs.CRS object to a Climate and Forecast (CF) Grid Mapping Version 1.8 dict.

Managing CRS to and from CF

Parameters
Returns

CF-1.8 version of the projection.

Return type

dict

to_dict() → dict[source]

New in version 2.2.0.

Converts the CRS to dictionary of PROJ parameters.

Warning

You will likely lose important projection information when converting to a PROJ string from another format. See: https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems # noqa: E501

Returns

PROJ params in dict format.

Return type

dict

to_epsg(min_confidence: int = 70) → Optional[int][source]

Return the EPSG code best matching the CRS or None if it a match is not found.

Example:

>>> from pyproj import CRS
>>> ccs = CRS("epsg:4328")
>>> ccs.to_epsg()
4328

If the CRS is bound, you can attempt to get an epsg code from the source CRS:

>>> from pyproj import CRS
>>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
>>> ccs.to_epsg()
>>> ccs.source_crs.to_epsg()
4978
>>> ccs == CRS.from_epsg(4978)
False
Parameters

min_confidence (int, default=70) – A value between 0-100 where 100 is the most confident. Why does the EPSG code return when using EPSG:xxxx and not with +init=EPSG:xxxx?

Returns

The best matching EPSG code matching the confidence level.

Return type

Optional[int]

to_json(pretty: bool = False, indentation: int = 2) → str[source]

New in version 2.4.0.

Convert the object to a JSON string.

Parameters

  • pretty (bool, default=False) – If True, it will set the output to be a multiline string.

  • indentation (int, default=2) – If pretty is True, it will set the width of the indentation.

Return type

str

to_json_dict() → dict[source]

New in version 2.4.0.

Convert the object to a JSON dictionary.

Return type

dict

to_proj4(version: Union[pyproj.enums.ProjVersion, int] = ProjVersion.PROJ_5) → str[source]

Convert the projection to a PROJ string.

Warning

You will likely lose important projection information when converting to a PROJ string from another format. See: https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems # noqa: E501

Parameters

version (pyproj.enums.ProjVersion) – The version of the PROJ string output. Default is pyproj.enums.ProjVersion.PROJ_4.

Return type

str

to_string() → str[source]

New in version 2.2.0.

Convert the CRS to a string.

It attempts to convert it to the authority string. Otherwise, it uses the string format of the user input to create the CRS.

Return type

str

to_wkt(version: Union[pyproj.enums.WktVersion, str] = WktVersion.WKT2_2019, pretty: bool = False) → str[source]

Convert the projection to a WKT string.

Version options:

  • WKT2_2015

  • WKT2_2015_SIMPLIFIED

  • WKT2_2019

  • WKT2_2019_SIMPLIFIED

  • WKT1_GDAL

  • WKT1_ESRI

Parameters
Return type

str

property type_name: str

returns: The name of the type of the CRS object. :rtype: str

property utm_zone: Optional[str]

New in version 2.6.0.

Finds the UTM zone in a Projected CRS, Bound CRS, or Compound CRS

Returns

The UTM zone number and letter if applicable.

Return type

Optional[str]

GeographicCRS

class pyproj.crs.GeographicCRS(name: str = 'undefined', datum: Any = 'urn:ogc:def:datum:EPSG::6326', ellipsoidal_cs: Optional[Any] = None)[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Geographic CRS

__init__(name: str = 'undefined', datum: Any = 'urn:ogc:def:datum:EPSG::6326', ellipsoidal_cs: Optional[Any] = None) → None[source]
Parameters

DerivedGeographicCRS

class pyproj.crs.DerivedGeographicCRS(base_crs: Any, conversion: Any, ellipsoidal_cs: Optional[Any] = None, name: str = 'undefined')[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Derived Geographic CRS

__init__(base_crs: Any, conversion: Any, ellipsoidal_cs: Optional[Any] = None, name: str = 'undefined') → None[source]
Parameters

GeocentricCRS

class pyproj.crs.GeocentricCRS(name: str = 'undefined', datum: Any = 'urn:ogc:def:datum:EPSG::6326')[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 3.2.0.

This class is for building a Geocentric CRS

__init__(name: str = 'undefined', datum: Any = 'urn:ogc:def:datum:EPSG::6326') → None[source]
Parameters

ProjectedCRS

class pyproj.crs.ProjectedCRS(conversion: Any, name: str = 'undefined', cartesian_cs: Optional[Any] = None, geodetic_crs: Optional[Any] = None)[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Projected CRS.

__init__(conversion: Any, name: str = 'undefined', cartesian_cs: Optional[Any] = None, geodetic_crs: Optional[Any] = None) → None[source]
Parameters

VerticalCRS

class pyproj.crs.VerticalCRS(name: str, datum: Any, vertical_cs: Optional[Any] = None, geoid_model: Optional[str] = None)[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Vetical CRS.

Warning

geoid_model support only exists in PROJ >= 6.3.0

__init__(name: str, datum: Any, vertical_cs: Optional[Any] = None, geoid_model: Optional[str] = None) → None[source]
Parameters

BoundCRS

class pyproj.crs.BoundCRS(source_crs: Any, target_crs: Any, transformation: Any)[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Bound CRS.

__init__(source_crs: Any, target_crs: Any, transformation: Any) → None[source]
Parameters

  • source_crs (Any) – Input to create a source CRS.

  • target_crs (Any) – Input to create the target CRS.

  • transformation (Any) – Input to create the transformation.

CompoundCRS

class pyproj.crs.CompoundCRS(name: str, components: List[Any])[source]

Bases: pyproj.crs.crs.CustomConstructorCRS

New in version 2.5.0.

This class is for building a Compound CRS.

__init__(name: str, components: List[Any]) → None[source]
Parameters

  • name (str) – The name of the Compound CRS.

  • components (List[Any], optional) – List of CRS to create a Compound Coordinate System. List of anything accepted by pyproj.crs.CRS.from_user_input()

CustomConstructorCRS

class pyproj.crs.CustomConstructorCRS(projparams: Optional[Any] = None, **kwargs)[source]

Bases: pyproj.crs.crs.CRS

This class is a base class for CRS classes that use a different constructor than the main CRS class.

New in version 3.2.0.

See: https://github.com/pyproj4/pyproj/issues/847

classmethod from_user_input(value: Any, **kwargs) → pyproj.crs.crs.CRS[source]
Initialize a CRS class instance with:

  • PROJ string

  • Dictionary of PROJ parameters

  • PROJ keyword arguments for parameters

  • JSON string with PROJ parameters

  • CRS WKT string

  • An authority string [i.e. ‘epsg:4326’]

  • An EPSG integer code [i.e. 4326]

  • A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

  • An object with a to_wkt method.

  • A pyproj.crs.CRS class

Parameters

value (obj) – A Python int, dict, or str.

Return type

CRS

property geodetic_crs: Optional[pyproj.crs.crs.CRS]

New in version 2.2.0.

Returns

The geodeticCRS / geographicCRS from the CRS.

Return type

CRS

property source_crs: Optional[pyproj.crs.crs.CRS]

The base CRS of a BoundCRS or a DerivedCRS/ProjectedCRS, or the source CRS of a CoordinateOperation.

Return type

CRS

property sub_crs_list: List[pyproj.crs.crs.CRS]

If the CRS is a compound CRS, it will return a list of sub CRS objects.

Return type

List[CRS]

property target_crs: Optional[pyproj.crs.crs.CRS]

New in version 2.2.0.

Returns

The hub CRS of a BoundCRS or the target CRS of a CoordinateOperation.

Return type

CRS

to_3d(name: Optional[str] = None) → pyproj.crs.crs.CRS[source]

New in version 3.1.0.

Convert the current CRS to the 3D version if it makes sense.

New vertical axis attributes:

  • ellipsoidal height

  • oriented upwards

  • metre units

Parameters

name (str, optional) – CRS name. Defaults to use the name of the original CRS.

Return type

CRS

is_wkt

pyproj.crs.is_wkt(unicode proj_string)

New in version 2.0.0.

Check if the input projection string is in the Well-Known Text format.

Parameters

proj_string (str) – The projection string.

Returns

bool

Return type

True if the string is in the Well-Known Text format

is_proj

pyproj.crs.is_proj(unicode proj_string)

New in version 2.2.2.

Check if the input projection string is in the PROJ format.

Parameters

proj_string (str) – The projection string.

Returns

bool

Return type

True if the string is in the PROJ format