Order Layout and Order Manifest
Order Delivery Layout
The default order delivery layout is organized as follows:
{OrderID}/manifest.json
{OrderID}/{ItemType}/{ItemID}_metadata.json
{OrderID}/{ItemType}/{AssetFileName}.{AssetFileExtension}
There are slight structural variations when an order is zipped or composited. When zipped, its layout will take the structure below. After it is unzipped, the resulting layout of the contents will look like the layout above.
{OrderID}/manifest.json
{OrderID}/{ArchiveFilename}.zip
When an order is composited, its layout will be organized as follows:
{OrderID}/manifest.json
{OrderID}/composite_udm.tif
{OrderID}/composite.tif
{OrderID}/{ItemID_1}_metadata.json
{OrderID}/{ItemID_1}_{AssetName}_metadata.xml
{OrderID}/{ItemID_2}_metadata.json
{OrderID}/{ItemID_2}_{AssetName}_metadata.xml
Delivery Manifests
The contents of your order are described by a JSON manifest, which is delivered alongside your order. This manifest describes the locations of the order's delivered files with additional metadata, such as the size and a cryptographic hash of file contents.
Manifests should be used to learn specifically to which paths data will be delivered. While the file paths referenced in the manifest may be subject to change over time, the order's manifest will always be found at the root directory of where the order data is being delivered.
Its location is calculated by taking the provided path_prefix (if any) and appending the order_id, then "manifest.json". As an example, an order with ID "68b2e5c0-aaf0-49cb-b5a8-13a96083dd41" with a path prefix of "ordered_data/" would result in a manifest at the following key:
/ordered_data/68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/manifest.json
Sample manifest.json File
{
"name": "",
"files": [
{
"path": "PSScene4Band/20180205_181923_1031_metadata.json",
"media_type": "application/json",
"size": 900,
"digests": {
"md5": "468c53baa4e985ca076500e6e9e99e7f",
"sha256": "4dd506111a27b747c780cdf373af9869a41a20e371655c776e7c1d1d505318a0"
},
"annotations": {
"planet/item_id": "20180205_181923_1031",
"planet/item_type": "PSScene4Band"
}
},
{
"path": "PSScene4Band/20180205_181923_1031_3B_AnalyticMS.tif",
"media_type": "image/tiff",
"size": 159628210,
"digests": {
"md5": "eccbc1ee8026a84264dc1470d1fee348",
"sha256": "e3264ba1922113b769bb6b2db693e78ae3ca7617ffb599a657a8ee3964df0ba9"
},
"annotations": {
"planet/asset_type": "analytic",
"planet/bundle_type": "analytic",
"planet/item_id": "20180205_181923_1031",
"planet/item_type": "PSScene4Band"
}
},
{
"path": "PSScene4Band/20180205_181923_1031_3B_AnalyticMS_DN_udm.tif",
"media_type": "image/tiff",
"size": 1233463,
"digests": {
"md5": "d4fdeda23e47073a73d802740731c3bb",
"sha256": "a225830664cbe1f5f1ed92c1101c893e89c8f8d9d88d83d9f4284b64811a909b"
},
"annotations": {
"planet/asset_type": "udm",
"planet/bundle_type": "analytic",
"planet/item_id": "20180205_181923_1031",
"planet/item_type": "PSScene4Band"
}
},
{
"path": "PSScene4Band/20180205_181923_1031_3B_AnalyticMS_metadata.xml",
"media_type": "text/xml",
"size": 10407,
"digests": {
"md5": "a2b24d7429217bbe1c3d3d4a00099d60",
"sha256": "4b251c4544203d8282403d09d32ed1bdd71b03f0ae8516169ee05382062f7aac"
},
"annotations": {
"planet/asset_type": "analytic_xml",
"planet/bundle_type": "analytic",
"planet/item_id": "20180205_181923_1031",
"planet/item_type": "PSScene4Band"
}
}
]
}
To find your ordered assets, you may assume all of these paths are relative to the manifest.json file. The final location of assets in this example order include:
/ordered_data/68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene4Band/20180205_181923_1031_metadata.json
/ordered_data/68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene4Band/20180205_181923_1031_3B_AnalyticMS.tif
/ordered_data/68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene4Band/20180205_181923_1031_3B_AnalyticMS_DN_udm.tif
/ordered_data/68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene4Band/20180205_181923_1031_3B_AnalyticMS_metadata.xml
Why you should depend on the manifest file
The manifest.json file is the last file delivered for an order, once the order is fully complete.
Due to potential delay between the time when an order's files are delivered and when they are accessible for download, we recommend waiting for the manifest before you begin accessing files.
The metadata.json file
In addition to your requested assets, your order will include a metadata.json file. This is a copy of the item-level metadata associated with the asset from our catalog. The metadata.json file will appear in the manifest like other assets but will not have planet/bundle_type nor planet/asset_type annotations.
Sample metadata.json File
{
"id": "20180204_152423_103e",
"type": "Feature",
"geometry": {
"coordinates": [
[
[
-80.66557928169364,
28.438843302832705
],
[
-80.68288062074312,
28.36602589486687
],
[
-80.42748137311838,
28.31897078740344
],
[
-80.4104695544562,
28.391931074041675
],
[
-80.66557928169364,
28.438843302832705
]
]
],
"type": "Polygon"
},
"properties": {
"acquired": "2018-02-04T15:24:23.097646Z",
"anomalous_pixels": 0,
"cloud_cover": 0.1,
"columns": 8894,
"epsg_code": 32617,
"ground_control": true,
"gsd": 3.9,
"instrument": "PS2",
"item_type": "PSScene3Band",
"origin_x": 531072,
"origin_y": 3145863,
"pixel_resolution": 3,
"provider": "planetscope",
"published": "2018-02-04T21:34:31Z",
"quality_category": "standard",
"rows": 4398,
"satellite_id": "103e",
"strip_id": "1141432",
"sun_azimuth": 140.3,
"sun_elevation": 35.3,
"updated": "2018-02-04T22:08:49Z",
"usable_data": 0,
"view_angle": 0.9
}
}
Delivery to Cloud Storage
You may choose to have your order delivered to either Amazon S3, Microsoft Azure Blob Storage, or Google Cloud Storage. For any cloud storage provider, you will need to create an account with both write and delete access.
Delivery to Amazon S3
For Amazon S3 delivery you will need an AWS account with GetObject, PutObject, and DeleteObject permissions.
Parameters
- aws_access_key_id (required): AWS credentials.
- aws_secret_access_key (required): AWS credentials.
- bucket (required): The name of the bucket that will receive the order output.
- aws_region (required): The region where the bucket lives in AWS.
- path_prefix (optional): An optional string that will be prepended to the files delivered to the bucket. A slash (
/) character will be treated as a "folder". Any other characters will be added as a prefix to the files.
Example Request
{
"name":"amazon_s3_delivery_order",
"products":[
{
"item_ids":[
"20151119_025740_0c74",
"20151119_025741_0c74"
],
"item_type":"PSScene3Band",
"product_bundle":"analytic"
}
],
"delivery":{
"amazon_s3":{
"bucket":"foo-bucket",
"aws_region":"us-east-2",
"aws_access_key_id":"",
"aws_secret_access_key":"",
"path_prefix":"folder1/prefix/"
}
}
}
The path_prefix specified above will produce a result in S3 which looks like the following:
/folder1/prefix/{order_id}}/320170716_144316_1041_3B_AnalyticMS.tif
Delivery to Microsoft Azure
For Microsoft Azure delivery you will need an Azure account with read, write, delete, and list permissions.
Parameters
- account (required): Azure credentials.
- container (required): The name of the container which will receive the order output.
- sas_token (required): Azure Shared Access Signature token. Token should be specified without a leading '?'. (I.e. "sv=2017-04-17u0026si=writersr=cu0026sig=LGqc" rather than "?sv=2017-04-17u0026si=writersr=cu0026sig=LGqc")
- storage_endpoint_suffix (optional): To deliver your order to a sovereign cloud a
storage_endpoint_suffixshould be set appropriately for your cloud. The default is "core.windows.net". - path_prefix (optional): String that will be prepended to the files delivered to the bucket. A slash (
/) character will be treated as a "folder"; other characters will be a prefix to the files.
Example Request
{
"name":"azure_delivery_order",
"products":[
{
"item_ids":[
"20151119_025740_0c74",
"20151119_025741_0c74"
],
"item_type":"PSScene3Band",
"product_bundle":"analytic"
}
],
"delivery":{
"azure_blob_storage":{
"account":"",
"container":"",
"sas_token":"",
"storage_endpoint_suffix":"",
"path_prefix":""
}
}
}
Delivery to Google Cloud Storage
For Google Cloud Storage delivery you will need an GCS account with write and delete permissions.
Preparing Your Google Cloud Storage Credentials
The Google Cloud Storage delivery option requires in a single-line base64 version of your service account credentials for use by the credentials parameter.
To download your service account credentials in JSON format (not P12) and encode them as a base64 string, you can use a cmdline operation such as:
cat my_creds.json | base64 | tr -d '\n'
Parameters
- credentials (required): GCS credentials.
- bucket (required): The name of the GCS bucket which will receive the order output.
- path_prefix (optional): String that will be prepended to the files delivered to the bucket. A slash (
/) character will be treated as a "folder"; other characters will be a prefix to the files.
Example Request
{
"name":"gcs_delivery_order",
"products":[
{
"item_ids":[
"20151119_025740_0c74",
"20151119_025741_0c74"
],
"item_type":"PSScene3Band",
"product_bundle":"analytic"
}
],
"delivery": {
"google_cloud_storage": {
"bucket": "your-gcs-bucket",
"credentials": "c29tZWNyZWRzZm9yeW91cmdjc2J1Y2...",
"path_prefix": ""
}
}
}
Zipping results
With the zip delivery option, you can receive the output of your order as a "per order" or "per bundle" zip archive.
Parameters
- archive_type (optional): Only
zipformat is supported. - archive_filename (optional): The name of the archive file you will receive. You can use template variables
{{name}}and{{order_id}}and in the string, which vary based on whether the order is per-bundle or per-order (i.e.single_archive) and are described in more detail below. - single_archive (optional): When
true, this option will archive all bundles together in a single file.
Per-Bundle Zipping
For per-bundle zipping (i.e. when single_archive is null or false), the archive filename variable {{name}} will return {item_typeitem_idproduct_bundle} and {{order_id}} will return the order_id.
Example Request
{
"name":"per-bundle-zipped-order",
"products":[
{
"item_ids":[
"20151119_025740_0c74",
"20151119_025741_0c74"
],
"item_type":"PSScene3Band",
"product_bundle":"analytic"
}
],
"delivery":{
"archive_type":"zip",
"archive_filename":"{{name}}_{{order_id}}.zip"
}
}
Output files (order_id = 68b2e5c0-aaf0-49cb-b5a8-13a96083dd41):
68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene3Band_20151119_025741_0c74_analytic_68b2e5c0-aaf0-49cb-b5a8-13a96083dd41.zip
68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene3Band_20151119_025740_0c74_analytic_68b2e5c0-aaf0-49cb-b5a8-13a96083dd41.zip
68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/manifest.json
Whole-Order Zipping
For per-order zipping (i.e. when single_archive is true), the archive filename variable {{name}} will list the order name and {{order_id}} will list the order_id.
Example Request
{
"name":"per-order-zipped-order",
"products":[
{
"item_ids":[
"20151119_025740_0c74",
"20151119_025741_0c74"
],
"item_type":"PSScene3Band",
"product_bundle":"analytic"
}
],
"delivery":{
"archive_type":"zip",
"single_archive": true,
"archive_filename":"{{name}}_{{order_id}}.zip"
}
}
Output files (order_id = 1b36c36c-8965-4e6f-9eef-ee9694f3d69c):
1b36c36c-8965-4e6f-9eef-ee9694f3d69c/per-order-zipped-order_1b36c36c-8965-4e6f-9eef-ee9694f3d69c.zip
1b36c36c-8965-4e6f-9eef-ee9694f3d69c/manifest.json