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

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

property axis_info

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

New in version 2.2.0.

Returns

Return type

CoordinateOperation

property coordinate_system

New in version 2.2.0.

Returns

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

New in version 2.2.0.

Returns

Return type

Datum

property 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.

Returns

Return type

bool

static 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.

Returns

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

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
Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

static 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.

Returns

Return type

CRS

property geodetic_crs

New in version 2.2.0.

Returns

The 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

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

property is_compound

New in version 3.1.0.

Returns

True if CRS is compound.

Return type

bool

property is_engineering

New in version 2.2.0.

Returns

True if CRS is local/engineering.

Return type

bool

is_exact_same(other: Any, ignore_axis_order: bool = False) → 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.

Returns

Return type

bool

property is_geocentric

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

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

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

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

property name

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

property prime_meridian

New in version 2.2.0.

Returns

The prime meridian object with associated attributes.

Return type

PrimeMeridian

property remarks

New in version 2.4.0.

Returns

Remarks about object.

Return type

str

property scope

New in version 2.4.0.

Returns

Scope of object.

Return type

str

property source_crs

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

Returns

Return type

CRS

property sub_crs_list

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

Returns

Return type

List[CRS]

property target_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.

Returns

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: '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.

Returns

Return type

str

to_json_dict() → dict[source]

New in version 2.4.0.

Convert the object to a JSON dictionary.

Returns

Return type

dict

to_proj4(version: Union[pyproj.enums.ProjVersion, int] = <ProjVersion.PROJ_5: 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.

Returns

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.

Returns

Return type

str

to_wkt(version: Union[pyproj.enums.WktVersion, str] = <WktVersion.WKT2_2019: '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
Returns

Return type

str

property type_name

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

property utm_zone

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.CRS

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.CRS

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

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.CRS

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.CRS

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.CRS

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.CRS

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()

is_wkt

pyproj.crs.is_wkt(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(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