ENH: Added pyproj.database.query_utm_crs_info (#712)

Author: snowman2

docs/api/database.rst

@@ -1,3 +1,5 @@
+.. _database:
+
 Database
 =========
 
@@ -36,3 +38,8 @@ pyproj.database.query_crs_info
 .. autofunction:: pyproj.database.query_crs_info
 
 .. autoclass:: pyproj.database.CRSInfo
+
+pyproj.database.query_utm_crs_info
+-----------------------------------
+
+.. autofunction:: pyproj.database.query_utm_crs_info

docs/examples.rst

@@ -204,6 +204,29 @@ This is just a small subset of what is available.
      Param(name=False northing, auth_name=EPSG, code=8807, value=0.0, unit_name=metre, unit_auth_name=, unit_code=, unit_category=linear)]
 
 
+Find UTM CRS by Latitude and Longitude
+---------------------------------------
+
+.. note:: For more database methods see: :ref:`database`.
+
+.. code-block:: python
+
+    from pyproj import CRS
+    from pyproj.aoi import AreaOfInterest
+    from pyproj.database import query_utm_crs_info
+
+    utm_crs_list = query_utm_crs_info(
+        datum_name="WGS 84",
+        area_of_interest=AreaOfInterest(
+            west_lon_degree=-93.581543,
+            south_lat_degree=42.032974,
+            east_lon_degree=-93.581543,
+            north_lat_degree=42.032974,
+        ),
+    )
+    utm_crs = CRS.from_epsg(utm_crs_list[0].code)
+
+
 Transformations from CRS to CRS
 -------------------------------
 

docs/history.rst

@@ -24,6 +24,7 @@ Change Log
 * ENH: Added support for debugging internal PROJ (pull #696)
 * ENH: Added pathlib support for data directory methods (pull #702)
 * ENH: Added :func:`pyproj.database.query_crs_info` (pull #703)
+* ENH: Added :func:`pyproj.database.query_utm_crs_info` (pull #712)
 * REF: Refactor Proj to inherit from Transformer (issue #624)
 * REF: Added `pyproj.database`, `pyproj.aoi`, and `pyproj.list` modules (pull #703)
 * BUG: Fix handling of polygon holes when calculating area in Geod (pull #686)

pyproj/database.pyx

@@ -261,6 +261,46 @@ def query_crs_info(
     return code_list
 
 
+def query_utm_crs_info(
+    datum_name=None,
+    area_of_interest=None,
+    contains=False,
+ ):
+    """
+    .. versionadded:: 3.0
+
+    Query for EPSG UTM CRS information from the PROJ database.
+
+    Parameters
+    ----------
+    datum_name: Optional[str]
+        The name of the datum in the CRS name ('NAD27', 'NAD83', 'WGS 84', ...).
+    area_of_interest: Optional[AreaOfInterest]
+        Filter returned CRS by the area of interest. Default method is intersection.
+    contains: Optional[bool]
+        Only works if the area of interest is passed in.
+        If True, then only CRS whose area of use entirely contains the specified
+        bounding box will be returned. If False, then only CRS whose area of use
+        intersects the specified bounding box will be returned.
+
+    Returns
+    -------
+    List[CRSInfo]:
+        UTM CRS information from the PROJ database.
+    """
+    projected_crs = query_crs_info(
+        auth_name="EPSG",
+        pj_types=PJType.PROJECTED_CRS,
+        area_of_interest=area_of_interest,
+        contains=contains,
+    )
+    utm_crs = [crs for crs in projected_crs if "UTM zone" in crs.name]
+    if datum_name is None:
+        return utm_crs
+    datum_name = datum_name.replace(" ", "")
+    return [crs for crs in utm_crs if datum_name in crs.name.replace(" ", "")]
+
+
 Unit = namedtuple(
     "Unit",
     [

test/test_database.py

@@ -7,6 +7,7 @@
     get_codes,
     get_units_map,
     query_crs_info,
+    query_utm_crs_info,
 )
 from pyproj.enums import PJType
 
@@ -201,3 +202,46 @@ def test_query_crs_info__aoi_contains():
         assert crs_info.auth_name == "IGNF"
         assert crs_info.type == PJType.PROJECTED_CRS
         assert not crs_info.deprecated
+
+
+@pytest.mark.parametrize("datum_name", ["WGS 84", "WGS84", "NAD27"])
+def test_query_utm_crs_info__aoi_datum_name(datum_name):
+    aoi = BBox(west=-93.581543, south=42.032974, east=-93.581543, north=42.032974)
+    crs_info_list = query_utm_crs_info(
+        datum_name=datum_name,
+        area_of_interest=AreaOfInterest(
+            west_lon_degree=aoi.west,
+            south_lat_degree=aoi.south,
+            east_lon_degree=aoi.east,
+            north_lat_degree=aoi.north,
+        ),
+    )
+    assert len(crs_info_list) == 1
+    crs_info = crs_info_list[0]
+    bbox = BBox(*crs_info.area_of_use.bounds)
+    assert bbox.intersects(aoi)
+    assert "UTM zone" in crs_info.name
+    assert datum_name.replace(" ", "") in crs_info.name.replace(" ", "")
+    assert crs_info.auth_name == "EPSG"
+    assert crs_info.type == PJType.PROJECTED_CRS
+    assert not crs_info.deprecated
+
+
+def test_query_utm_crs_info__aoi_contains():
+    aoi = BBox(west=41, south=50, east=42, north=51)
+    crs_info_list = query_utm_crs_info(
+        area_of_interest=AreaOfInterest(
+            west_lon_degree=aoi.west,
+            south_lat_degree=aoi.south,
+            east_lon_degree=aoi.east,
+            north_lat_degree=aoi.north,
+        ),
+        contains=True,
+    )
+    assert crs_info_list
+    for crs_info in crs_info_list:
+        assert BBox(*crs_info.area_of_use.bounds).contains(aoi)
+        assert "UTM zone" in crs_info.name
+        assert crs_info.auth_name == "EPSG"
+        assert crs_info.type == PJType.PROJECTED_CRS
+        assert not crs_info.deprecated