Quick Start Guide

This guide helps you get started with geoextent quickly through practical examples.

Installation

Install geoextent via pip:

pip install geoextent

Requirements: Python 3.10+ and GDAL 3.11.x

For detailed installation instructions including system dependencies and Docker setup, see Installing geoextent.

Basic Usage

Extract from a Local File

Extract spatial extent from a GeoJSON file:

python -m geoextent -b --quiet tests/testdata/geojson/muenster_ring_zeit.geojson

The CLI always emits a GeoJSON FeatureCollection with [lon, lat] coordinates per RFC 7946:

{"type": "FeatureCollection", "features": [{"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[7.6016807556152335, 51.94881477206191], [7.647256851196289, 51.94881477206191], [7.647256851196289, 51.974624029877454], [7.6016807556152335, 51.974624029877454], [7.6016807556152335, 51.94881477206191]]]}, "properties": {}}], "geoextent_extraction": {"version": "<...>", "inputs": ["tests/testdata/geojson/muenster_ring_zeit.geojson"], "statistics": {"files_processed": 1, "files_with_extent": 1, "total_size": "<...>"}, "format": "geojson", "geoextent_handler": "handle_vector", "extent_type": "bounding_box"}}

Extract from a Directory

Process all geospatial files in a directory:

python -m geoextent -b tests/testdata/geojson/

Geoextent automatically discovers supported file formats and returns a merged bounding box covering all files.

Extract from Research Repository

Extract directly from a Zenodo dataset using its DOI:

python -m geoextent -b -t https://doi.org/10.5281/zenodo.4593540

Or use the short DOI format:

python -m geoextent -b -t 10.5281/zenodo.4593540

Supported repositories include Zenodo, Figshare, Dryad, PANGAEA, OSF, Dataverse, GFZ Data Services, Pensoft, and TU Dresden Opara. See Content Providers for complete list.

Extract from a Remote GeoTIFF

Extract extent directly from a remote Cloud Optimized GeoTIFF (COG) URL — only the file header is downloaded:

python -m geoextent -b https://raw.githubusercontent.com/GeoTIFF/test-data/main/files/gfw-azores.tif

Extract from Multiple Repositories

Process multiple repositories in a single command:

python -m geoextent -b -t \
    10.5281/zenodo.4593540 \
    10.25532/OPARA-581 \
    https://osf.io/abc123/

Returns a merged bounding box covering all resources, similar to directory extraction.

Python API

Single File Extraction

import geoextent.lib.extent as geoextent

result = geoextent.from_file(
    'tests/testdata/geojson/muenster_ring_zeit.geojson',
    bbox=True, tbox=True, show_progress=False,
)
print(result['envelope'])  # [minlat, minlon, maxlat, maxlon] (native EPSG:4326)
print(result['tbox'])

[51.94881477206191, 7.6016807556152335, 51.974624029877454, 7.647256851196289]
['2018-11-14', '2018-11-14']

The result dict uses canonical keys: envelope (4-tuple), geometry (GeoJSON Polygon), convex_hull (bool), and tbox (date strings). Output is always in EPSG:4326 so there is no crs field. Pass legacy=True to receive the envelope in traditional GIS order [minlon, minlat, maxlon, maxlat].

Directory Extraction

result = geoextent.from_directory('data/', bbox=True, tbox=True)
print(result['envelope'])  # Merged envelope covering all files

Remote Repository Extraction

# Single repository
result = geoextent.from_remote('10.5281/zenodo.4593540', bbox=True)

# Multiple repositories
identifiers = ['10.5281/zenodo.4593540', '10.25532/OPARA-581']
result = geoextent.from_remote(identifiers, bbox=True, tbox=True)
print(result['envelope'])  # Merged envelope covering all resources

Common Options

Bounding Box and Temporal Extent

Extract both spatial and temporal extents:

python -m geoextent -b -t data.geojson

  • -b or --bbox - Extract bounding box

  • -t or --tbox - Extract temporal extent

Convex Hull

Extract a more precise convex hull instead of rectangular bounding box:

python -m geoextent -b --convex-hull data.geojson

Useful for irregularly shaped data where a rectangular box would include large empty areas.

Output Formats

Export spatial extent in different formats:

# GeoJSON (default)
python -m geoextent -b data.geojson

# Well-Known Text
python -m geoextent -b --format wkt data.geojson

# Well-Known Binary
python -m geoextent -b --format wkb data.geojson

Interactive Visualization

Open the extracted extent in your browser using geojson.io:

python -m geoextent -b --browse data.geojson

Next Steps