SearchResult¶
The SearchResult class is the primary return type from abovepy.search(). It wraps a GeoDataFrame with workflow methods for download, preview, export, and comparison.
Quick Reference¶
import abovepy
result = abovepy.search(county="Franklin", product="dem_phase3")
# Inspect
result.count # number of tiles
result.estimate_size() # {'tile_count': 42, 'avg_tile_mb': 5.0, 'total_mb': 210.0}
result.bbox # bounding box of all tiles
# Workflow
paths = result.download("./data") # concurrent download
url = result.preview() # preview image URL
m = result.map() # interactive notebook map
vrt = result.mosaic(output="out.vrt") # mosaic tiles
# Export
gdf = result.to_geodataframe() # raw GeoDataFrame
result.to_geoparquet("tiles.parquet") # GeoParquet
geojson = result.to_geojson() # GeoJSON string
# Compare
phase2 = abovepy.search(county="Franklin", product="dem_phase2")
overlap = result.compare(phase2) # spatial overlap
# Subset
filtered = result.filter_by_bbox((-84.9, 38.15, -84.8, 38.25))
first_5 = result.head(5)
API Reference¶
SearchResult
¶
Result of an abovepy search, wrapping tile metadata with workflow methods.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
Tile index with columns: tile_id, product, datetime, geometry, asset_url, collection_id. |
required |
product
|
Product
|
The product definition used for this search. |
required |
query_params
|
dict
|
Original search parameters (for regenerating URLs and repr). |
required |
Examples:
>>> result = abovepy.search(county="Franklin", product="dem_phase3")
>>> result.count
42
>>> result.estimate_size()
{'tile_count': 42, 'avg_tile_mb': 5.0, 'total_mb': 210.0}
>>> paths = result.download("./data")
>>> result.preview()
'https://...'
tiles
property
¶
The raw tile index as a GeoDataFrame.
product
property
¶
The product definition for this search.
query_params
property
¶
The original search parameters.
bbox
property
¶
Bounding box (xmin, ymin, xmax, ymax) of all result tiles.
count
property
¶
Number of tiles in the result.
empty
property
¶
Whether the result contains no tiles.
estimate_size()
¶
Estimate the total download size of the result set.
Returns:
| Type | Description |
|---|---|
dict
|
Keys: tile_count, avg_tile_mb, total_mb. |
download(output_dir='.', overwrite=False, max_workers=4)
¶
Download all tiles in this result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_dir
|
str or Path
|
Destination directory. Default current directory. |
'.'
|
overwrite
|
bool
|
Overwrite existing files. Default False. |
False
|
max_workers
|
int
|
Number of concurrent download threads. Default 4. |
4
|
Returns:
| Type | Description |
|---|---|
list[Path]
|
Paths to downloaded files. |
preview(**kwargs)
¶
Generate a preview image URL for this result's area.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Extra parameters passed to |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
Preview image URL. |
map(**kwargs)
¶
Display an interactive map of this result in a notebook.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Extra parameters passed to |
{}
|
Returns:
| Type | Description |
|---|---|
Map
|
|
mosaic(output=None, bbox=None, crs=None)
¶
Mosaic downloaded tiles into a single raster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output
|
str or Path
|
Output path. |
None
|
bbox
|
tuple
|
Clip to bounding box. |
None
|
crs
|
str
|
Reproject to this CRS. |
None
|
Returns:
| Type | Description |
|---|---|
Path or tuple[ndarray, dict]
|
|
to_geodataframe()
¶
Return the raw GeoDataFrame.
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
|
to_geoparquet(output)
¶
Export tiles to GeoParquet.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output
|
str or Path
|
Output file path. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
|
to_geojson()
¶
Serialize tiles to GeoJSON string.
Returns:
| Type | Description |
|---|---|
str
|
GeoJSON FeatureCollection. |
compare(other)
¶
Compare spatial overlap between two search results.
Useful for phase comparison workflows (e.g., Phase 2 vs Phase 3 coverage for the same area).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
SearchResult
|
Another search result to compare against. |
required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Spatial join showing overlapping tiles from both results,
with columns suffixed |
provenance()
¶
Generate provenance metadata for this search result.
Useful for survey/engineering deliverables that require source documentation, acquisition dates, and data lineage.
Returns:
| Type | Description |
|---|---|
dict
|
Keys: product, collection_id, source_program, acquisition_period, native_crs, tile_count, estimated_size_mb, bbox, query_params, asset_urls, phases. |
validate()
¶
Check for data quality issues in this search result.
Returns a list of human-readable warning strings. An empty list means no issues were detected.
Returns:
| Type | Description |
|---|---|
list[str]
|
Warning messages. Empty if no issues found. |
filter_by_bbox(bbox)
¶
Filter tiles to those intersecting a bounding box.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
tuple
|
(xmin, ymin, xmax, ymax) in EPSG:4326. |
required |
Returns:
| Type | Description |
|---|---|
SearchResult
|
Filtered result. |
head(n=5)
¶
Return the first n tiles.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of tiles. Default 5. |
5
|
Returns:
| Type | Description |
|---|---|
SearchResult
|
|
__iter__()
¶
Iterate over tiles as dicts (excludes geometry).