Skip to content

Catalog

The Catalog class enables access to the UP42 catalog functionality.

catalog = up42.initialize_catalog()

This class also inherits functions from the CatalogBase class.

Scenes

construct_search_parameters()

The construct_search_parameters() function allows you to fill out search parameters when searching for catalog imagery.

The returned data type is dict.

Arguments
Argument Overview
geometry Union[FeatureCollection, Feature, dict, list, GeoDataFrame, Polygon] / required
The geometry of interest.
collections list[str] / required
The geospatial collection names.
start_date str
The start date of the search period in the YYYY-MM-DD format. The default value is 2020-01-01.
end_date str
The end date of the search period in the YYYY-MM-DD format. The default value is 2020-01-30.
limit int
The number of search results to show. Use a value from 1 to 500. The default value is 10.
max_cloudcover int
The maximum cloud coverage, in percentage.
Example
catalog.construct_search_parameters(
    geometry=up42.get_example_aoi(location="Berlin"),
    collections=["phr"],
    start_date="2022-06-01",
    end_date="2022-12-31",
    limit=20,
    max_cloudcover=25,
)

The search() function returns the scenes matching the search parameters.

The returned data type is Union[GeoDataFrame, dict].

Arguments
Argument Overview
search_parameters dict / required
The catalog search parameters.
as_dataframe bool
Determines how to return search results:
  • True: return GeoDataFrame.
  • False: return JSON.
The default value is True.
Example
catalog.search(
    search_parameters=catalog.construct_search_parameters(
        geometry=up42.get_example_aoi(),
        collections=["phr"],
        start_date="2022-06-01",
        end_date="2022-12-31",
        limit=20,
        max_cloudcover=25,
    ),
    as_dataframe=False,
)

download_quicklooks()

The download_quicklooks() function allows you to download low-resolution previews of scenes returned in search results. Visualize quicklooks with map_quicklooks() or plot_quicklooks().

The returned data type is list[str].

Arguments
Argument Overview
image_ids list[str] / required
The scene IDs.
collection str / required
The geospatial collection name.
output_directory Union[str, Path, None]
The file output directory. The default value is the current directory.
Example
catalog.download_quicklooks(
    image_ids=["a4c9e729-1b62-43be-82e4-4e02c31963dd"],
    collection="phr",
    output_directory="/Users/max.mustermann/Desktop/",
)

Orders

construct_order_parameters()

The construct_order_parameters() function allows you to fill out an order form for a new catalog order.

The returned data type is dict.

Arguments
Argument Overview
data_product_id str / required
The data product ID.
image_id str / required
The scene ID.
aoi Union[dict, Feature, FeatureCollection, list, GeoDataFrame, Polygon]
The order AOI.
tags list[str]
A list of tags that categorize the order.
Example
catalog.construct_order_parameters(
    data_product_id="647780db-5a06-4b61-b525-577a8b68bb54",
    image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
    aoi="/Users/max.mustermann/Desktop/aoi.geojson",
    tags=["project-7", "optical"],
)

estimate_order()

The estimate_order() function returns the cost estimate for a catalog order.

The returned data type is int.

Arguments
Argument Overview
order_parameters Union[dict, None] / required
Parameters with which to place an order.
Example
catalog.estimate_order(
    order_parameters=catalog.construct_order_parameters(
        data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99",
        image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
        aoi="/Users/max.mustermann/Desktop/aoi.geojson",
    ),
)

Visualization

To use the visualization functionalities, install the advanced up42-py package.

plot_coverage()

The function is deprecated.

The plot_coverage() function allows you to visualize the coverage of scenes matching the search parameters. Use together with search().

Arguments
Argument Overview
scenes GeoDataFrame / required
The scenes matching the search parameters.
aoi GeoDataFrame
The order AOI.
legend_column str
The column name of scenes to arrange legend entries by ascending order. The default value is sceneId.
figsize tuple[int, int]
The size of the visualization, in inches. The first number is height, the second one is width. The default value is (12, 16).
Example
# Construct search parameters

search_parameters = catalog.construct_search_parameters(
    geometry=up42.get_example_aoi(location="Berlin"),
    collections=["phr"],
    start_date="2022-06-01",
    end_date="2022-12-31",
    limit=5,
    max_cloudcover=25,
)

# Search and plot scene coverage

catalog.plot_coverage(
    scenes=catalog.search(search_parameters),
    geometry=up42.get_example_aoi(location="Berlin"),
    legend_column="cloudCoverage",
    figsize=(14, 18),
)

map_quicklooks()

The function is deprecated.

The map_quicklooks() function allows you to visualize downloaded quicklooks on a Folium map. Use together with search() and download_quicklooks().

The returned data type is folium.Map.

Arguments
Argument Overview
scenes GeoDataFrame / required
The scenes matching the search parameters.
aoi GeoDataFrame
The order AOI.
show_images bool
Determines whether to visualize quicklooks:
  • True: show the quicklooks on the map.
  • False: don't show the quicklook on the map.
The default value is True.
show_features bool
Determines whether to visualize the geometry:
  • True: show the geometry on the map.
  • False: don't show the geometry on the map.
The default value is False.
filepaths list[Union[str, Path]]
The file paths. By default, the last downloaded quicklooks will be used.
name_column str
The column name of scenes that provides the feature name. The default value is id.
save_html Path
Use to specify a path to save the map as an HTML file.
Example
# Conduct search

scenes = catalog.search(
    search_parameters=catalog.construct_search_parameters(
        geometry=up42.get_example_aoi(location="Berlin"),
        collections=["phr"],
        limit=2,
    ),
)

# Download quicklooks

catalog.download_quicklooks(
    image_ids=list(scenes.id),
    collection="phr",
    output_directory="/Users/max.mustermann/Desktop/",
)

# Map quicklooks

catalog.map_quicklooks(
    scenes=scenes,
    aoi="/Users/max.mustermann/Desktop/aoi.geojson",
    show_images=True,
    show_features=True,
    filepaths=[
        "/Users/max.mustermann/Desktop/quicklook_d0a7e38a-0087-48c9-b3f7-8b422388e101.jpg",
        "/Users/max.mustermann/Desktop/quicklook_b7f2c82f-641d-4119-baff-7001a5ceb4f6.jpg",
    ],
    name_column="cloudCoverage",
    save_html="/Users/max.mustermann/Desktop/",
)

plot_quicklooks()

The function is deprecated.

The plot_quicklooks() function allows you to visualize downloaded quicklooks. Use together with search() and download_quicklooks().

Arguments
Argument Overview
figsize tuple[int, int]
The size of the visualization, in inches. The first number is height, the second one is width. The default value is (8, 8).
filepaths Union[list[Union[str, Path]], dict, None]
The file paths. By default, the last downloaded quicklooks will be used.
titles list[str]
The titles for the subplots.
Example
# Conduct search

scenes = catalog.search(
    search_parameters=catalog.construct_search_parameters(
        geometry=up42.get_example_aoi(location="Berlin"),
        collections=["phr"],
        limit=2,
    ),
)

# Download quicklooks

catalog.download_quicklooks(
    image_ids=list(scenes.id),
    collection="phr",
    output_directory="/Users/max.mustermann/Desktop/",
)

# Map quicklooks

catalog.plot_quicklooks(
    figsize=(10, 10),
    filepaths=[
        "/Users/max.mustermann/Desktop/quicklook_d0a7e38a-0087-48c9-b3f7-8b422388e101.jpg",
        "/Users/max.mustermann/Desktop/quicklook_b7f2c82f-641d-4119-baff-7001a5ceb4f6.jpg",
    ],
    titles=["Scene 1", "Scene 2"],
)