Skip to main content

Sources

Scenes Source Type​

Scene item IDs from the Data API can be ordered through the Orders API. A scenes order in the Orders API includes a source type, a set of item IDs, an item type, and a product bundle — a predefined set of imagery and metadata assets.

Parameters​

ParameterTypeRequiredDescription
nameStringRequiredA name for the order.
source_typeStringRequiredThe product you are choosing to order (scenes in this case).
item_idsList[String]RequiredCatalog items of the scenes you wish to download. You can find the item_ids by creating a search in the Data API or Planet Explorer.
item_typeStringRequiredRepresents the sensors and processing characteristics of a catalog item, like PSScene or SkySatCollect. More details on item types here.
product_bundleStringRequiredA predefined group of asset_types. Details on product bundles here.
{
    "name": "simple order",
    "source_type": "scenes",
    "products":[
        {
            "item_ids":[
                "20220304_093300_37_2430",
                "20220304_093257_90_2430",
            ],
            "item_type":"PSScene",
            "product_bundle":"analytic_udm2"
        }
    ]
}

Order Types​

The Orders API supports two order types: full and partial.

full order type​

By default, all orders are full if no order_type is specified. A full order type will fail if complete product bundles (all required asset_types) are not available for all items included. This is common for analytic_sr bundles due to publishing delays.

partial order type​

A partial order type will deliver product bundles for all items included in the order which have all the complete product bundles (all required asset_types). In the analytic_udm2 product bundle example provided above, a partial order would deliver all the items in the order which have all analytic_udm2 assets, and omit delivery of items which are missing any of the required assets.

A partial order type will also omit delivery of items which the requester lacks permissions to access and provide error hints for items which failed to deliver, as long as at least one item bundle is deliverable.

An important note here is that the Orders API will always deliver all or none of the assets in the product bundle for an item. It will never deliver partial product bundles – only partial orders, with complete product bundles for the items which were delivered.

{
    "name":"partial order",
    "source_type": "scenes",
    "order_type": "partial",
    "products":[
        {
            "item_ids":[
                "20220304_093300_37_2430",
                "20220304_093257_90_2430",
            ],
            "item_type":"PSScene",
            "product_bundle":"analytic_udm2"
        }
    ]
}

Supported Tools​

All tools are supported for scenes orders, except merge.

Fallback Bundles​

A fallback bundle is a product bundle that the Orders API will deliver if the first choice product bundle fails for any reason (asset availability, permissions, etc.). For example, a fallback bundle could be used to deliver an analytic_udm2 bundle for an item, if all the assets in the analytic_8b_udm2 bundle are not available.

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

"products": [
    {
        "item_ids":[
            "20220304_093300_37_2430",
            "20220304_093257_90_2430",
        ],
        "item_type":"PSScene",
        "product_bundle":"analytic_8b_udm2,analytic_udm2"
    }
]

Ordering Multiple Item Types​

To order items of multiple item_types, you can add other products set within the array of the products block.

note

Multiple item types (such as PlanetScope or SkySat) can be included in the same order as long as there is a plan that enables access to all of those item types.

{
    "name":"multiple item types order",
    "source_type": "scenes",
    "products":[
        {
            "item_ids":[
                "20220306_094818_22_2276","20220306_094815_93_2276"
            ],
            "item_type":"PSScene",
            "product_bundle":"analytic_udm2"
        },
        {
            "item_ids": [
                "20171226_222055_6021709_RapidEye-3"
            ],
            "item_type": "REOrthoTile",
            "product_bundle": "analytic"
        }
    ]
}

Basemaps Source Type​

Planet Basemaps may be ordered through the Orders API. To read about the different kinds of basemaps and their specifications, see the Basemaps page. To discover individual basemaps, use the Basemaps API, select them in Planet Explorer, or view your Basemaps in the Basemap Viewer.

Use the power of the Orders API to access basemaps in cases where you want to:

  • Order mosaic quads in bulk
  • Get metadata for quad and scene identification
  • Download data for analysis based on an area of interest (AOI)
  • Reproject, resample, and rescale imagery to a projected coordinate system and resolution
  • Merge quads and associated metadata to produce a single GeoTIFF file
  • Deliver data to object stores in the cloud and download cloud-optimized GeoTIFFs

By Geometry​

Basemaps may be ordered by geometry. For these orders, the Orders API will determine the quads that intersect with the mosaic (basemap ID) provided and deliver them.

Parameters​

ParameterTypeRequiredDescription
nameStringRequiredA name for the order.
source_typeStringRequiredThe product you're choosing to order (basemaps in this case).
mosaic_nameStringRequiredThe name of the basemap mosaic you're ordering.
geometryJSONRequiredA geojson geometry object representing the Area of Interest (AOI) that defines the region of the basemap you want to order. Used when ordering by an AOI instead of specific quads.
{
    "name": "basemap order by geometry",
    "source_type": "basemaps",
    "products": [
        {
            "geometry":{
                "type": "Polygon",
                "coordinates":[
                    [
                        [4.607406, 52.353994],
                        [4.680005, 52.353994],
                        [4.680005, 52.395523],
                        [4.607406, 52.395523],
                        [4.607406, 52.353994]
                    ]
                ]
            },
            "mosaic_name": "global_monthly_2022_01_mosaic",
        }
    ]
}

By Quad ID​

Basemaps may be ordered by quad ID - likely extracted from the Basemaps API. The Orders API will deliver the quads you specify.

Parameters​

ParameterTypeRequiredDescription
nameStringRequiredA name for the order.
source_typeStringRequiredThe product you are choosing to order (basemaps in this case).
mosaic_nameStringRequiredThe name of the mosaic you are ordering.
quad_idsList[String]RequiredThe IDs of the basemap quads you wish to order. Use the Basemaps API to retrieve the quad IDs based on your area of interest or bounding box.
{
    "name": "basemap order by quad",
    "source_type": "basemaps",
    "products": [
        {
            "quad_ids": [
                "377-1251"
            ],
            "mosaic_name": "global_monthly_2022_03_mosaic"
        }
    ]
}

Order Types​

  • full: A full order will fail if any single quad is unavailable.
  • partial: A partial order will deliver any available quads, excluding those that are unavailable or inaccessible.

The Orders API will always deliver all or none of the scenes in a quad, not partial quads.

Supported Tools​

A subset of tools are supported for basemaps orders.

  • merge — merge basemaps into a larger study area
  • clip — for orders with a geometry block, clip a raster to an area of interest
  • reproject — resample a Basemap to a new projection area
  • bandmath — perform numpy-like operations on rasters

To learn more about these tools, refer to the tools documentation.

Last updated on