Place an order

Overview

You can order data from catalog and tasking collections using the API. If you are ordering from a collection for the first time, you need to complete access steps.

You can also place an order using the console.

See a JSON schema of an order form

Orders require different parameters depending on the data product.

To see detailed information about the parameters needed to create an order for a specific data product, call the /orders/schema/{data_product_id} endpoint with the data product ID as a path parameter.

Request

GET /orders/schema/{data_product_id} HTTP/1.1
Host: api.up42.comf
Authorization: Bearer {token}

Response

See response example

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "geometry": {
      "title": "Geometry",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/Point"
        }
      ]
    },
    "displayName": {
      "title": "Order name",
      "type": "string"
    },
    "extraDescription": {
      "title": "Description",
      "type": "string"
    },
    "acquisitionStart": {
      "title": "Start",
      "type": "string",
      "format": "date-time"
    },
    "acquisitionEnd": {
      "title": "End",
      "type": "string",
      "format": "date-time"
    },
    "acquisitionMode": {
      "title": "Acquisition mode",
      "description": "Standard mode acquires single image scene in daylight with standard product specifications. Burst collects multiple images in rapid sequence for motion analysis. Area Coverage collects mulitple images over an area larger than a single image scene. Stereo collects multiple images from different viewing angles for 3D visualization and analysis.",
      "type": "string",
      "allOf": [
        {
          "$ref": "#/definitions/acquisitionMode"
        }
      ]
    },
    "cloudCoverage": {
      "title": "Max cloud coverage (%)",
      "description": "Maximum allowed cloud coverage in percentage. If nothing specified, 30% is set as the default cloud cover.",
      "default": 30,
      "minimum": 30,
      "maximum": 100,
      "type": "integer"
    },
    "incidenceAngle": {
      "title": "Max incidence angle (\u00b0)",
      "description": "Maximum allowed incidence angle (angle between the sub-satellite point, satellite, and the target) in degree. If nothing specified, an angle between 0 and 30 is set as the default angle.",
      "default": 30,
      "minimum": 0,
      "maximum": 30,
      "type": "integer"
    },
    "priority": {
      "title": "Priority",
      "description": "Choosing high priority for your order will incur additional cost (approximately 70%).",
      "type": "string",
      "allOf": [
        {
          "$ref": "#/definitions/priority"
        }
      ]
    }
  },
  "required": ["geometry", "displayName", "acquisitionStart", "acquisitionEnd", "acquisitionMode", "priority"],
  "definitions": {
    "Point": {
      "title": "Point",
      "description": "Point Model",
      "type": "object",
      "properties": {
        "type": {
          "title": "Type",
          "default": "Point",
          "const": "Point",
          "type": "string"
        },
        "coordinates": {
          "type": "array",
          "minItems": 2,
          "items": {
            "type": "number"
          }
        }
      },
      "required": ["coordinates"]
    },
    "acquisitionMode": {
      "title": "acquisitionMode",
      "anyOf": [
        {
          "const": "standard",
          "title": "Standard"
        },
        {
          "const": "burst",
          "title": "Burst"
        },
        {
          "const": "areaCoverage",
          "title": "Area Coverage"
        },
        {
          "const": "stereo",
          "title": "Stereo"
        }
      ]
    },
    "priority": {
      "title": "priority",
      "anyOf": [
        {
          "const": "standard",
          "title": "Medium"
        },
        {
          "const": "global",
          "title": "High"
        }
      ]
    }
  },
  "additionalProperties": false
}

Create an order

To create a new order, call the /v2/orders endpoint.

Request

POST /v2/orders HTTP/1.1
Host: api.up42.com
Content-Type: application/json
Authorization: Bearer {token}

Parameter	Overview
`workspaceId`	string / required The workspace ID.
`dataProduct`	string / required The data product ID.
`displayName`	string / required A human-readable name between 1 and 200 characters that describes the order.
`params`	object / required The order parameters.
`featureCollection`	object / required The specified geometry. Can be a POI or an AOI, single or multipart.
`featureCollection.` `type`	string / required The type of the specified geometry. The only allowed value is `FeatureCollection`.
`featureCollection.` `features`	array of objects / required GeoJSON features.
`tags`	array of strings A list of tags that categorize the order. You can use up to 30 tags.
	Parameters of the `featureCollection.features` array
`type`	string The type of the specified geometry. The only allowed value is `Feature`.
`geometry`	object The order AOI.
`geometry.type`	string The geometry type. The allowed types: `Point` `MultiPoint` `LineString` `MultiLineString` `Polygon` `MultiPolygon`
`geometry.` `coordinates`	array of arrays The coordinates of the AOI.

See request example

{
  "workspaceId": "a19e9ab6-afad-461f-8043-ce19cfd0985b",
  "dataProduct": "613ad1f5-4148-4460-a316-1a97e46058f9",
  "displayName": "BlackSky NY Central Park",
  "params": {
    "geometry": {
      "type": "Point",
      "coordinates": [[[-73.981842, 40.771133]]]
    },
    "displayName": "BlackSky NY Central Park",
    "acquisitionStart": "2019-08-24T14:15:22Z",
    "acquisitionEnd": "2019-08-24T14:15:22Z",
    "acquisitionMode": "standard",
    "priority": "standard"
  },
  "featureCollection": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [[[-73.981842, 40.771133]]]
        }
      }
    ]
  },
  "tags": ["project-7"]
}

Response

See response example

{
  "results": [
    {
      "index": 0,
      "id": "14e49010-9fab-4ba8-b4c5-ed929a083400"
    }
  ],
  "errors": []
}

Parameter	Overview
`results`	object Details of the created orders. If you have defined multiple geometries, each geometry will result in a separate order.
`results.index`	number The created order index number. Indexing starts from `0`.
`results.id`	string The created order ID.

Troubleshooting

Can I stop an order after I placed it?

Placing an order is irreversible, and credit consumption can't be reverted.