Place an order

Place orders using the API.


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}
ParameterOverview
workspaceIdstring / required
The workspace ID.
dataProductstring / required
The data product ID.
displayNamestring / required
A human-readable name between 1 and 200 characters that describes the order.
paramsobject / required
The order parameters.
featureCollectionobject / 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.
tagsarray of strings
A list of tags that categorize the order. You can use up to 30 tags.
Parameters of the featureCollection.features array
typestring
The type of the specified geometry. The only allowed value is Feature.
geometryobject
The order AOI.
geometry.typestring
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": []
}

ParameterOverview
resultsobject
Details of the created orders. If you have defined multiple geometries, each geometry will result in a separate order.
results.indexnumber
The created order index number. Indexing starts from 0.
results.idstring
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.

Learn more