0
# Database Operations
1

2
PyProj provides comprehensive access to the PROJ database for querying coordinate reference systems, transformations, units, and spatial reference metadata. These functions enable discovery and validation of CRS codes, authority information, and transformation operations.
3

4
## Capabilities
5

6
### Authority and Code Management
7

8
Query available authorities and their coordinate reference system codes with filtering options.
9

10
```python { .api }
11
def get_authorities() -> list[str]:
12
    """
13
    Get list of available CRS authorities in PROJ database.
14

15
    Returns:
16
        List of authority names (e.g., ['EPSG', 'ESRI', 'IAU_2015', 'IGNF', 'OGC'])
17

18
    Note:
19
        Authorities are organizations that maintain coordinate reference system definitions.
20
        EPSG is the most commonly used authority for standard CRS definitions.
21
    """
22

23
def get_codes(
24
    auth_name: str,
25
    pj_type: PJType | str,
26
    allow_deprecated: bool = False
27
) -> list[str]:
28
    """
29
    Get list of codes for specified authority and object type.
30

31
    Args:
32
        auth_name: Authority name (e.g., 'EPSG', 'ESRI')
33
        pj_type: Type of objects to query (CRS, ELLIPSOID, DATUM, etc.)
34
        allow_deprecated: Include deprecated/superseded codes
35

36
    Returns:
37
        List of codes as strings
38

39
    Raises:
40
        ValueError: If authority name or PJ type is invalid
41
    """
42
```
43

44
### CRS Information Queries
45

46
Search and retrieve detailed information about coordinate reference systems with flexible filtering.
47

48
```python { .api }
49
def query_crs_info(
50
    auth_name: str | None = None,
51
    pj_types: list[PJType] | None = None,
52
    area_of_interest: AreaOfInterest | None = None,
53
    contains: bool = False,
54
    allow_deprecated: bool = False
55
) -> list[CRSInfo]:
56
    """
57
    Query coordinate reference system information from PROJ database.
58

59
    Args:
60
        auth_name: Filter by authority name (None for all authorities)
61
        pj_types: Filter by CRS types (None for all types)
62
        area_of_interest: Geographic area constraint
63
        contains: If True, CRS area must contain AOI; if False, must intersect AOI
64
        allow_deprecated: Include deprecated CRS definitions
65

66
    Returns:
67
        List of CRSInfo objects matching the criteria
68

69
    Note:
70
        Results are sorted by relevance and accuracy for the specified area.
71
    """
72

73
def query_utm_crs_info(
74
    datum_name: str | None = None,
75
    area_of_interest: AreaOfInterest | None = None,
76
    contains: bool = False
77
) -> list[CRSInfo]:
78
    """
79
    Query UTM coordinate reference systems from PROJ database.
80

81
    Args:
82
        datum_name: Filter by datum name (e.g., 'WGS 84', 'NAD83')
83
        area_of_interest: Geographic area constraint for UTM zone selection
84
        contains: If True, UTM zone must contain AOI; if False, must intersect AOI
85

86
    Returns:
87
        List of CRSInfo objects for UTM zones matching criteria
88

89
    Note:
90
        Automatically selects appropriate UTM zones based on area of interest.
91
        Results include both northern and southern hemisphere zones if applicable.
92
    """
93
```
94

95
### Units and Measurement Systems
96

97
Access unit definitions and conversion factors for coordinate systems and measurements.
98

99
```python { .api }
100
def get_units_map(
101
    auth_name: str | None = None,
102
    category: str | None = None,
103
    allow_deprecated: bool = False
104
) -> dict[str, Unit]:
105
    """
106
    Get dictionary of available units from PROJ database.
107

108
    Args:
109
        auth_name: Filter by authority name (None for all authorities)
110
        category: Filter by unit category ('linear', 'angular', 'scale', 'time')
111
        allow_deprecated: Include deprecated unit definitions
112

113
    Returns:
114
        Dictionary mapping unit names to Unit objects
115

116
    Note:
117
        Units include linear units (meters, feet), angular units (degrees, radians),
118
        and other measurement units used in coordinate system definitions.
119
    """
120

121
def get_ellps_map() -> dict[str, dict[str, float]]:
122
    """
123
    Get dictionary of ellipsoid parameters.
124

125
    Returns:
126
        Dictionary mapping ellipsoid names to parameter dictionaries
127
        containing 'a' (semi-major axis), 'b' (semi-minor axis), 
128
        and other ellipsoid parameters
129

130
    Note:
131
        Provides parameters for standard ellipsoids like WGS84, GRS80, Clarke 1866, etc.
132
        Values are in meters for linear dimensions.
133
    """
134

135
def get_prime_meridians_map() -> dict[str, str]:
136
    """
137
    Get dictionary of prime meridian definitions.
138

139
    Returns:
140
        Dictionary mapping prime meridian names to longitude values
141

142
    Note:
143
        Most common prime meridian is Greenwich (0°).
144
        Historical data may reference other prime meridians.
145
    """
146

147
def get_proj_operations_map() -> dict[str, str]:
148
    """
149
    Get dictionary of available PROJ operations.
150

151
    Returns:
152
        Dictionary mapping operation names to descriptions
153

154
    Note:
155
        Includes map projections, datum transformations, and coordinate conversions
156
        available in the current PROJ installation.
157
    """
158
```
159

160
### Database Metadata
161

162
Access metadata about the PROJ database installation and version information.
163

164
```python { .api }
165
def get_database_metadata(key: str) -> str | None:
166
    """
167
    Get metadata value from PROJ database.
168

169
    Args:
170
        key: Metadata key to retrieve
171

172
    Returns:
173
        Metadata value as string, or None if key not found
174

175
    Note:
176
        Common keys include version information, update timestamps,
177
        and database configuration details.
178
    """
179
```
180

181
## Usage Examples
182

183
### Discovering Available Authorities and Codes
184

185
```python
186
from pyproj.database import get_authorities, get_codes, PJType
187

188
# Get all available authorities
189
authorities = get_authorities()
190
print(f"Available authorities: {authorities}")
191

192
# Get EPSG coordinate reference system codes
193
epsg_crs_codes = get_codes('EPSG', PJType.CRS)
194
print(f"Number of EPSG CRS codes: {len(epsg_crs_codes)}")
195
print(f"First 10 codes: {epsg_crs_codes[:10]}")
196

197
# Get ellipsoid codes from different authorities
198
epsg_ellipsoids = get_codes('EPSG', PJType.ELLIPSOID)
199
esri_ellipsoids = get_codes('ESRI', PJType.ELLIPSOID, allow_deprecated=True)
200

201
print(f"EPSG ellipsoids: {len(epsg_ellipsoids)}")
202
print(f"ESRI ellipsoids (including deprecated): {len(esri_ellipsoids)}")
203

204
# Get datum codes
205
datum_codes = get_codes('EPSG', PJType.DATUM)
206
print(f"EPSG datum codes: {datum_codes[:5]}")
207
```
208

209
### Searching for Coordinate Reference Systems
210

211
```python
212
from pyproj.database import query_crs_info, AreaOfInterest, PJType
213

214
# Search for CRS in specific geographic area (Texas)
215
texas_aoi = AreaOfInterest(
216
    west_lon_degree=-106.5,
217
    south_lat_degree=25.8,
218
    east_lon_degree=-93.5,
219
    north_lat_degree=36.5
220
)
221

222
# Find all CRS for Texas area
223
texas_crs = query_crs_info(area_of_interest=texas_aoi)
224
print(f"CRS options for Texas: {len(texas_crs)}")
225

226
# Show details for first few results
227
for crs_info in texas_crs[:5]:
228
    print(f"Code: {crs_info.auth_name}:{crs_info.code}")
229
    print(f"Name: {crs_info.name}")
230
    print(f"Type: {crs_info.type}")
231
    print(f"Deprecated: {crs_info.deprecated}")
232
    print("---")
233

234
# Search for projected CRS only
235
projected_crs = query_crs_info(
236
    area_of_interest=texas_aoi,
237
    pj_types=[PJType.PROJECTED_CRS],
238
    contains=True  # CRS area must fully contain Texas
239
)
240
print(f"Projected CRS containing Texas: {len(projected_crs)}")
241
```
242

243
### Finding UTM Zones
244

245
```python
246
from pyproj.database import query_utm_crs_info, AreaOfInterest
247

248
# Find UTM zones for New York area
249
ny_aoi = AreaOfInterest(
250
    west_lon_degree=-74.5,
251
    south_lat_degree=40.5,
252
    east_lon_degree=-73.5,
253
    north_lat_degree=41.0
254
)
255

256
utm_zones = query_utm_crs_info(
257
    area_of_interest=ny_aoi,
258
    datum_name='WGS 84'
259
)
260

261
print(f"UTM zones for New York area:")
262
for utm_info in utm_zones:
263
    print(f"  {utm_info.auth_name}:{utm_info.code} - {utm_info.name}")
264

265
# Find UTM zones globally for specific datum
266
all_utm_nad83 = query_utm_crs_info(datum_name='NAD83')
267
print(f"All NAD83 UTM zones: {len(all_utm_nad83)}")
268
```
269

270
### Working with Units and Parameters
271

272
```python
273
from pyproj.database import get_units_map, get_ellps_map, get_prime_meridians_map
274

275
# Get linear units
276
linear_units = get_units_map(category='linear')
277
print("Common linear units:")
278
for name, unit in list(linear_units.items())[:10]:
279
    print(f"  {name}: {unit.conv_factor} meters")
280

281
# Get angular units
282
angular_units = get_units_map(category='angular')
283
print("\nAngular units:")
284
for name, unit in list(angular_units.items())[:5]:
285
    print(f"  {name}: {unit.conv_factor} radians")
286

287
# Get ellipsoid parameters
288
ellipsoids = get_ellps_map()
289
wgs84_params = ellipsoids.get('WGS84', {})
290
grs80_params = ellipsoids.get('GRS80', {})
291

292
print(f"\nWGS84 ellipsoid:")
293
print(f"  Semi-major axis: {wgs84_params.get('a', 'N/A')} m")
294
print(f"  Semi-minor axis: {wgs84_params.get('b', 'N/A')} m")
295
print(f"  Flattening: {wgs84_params.get('f', 'N/A')}")
296

297
# Get prime meridians
298
prime_meridians = get_prime_meridians_map()
299
print(f"\nPrime meridians:")
300
for name, longitude in list(prime_meridians.items())[:5]:
301
    print(f"  {name}: {longitude}")
302
```
303

304
### Database Metadata and Versioning
305

306
```python
307
from pyproj.database import get_database_metadata, get_proj_operations_map
308

309
# Get database metadata
310
try:
311
    db_version = get_database_metadata('DATABASE.VERSION')
312
    print(f"PROJ database version: {db_version}")
313
except:
314
    print("Database version not available")
315

316
# Get available operations
317
operations = get_proj_operations_map()
318
print(f"Available PROJ operations: {len(operations)}")
319

320
# Show some projection operations
321
projection_ops = {k: v for k, v in operations.items() 
322
                 if 'projection' in v.lower()}
323
print(f"\nProjection operations:")
324
for name, desc in list(projection_ops.items())[:5]:
325
    print(f"  {name}: {desc}")
326
```
327

328
### Authority-Specific Searches
329

330
```python
331
from pyproj.database import query_crs_info, get_codes, PJType
332

333
# Compare EPSG vs ESRI CRS options
334
epsg_geographic = query_crs_info(
335
    auth_name='EPSG',
336
    pj_types=[PJType.GEOGRAPHIC_2D_CRS, PJType.GEOGRAPHIC_3D_CRS]
337
)
338

339
esri_geographic = query_crs_info(
340
    auth_name='ESRI', 
341
    pj_types=[PJType.GEOGRAPHIC_2D_CRS, PJType.GEOGRAPHIC_3D_CRS]
342
)
343

344
print(f"EPSG geographic CRS: {len(epsg_geographic)}")
345
print(f"ESRI geographic CRS: {len(esri_geographic)}")
346

347
# Find deprecated CRS that have been superseded
348
all_epsg_crs = query_crs_info(
349
    auth_name='EPSG',
350
    allow_deprecated=True
351
)
352

353
deprecated_crs = [crs for crs in all_epsg_crs if crs.deprecated]
354
print(f"Deprecated EPSG CRS: {len(deprecated_crs)}")
355

356
# Show some deprecated entries
357
print("Examples of deprecated CRS:")
358
for crs_info in deprecated_crs[:3]:
359
    print(f"  {crs_info.code}: {crs_info.name}")
360
```
361

362
### Regional CRS Discovery
363

364
```python
365
from pyproj.database import query_crs_info, AreaOfInterest
366

367
# Find appropriate CRS for different regions
368
regions = {
369
    'California': AreaOfInterest(-124.5, 32.5, -114.0, 42.0),
370
    'France': AreaOfInterest(-5.5, 42.0, 8.5, 51.5),
371
    'Australia': AreaOfInterest(112.0, -44.0, 154.0, -10.0)
372
}
373

374
for region_name, aoi in regions.items():
375
    regional_crs = query_crs_info(
376
        area_of_interest=aoi,
377
        pj_types=[PJType.PROJECTED_CRS],
378
        contains=False  # Intersects the region
379
    )
380
    
381
    print(f"\n{region_name} - Top 3 projected CRS:")
382
    for crs_info in regional_crs[:3]:
383
        area = crs_info.area_of_use
384
        area_desc = f"({area.west:.1f}, {area.south:.1f}, {area.east:.1f}, {area.north:.1f})" if area else "No area info"
385
        print(f"  {crs_info.auth_name}:{crs_info.code} - {crs_info.name}")
386
        print(f"    Area: {area_desc}")
387
```
388

389
## Types
390

391
```python { .api }
392
# Information structures
393
class CRSInfo:
394
    """Information about a coordinate reference system."""
395
    auth_name: str  # Authority name (e.g., 'EPSG')
396
    code: str       # Authority code (e.g., '4326')
397
    name: str       # CRS name
398
    type: str       # CRS type description
399
    deprecated: bool # Whether CRS is deprecated
400
    area_of_use: AreaOfUse | None  # Geographic area of use
401
    projection_method_name: str | None  # Projection method for projected CRS
402

403
class Unit:
404
    """Information about a measurement unit."""
405
    auth_name: str      # Authority name
406
    code: str           # Unit code
407
    name: str           # Unit name
408
    category: str       # Unit category ('linear', 'angular', etc.)
409
    conv_factor: float  # Conversion factor to base unit
410
    proj_short_name: str | None  # PROJ short name
411
    deprecated: bool    # Whether unit is deprecated
412

413
# Enumeration for PROJ object types
414
class PJType(Enum):
415
    """Types of objects in PROJ database."""
416
    UNKNOWN = "UNKNOWN"
417
    ELLIPSOID = "ELLIPSOID"
418
    PRIME_MERIDIAN = "PRIME_MERIDIAN"
419
    DATUM = "DATUM"
420
    CRS = "CRS"
421
    GEOGRAPHIC_CRS = "GEOGRAPHIC_CRS"
422
    GEOGRAPHIC_2D_CRS = "GEOGRAPHIC_2D_CRS"  
423
    GEOGRAPHIC_3D_CRS = "GEOGRAPHIC_3D_CRS"
424
    GEOCENTRIC_CRS = "GEOCENTRIC_CRS"
425
    PROJECTED_CRS = "PROJECTED_CRS"
426
    VERTICAL_CRS = "VERTICAL_CRS"
427
    COMPOUND_CRS = "COMPOUND_CRS"
428
    ENGINEERING_CRS = "ENGINEERING_CRS"
429
    BOUND_CRS = "BOUND_CRS"
430
    OTHER_CRS = "OTHER_CRS"
431
    COORDINATE_OPERATION = "COORDINATE_OPERATION"
432
    CONVERSION = "CONVERSION"
433
    TRANSFORMATION = "TRANSFORMATION"
434
    CONCATENATED_OPERATION = "CONCATENATED_OPERATION"
435
    OTHER_COORDINATE_OPERATION = "OTHER_COORDINATE_OPERATION"
436

437
# Area of interest for geographic filtering
438
class AreaOfInterest:
439
    """Geographic bounding box for CRS queries."""
440
    west_lon_degree: float   # Western boundary longitude
441
    south_lat_degree: float  # Southern boundary latitude
442
    east_lon_degree: float   # Eastern boundary longitude  
443
    north_lat_degree: float  # Northern boundary latitude
444
```