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
Parameter | Type | Required | Description |
---|---|---|---|
name | String | Required | A name for the order. |
source_type | String | Required | The product you are choosing to order (scenes in this case). |
item_ids | List[String] | Required | Catalog 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_type | String | Required | Represents the sensors and processing characteristics of a catalog item, like PSScene or SkySatCollect . More details on item types here. |
product_bundle | String | Required | A predefined group of asset_types . Details on product bundles here. |
- JSON
- Python SDK
{
"name": "simple order",
"source_type": "scenes",
"products":[
{
"item_ids":[
"20220304_093300_37_2430",
"20220304_093257_90_2430",
],
"item_type":"PSScene",
"product_bundle":"analytic_udm2"
}
]
}
from planet.order_request import product, build_request
single_product = product(
item_ids=["20220304_093300_37_2430", "20220304_093257_90_2430"],
product_bundle="analytic_udm2",
item_type="PSScene",
)
order_request = build_request(name="simple order", products=[single_product])
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.
- JSON
- Python SDK
{
"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"
}
]
}
from planet.order_request import product, build_request
single_product = product(
item_ids=["20220304_093300_37_2430", "20220304_093257_90_2430"],
product_bundle="analytic_udm2",
item_type="PSScene",
)
order_request = build_request(
name="partial order", products=[single_product], order_type="partial"
)
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.
- JSON
- Python SDK
"products": [
{
"item_ids":[
"20220304_093300_37_2430",
"20220304_093257_90_2430",
],
"item_type":"PSScene",
"product_bundle":"analytic_8b_udm2,analytic_udm2"
}
]
from planet.order_request import product
single_product = product(
item_ids=["20220304_093300_37_2430", "20220304_093257_90_2430"],
product_bundle="analytic_8b_udm2",
item_type="PSScene",
fallback_bundle="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.
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.
- JSON
- Python SDK
{
"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"
}
]
}
from planet.order_request import product, build_request
psscene_product = product(
item_ids=["20220306_094818_22_2276", "20220306_094815_93_2276"],
product_bundle="analytic_udm2",
item_type="PSScene",
)
reorthotile_product = product(
item_ids=["20171226_222055_6021709_RapidEye-3"],
product_bundle="analytic",
item_type="REOrthoTile",
)
order_request = build_request(
name="multiple item types order",
products=[psscene_product, reorthotile_product],
)
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
Parameter | Type | Required | Description |
---|---|---|---|
name | String | Required | A name for the order. |
source_type | String | Required | The product you're choosing to order (basemaps in this case). |
mosaic_name | String | Required | The name of the basemap mosaic you're ordering. |
geometry | JSON | Required | A 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. |
- JSON
{
"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
Parameter | Type | Required | Description |
---|---|---|---|
name | String | Required | A name for the order. |
source_type | String | Required | The product you are choosing to order (basemaps in this case). |
mosaic_name | String | Required | The name of the mosaic you are ordering. |
quad_ids | List[String] | Required | The 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. |
- JSON
{
"name": "basemap order by quad",
"source_type": "basemaps",
"products": [
{
"quad_ids": [
"377-1251"
],
"mosaic_name": "global_monthly_2022_03_mosaic"
}
]
}
Order Types
full
: Afull
order will fail if any single quad is unavailable.partial
: Apartial
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 areaclip
— for orders with a geometry block, clip a raster to an area of interestreproject
— resample a Basemap to a new projection areabandmath
— perform numpy-like operations on rasters
To learn more about these tools, refer to the tools documentation.