Skip to content

ARD Orders

To run orders from Python the SDK has one main object: Order represents an order and its interaction with the API. 

from max_ard import Order

The call signature for an Order includes the following keyword arguments:

  • acquisitions: List of acquisition IDs to order, a list of acquisition/cell dictionaries, or SelectResults - see below.
  • select_id: Order the results of a Select query with the Select ID. If ordering by select ID, do not include acquisition ID or an AOI in the order request.
  • destination: For S3 orders only, the destination of the tiles: an S3 bucket path like s3://bucket/prefix
  • output_config: An output configuration dictionary, see Output Configuration below. Required if not using destination.
  • intersects: Only generate tiles that intersect this WGS84 geometry. Accepts WKT or GeoJSON strings, most Python geospatial objects, or a file path to OGR-readable files
  • bbox: Like intersects, but takes a bounding box list or tuple in the form [XMIN YMIN XMAX YMAX]
  • role_arn: A trusted S3 Role ARN for the writer to assume so it can write tiles. This is not used if the s3 bucket policy is in place.
  • dry_run: Boolean to dry-run the order. If True, submits the order for basic validation but will not generate tiles. Default is False.
  • bba Boolean to use Bundle Block Adjustment to relatively align images within this order. Default is False.
  • settings A dictionary for finer-grained control of processing and outputs
  • metadata: A dictionary of user-defined key-value pairs.

Orders can send notifications. Notifications are set up using these two methods. Note: "dry run" orders do not send notifications since they do not start the order pipeline.

  • add_email_notification(address): add an email notification
  • add_sns_notification(topic): add an sns notification

Output Configurations

ARD support delivering to Amazon S3, Google Cloud Storage, and Azure Blob Storage. You can configure the storage destination by passing a dictionary in the following formats:

Amazon S3

{
    "amazon_s3": {
        "bucket": "my-ard-bucket"
        "prefix": "example/prefix"
    }
}

Note: you can also specify S3 locations using the parameter destination="s3://bucket/prefix" instead of output_config.

Azure Blob Storage

{
    "azure_blob_storage": {
        "sas_url": "https://storagesample.blob.core.windows.net/?...",
        "container": "my-ard-container",
        "prefix": "example/prefix"
    }
}

Google Cloud Storage

{
    "google_cloud_storage": {
        "service_credentials": <see note>,
        "bucket": "my-ard-bucket",
        "prefix": "example/prefix"
    }
}

service_credentials can accept two forms:

  • a path to the service credentials JSON file. The SDK will read the file and convert it to Base64 encoding.
  • a Base64-encoded string of the credentials file contents.

Storing Credentials for GCS and Azure

Output configurations for GCS and Azure can use a stored credential instead of the service_credentials or sas_url parameters. Use the parameter "credentials_id" instead. Secure credential storage is provided by the ARD API, see the Credentials Service documentation for more information and Administration and Authentication section for using the Python SDK to manage credentials.

{
    "google_cloud_storage": {
        "credentials_id": "our-stored-credentials"
        "bucket": "my-ard-bucket",
        "prefix": "example/prefix"
    }
}

Finer Control with the settings parameter

Default behavior of the ARD production system is to generate all outputs and masks. You can optionally skip some assets by providing a settings dictionary with the options you wish to change. settings can also control processing options like BBA or HD.

The default values are:

{
    "bundle_adjust": False,
    "hd": False,
    "cloud_mask": True,
    "healthy_vegetation_mask": True,
    "ms_saturation_mask": True,
    "pan_flare_mask": True,
    "terrain_shadow_mask": True,
    "water_mask": True
}

You can disable any of the above output files by setting them to False. You do not need to provide all values, only the settings you wish to change. Note that setting the BBA option with the bundle_adjust value in settings has priority over the bba parameter, but setting either to True will turn on BBA.

Creating Orders

Create an order object with the desired parameters described above. Add notifications if needed. You can then call the submit() method to start the order processing.

Ordering Acquisitions and/or Tiles

To order specific acquisitions, using an optional AOI or BBOX, provide a list of acquisition IDs:

acquisitions=['1030010052208D00']

To limit ordering to specific ARD tiles from acquisitions, pass a list of dictionaries, with the keys id and cells. If no cells are specified, it is assumed all cells are wanted (subject to clipping by an AOI or BBOX):

acquisitions=[
      {
          "id": "103001007B478000",
          "cell_ids": ["Z17-031313123113", "Z17-031313123112"]
      },
      {
          "id": "103001009E8C7C00",
          "cell_ids": ["Z17-031313123113"]
      },
      {
          "id": "103001009E8G3C90"
      }
  ]

If you have results from a Select or MetaSelect, you can also pass those to acquisitions to order the tiles returned by the search.

select = MetaSelect(query=...)
order = Order(acquisitions=select.results, ...)

However, if you have run a Select and have it's ID, you can pass that instead of results using select_id= instead of acquisitions= and the ARD pipeline will fetch the select results and order them for you.

# an S3 order for a Select using `destination`
order = Order(destination='my_bucket/my_ard_tiles', select_id=<Select ID>)

# a GCS order for acquisitions using `output_config` and a credentials file
output_config = {
    "google_cloud_storage": {
        "service_credentials": "path/to/credentials.json",
        "bucket": "my-ard-bucket",
        "prefix": "example/prefix"
    }
}

order = Order(output_config=output_config, acquisitions=['1030010052208D00'])

# add notifications if needed, then submit the order
order.add_email_notification('me@email.com')
order.submit()

Properties of the Order object

An Order has the following properties after it is created:

  • request: A container object storing the request options.

After the Order has been submitted with submit(), the following properties can be used:

  • order_id: The order ID assigned to the request
  • finished: Boolean if the order has finished running
  • status: state of the order process: 'RUNNING', 'SUCCEEDED', or 'FAILED'

Once the Order has finished, this property is also available:

  • response: A container object of the API response

Methods of the Order object

submit(): submits the order

order.submit()

# you can poll order.finished, but orders can take up to 3 days.

To create a Order object from ID, use the from_id classmethod:

Order.from_id(id)

When an order is complete, you can use ARDCollection to work with the data, see the Working with ARD Data section of the documentation.

Back to top