Home / Python SDK / Python SDK reference

Catalog in SDK

Beta

Search the catalog for archive scenes using the SDK.

Overview

Search the catalog for archive scenes with PySTAC.

View repository

PySTAC authentication

After you’ve authenticated with the SDK, create a PySTAC client connection to the catalog.

Python
catalog = up42.catalog_client()

The code samples on this page require an initialized catalog object.

Class: Collection

A PySTAC class that represents a catalog collection. See the PySTAC documentation for more information.

A catalog collection is an archived dataset available for immediate ordering.

Attributes

AttributeDescription
id

str

The catalog collection ID in a name format.

title

Optional[str]

The title of the collection.

description

Optional[str]

The description of the collection.

Methods

get_collections

Retrieves all catalog collections. Returns Iterator[Collection]. Use itertools.islice to offset and limit the results. See the PySTAC documentation for more information.

Python
from itertools import islice


# Search for catalog collections
collections = catalog.get_collections()


# Define output
for collection in islice(collections, 0, 5): # Print first 5 results
    print(f"- Collection ID: {collection.id}")
    print(f"  Title:           {collection.title}")
    print()

get_collection

Retrieves a specific catalog collection. Returns Collection. See the PySTAC documentation for more information.

ParameterDescription
collection_id

str

The catalog collection ID in a name format.
Python
# Fetch a catalog collection
collection = catalog.get_collection("phr")


# Define output
print(f"Collection ID: {collection.id}")
print(f"Title:           {collection.title}")
print(f"Description:     {collection.description}")

Class: Item

A PySTAC class that represents an archive scene. See the PySTAC documentation for more information.

A STAC item is an individual scene that represents inseparable data and metadata. A STAC item has a unique spatiotemporal extent, that is, has one AOI and acquisition time in its characteristics.

Attributes

AttributeDescription
id

str

The scene ID.

collection

Optional[str]

The name of the geospatial collection the scene belongs to.

geometry

Optional[Union[geojson.Polygon, geojson.MultiPolygon]]

The scene’s geometry.

bbox

Optional[list[float]]

The bounding box that encloses the scene’s geometry, in the [min longitude, min latitude, max longitude, max latitude] order.

datetime

Optional[datetime.datetime]

The date and time when the sensor acquired the scene.

properties

dict

Additional scene metadata:

  • eo:cloud_cover: The cloud coverage percentage.
  • gsd: The nominal resolution of the data, in meters.
assets

dict[str, Asset]

Geospatial assets linked to this scene, such as a preview image.

Methods

Retrieves catalog scenes matching search criteria. Returns ItemSearch. Use itertools.islice to offset and limit the results. See the PySTAC documentation for more information.

ParameterDescription
collections

Optional[list[str]]

The geospatial collections whose scenes you want to include in search results. When omitted, the search returns all catalog collections.

bbox

Optional[list[float]]

A bounding box in the [min longitude, min latitude, max longitude, max latitude] format. Returns scenes that intersect this rectangle and may not fully cover it. Use only if intersects isn’t specified.

intersects

Optional[geojson.Polygon]

A polygon in the GeoJSON format. Use only if bbox isn’t specified.

datetime

Optional[str]

The date and time when the sensor acquired the scene. A closed interval uses YYYY-MM-DD/YYYY-MM-DD. An open interval uses double-dots, for example 2022-06-01/...

filter

Optional[dict]

A CQL2 filter that consists of arguments and operators. To filter by cloud coverage, compare the eo:cloud_cover property with a percentage.

ids

Optional[list[str]]

The IDs of scenes you want to include in search results.

max_items

Optional[int]

The maximum number of scenes to return.
Python
from itertools import islice


# Define search geometry
10 collapsed lines
geometry = {
    "type": "Polygon",
    "coordinates": [[
        [13.369713, 52.452327],
        [13.369713, 52.470760],
        [13.339159, 52.470760],
        [13.339159, 52.452327],
        [13.369713, 52.452327]
    ]]
}


# Search for scenes
items = catalog.search(
    collections=["spot", "phr"],
    intersects=geometry,
    datetime="2022-06-01/2022-12-31",
    filter={
        "op": "<",
        "args": [
            {"property": "eo:cloud_cover"},
            20,
        ],
    },
)


# Define output
for item in islice(items.items(), 0, 5): # Print first 5 results
    print(f"- Scene ID:       {item.id}")
    print(f"  Collection:     {item.collection}")
    print(f"  Acquisition:    {item.datetime}")
    print(f"  Cloud coverage: {item.properties.get('eo:cloud_cover')}%")
    print(f"  Resolution:     {item.properties.get('gsd')} m")
    print()

Class: Asset

A PySTAC class that represents a scene asset. See the PySTAC documentation for more information.

Attributes

AttributeDescription
href

str

The URL of the scene asset.

title

Optional[str]

The asset title.

description

Optional[str]

The asset description.

media_type

Optional[str]

The asset data type.

roles

Optional[list[str]]

The asset type:

  • overview: A low-resolution, simplified view of the scene.
  • thumbnail: A lightweight version of the preview image that might differ in coverage or orientation.

Properties

file.url

Retrieves the signed URL for a scene asset. The URL is valid for 5 minutes. Returns str. Uses the file helper object.

Python
# Define search geometry
geometry = {
    "type": "Polygon",
10 collapsed lines
    "coordinates": [[
        [13.369713, 52.452327],
        [13.369713, 52.470760],
        [13.339159, 52.470760],
        [13.339159, 52.452327],
        [13.369713, 52.452327]
    ]]
}


# Search for scenes
items = catalog.search(
    collections=["phr"],
    intersects=geometry,
    datetime="2022-06-01/2022-12-31",
    max_items=20,
)


# Select the first scene that provides a quicklook
item = next((item for item in items.items() if "quicklook" in item.assets), None)


# Define output
if item:
    print(f"The signed URL: {item.assets['quicklook'].file.url}")
else:
    print("No quicklook found.")

Methods

file.download

Downloads a scene asset. Returns pathlib.Path. Uses the file helper object.

ParameterDescription
output_directory

Union[str, pathlib.Path]

The file output directory.
Python
import pathlib


# Define search geometry
10 collapsed lines
geometry = {
    "type": "Polygon",
    "coordinates": [[
        [13.369713, 52.452327],
        [13.369713, 52.470760],
        [13.339159, 52.470760],
        [13.339159, 52.452327],
        [13.369713, 52.452327]
    ]]
}


# Search for scenes
items = catalog.search(
    collections=["phr"],
    intersects=geometry,
    datetime="2022-06-01/2022-12-31",
    max_items=20,
)


# Select the first scene that provides a quicklook
item = next((item for item in items.items() if "quicklook" in item.assets), None)


# Download the quicklook
output_directory = pathlib.Path("quicklooks")
output_directory.mkdir(exist_ok=True)


if item:
    downloaded_file_path = item.assets["quicklook"].file.download(output_directory)
    print(f"Quicklook downloaded to '{downloaded_file_path}'.")
else:
    print("No quicklook found.")

Last updated: