06 — Data access points

The data_access extension connects an instrument to collections exposed by platforms such as Google Earth Engine, Microsoft Planetary Computer, the Copernicus Data Space Ecosystem, and EOPF Sentinel Zarr Samples. This tutorial uses Sentinel-2A MSI to discover the available providers and their collection identifiers.

import pandas as pd
import xeo

instrument = xeo.instruments.MSI_S2A
instrument

Discover available providers

get_data_access() accepts the provider names used by the catalogue: ee, planetary_computer, cdse, and eopf. Calling it with the defaults requests the primary Earth Engine collection.

print("Available extensions:", instrument.extension_names)

providers = ["ee", "planetary_computer", "cdse", "eopf"]
available_providers = [
    provider
    for provider in providers
    if instrument.get_data_access(provider) is not None
]
print("Data access providers:", available_providers)

Get the primary collection ID for each provider

Every provider can identify one access point as primary. The method returns a dictionary containing stac_endpoint, collection, and docs; unavailable values are None.

primary_collection_ids = {}
for provider in providers:
    access = instrument.get_data_access(provider)
    if access is not None:
        primary_collection_ids[provider] = access["collection"]

primary_collection_ids

Select a provider and processing level

The supported processing and product levels are primary, boa, toa, raw, lst, wst, grd, rtc, and slc. A valid combination that is unavailable for the instrument returns None.

print(instrument.get_data_access())
print(instrument.get_data_access("planetary_computer", "boa"))
print(instrument.get_data_access("cdse", "toa"))
print(instrument.get_data_access(processing_level="raw"))

Access product-specific collections

Some instruments expose collections for specialized products. Sentinel-3A SLSTR, for example, provides land surface temperature (lst) and water surface temperature (wst) access points.

slstr = xeo.instruments.SLSTR_S3A

print(slstr.get_data_access("planetary_computer", "lst"))
print(slstr.get_data_access("cdse", "wst"))

List every available access point

Providers may expose several processing levels, such as bottom-of-atmosphere (boa) and top-of-atmosphere (toa) collections. The helper below flattens the extension into a DataFrame while ignoring provider-level fields such as stac_endpoint.

data_access = instrument.extensions.get("data_access", {})


def data_access_table(instrument):
    rows = []
    data_access = instrument.extensions.get("data_access", {})

    for provider, provider_metadata in data_access.items():
        stac_endpoint = provider_metadata.get("stac_endpoint")
        for access_point, access_metadata in provider_metadata.items():
            if not isinstance(access_metadata, dict):
                continue
            if "collection" not in access_metadata:
                continue

            rows.append(
                {
                    "provider": provider,
                    "access_point": access_point,
                    "collection": access_metadata["collection"],
                    "stac_endpoint": stac_endpoint,
                    "docs": access_metadata.get("docs"),
                }
            )

    return pd.DataFrame(rows)


access_points = data_access_table(instrument)
access_points

The resulting table makes it easy to select collection IDs by provider or processing level.

access_points.loc[
    access_points["access_point"].isin(["boa", "toa"]),
    ["provider", "access_point", "collection"],
].sort_values(["provider", "access_point"])

Get STAC endpoints

STAC-based providers include a provider-level endpoint. Google Earth Engine uses its own collection identifiers and therefore has no stac_endpoint here.

stac_endpoints = {}
for provider in providers:
    access = instrument.get_data_access(provider)
    if access is not None and access["stac_endpoint"] is not None:
        stac_endpoints[provider] = access["stac_endpoint"]

stac_endpoints

Reuse the workflow with other instruments

First discover which instruments provide the extension, then pass any of them to data_access_table().

instruments_with_data_access = [
    item.id
    for item in xeo.instruments.values()
    if "data_access" in item.extension_names
]
print(instruments_with_data_access)

data_access_table(xeo.instruments.ASTER)