Order API client support for multiple fallback bundle(s)

[ceholden]

Is your feature request related to a problem? Please describe.

It would be very convenient for us if the Orders API client in this package supported more than one "fallback bundle(s)". The API documentation and our experience using the Order API directly suggest that this is possible, so it would be great to have support from this Python client.

The API documentation suggests we can supply multiple "alternative bundle(s)",

To specify a fallback bundle simply add the alternate bundle(s) to the product_bundle field separated by commas.

This example has worked for us in practice - note the 2 fallback bundles,

payload = {
    "name": "mre-test-order",
    "order_type": "partial",
    "products": [
        {
            "item_type": "PSScene",
            "item_ids": ["20250130_035211_69_2516"],
            "product_bundle": "analytic_8b_udm2,analytic_udm2,analytic_3b_udm2",
        }
    ]
}
req = requests.post(
    f"https://api.planet.com//compute/ops/orders/v2",
    json=payload,
    auth=requests.auth.HTTPBasicAuth(PLANET_API_KEY, ""),
)

If I try to add multiple fallback bundles using the SDK as either a list[str] or comma joined list, I get either,

# given as a list[str]
AttributeError: 'list' object has no attribute 'lower'

# pre-joined with a comma
SpecificationException: bundle - 'analytic_udm2,analytic_3b_udm2' is not one of 'analytic_udm2', 'analytic_3b_udm2', 'analytic_8b_udm2', 'visual', 'basic_analytic_udm2', 'basic_analytic_8b_udm2', 'analytic_sr_udm2', 'analytic_8b_sr_udm2'.

Describe the solution you'd like

It seems like this addition could be added without much complexity and in a backwards compatible way. One possible solution would be to update the planet.order_request.product function's call signature to support fallback_bundle: Optional[Union[str, List[str]]] instead of fallback_bundle: Optional[str] and add a little more handling logic for the List[str] case.

For example,

def product(item_ids: List[str],
            product_bundle: str,
            item_type: str,
            fallback_bundle: Optional[Union[str, List[str]]] = None) -> dict:
    ...

    if fallback_bundle is not None:
        fallback_bundles = [fallback_bundle] if isinstance(fallback_bundle, str) else fallback_bundle
        validated_fallback_bundles = []
        for fallback_bundle in fallback_bundles:
            validated_fallback_bundles.append(specs.validate_bundle(
                item_type, fallback_bundle))
        validated_product_bundle = ','.join(
            [validated_product_bundle, *validated_fallback_bundles])
    ...

Describe alternatives you've considered

We have been using the Orders API without this SDK but have to maintain our own tiny client for this API. It would be great to be able to use the Planet SDK as the more authoritative way to interact with this API.

We could also check the Data API for each scene ID, determine the available assets, and then infer which bundle we want to request, but this would be rather complicated and add unnecessary API requests.

Additional context

The use case we have in mind is that we want to simplify our ordering experience for requesting products regardless of how many bands might be available for a scene we found through the search API.

For example, we might search for a long time series of PlanetScope data for a region of interest and find scenes that have either 8-, 4-, or 3-band analytic assets. For our use case we'd like all of these data if possible, so providing a primary and 2 fallback bundles would make this simple.

Thank you for your consideration! If the proposed solution seems good I'd be happy to make a PR for this change.

[asonnenschein]

@ceholden @olepinard thanks for the detailed ticket! Here's a draft MR I created to add better support for fallback bundles to the Orders SDK and CLI: #1106.

[asonnenschein]

#1106 is ready for review!

[asonnenschein]

Ticket is resolved with #1106.