Home /UP42 API

Catalog

Create and monitor catalog orders using the API.

Overview

Catalog data is archive geospatial data that has been captured in the past.

Step 1. Get access

If you are ordering a certain catalog collection for the first time, complete the access steps.

  1. Select a collection

    Review the specifications of catalog collections and select a collection for ordering.

    To get a list of all collections, call the Get geospatial collections endpoint. Select the collection you want to proceed with and retrieve its name.

  2. Request access

    If you order a collection for the first time and its restricted parameter is set to true, request access to the collection. Your request will be reviewed in up to 3 working days. You will get an email once a decision has been reached. You can review your access request status on the Access requests page.

    After you have access, you won’t need to request access again.

  3. Accept EULAs

    If you want to order the chosen collection for the first time, review and accept its end-user license agreement (EULA). If a EULA is updated, you need to re-accept it before creating your next order.

  1. Select a host

    Host are providers that offer access to the data initially acquired and processed by producers.

    Call the Get a geospatial collection endpoint with the collection name as the path parameter. Retrieve the name of the host for this collection.

  2. Search the catalog

    To get a list of available full scenes from the catalog, call the Search the catalog by host name endpoint with the name of the host as the path parameter. Note that some hosts offer several collections, all of which will be listed in the search results.

    Here is a sample search request with the following parameters:

    • From the Pléiades collection
    • Covering the geometry specified in the bounding box
    • Captured from January 1, 2019, to January 15, 2019
    • With cloud coverage less than or equal to 90%

    JSON 

        {
  "collections": ["PHR"],
  "bbox": [6.553674, 62.191632, 6.560222, 62.195116],
  "datetime": "2019-01-01T00:00:00Z/2019-01-15T23:59:59Z",
  "limit": 100,
  "query": {
    "cloudCoverage": {
      "LTE": 90
    }
  }
}

    To search for imagery from NEXTMap, set the datetime of the search range to include 2020-01-01T00:00:00Z. For example: "datetime": "2019-01-01T00:00:00.000Z/2022-12-31T00:00:00.000Z"

    Retrieve the full scene ID from the features.properties.id field in the response.

    Full scenes can either have an acquisition date or an acquisition date range in the response.

    How to find acquisition dates or acquisition date ranges

    • Acquisition dates

      For collections that have acquisition dates, full scenes will have start_datetime and end_datetime set to null. The acquisitionDate field provides the acquisition date.

      JSON 

          {
  "features": [
    {
      "properties": {
        "acquisitionDate": "2021-08-28T10:39:07Z",
        "start_datetime": null,
        "end_datetime": null,
        // Other parameters
      },
      <...> // The format of the response is different for different collections
    }
  ]
}

    • Acquisition date ranges

      For collections that have acquisition date ranges, full scenes will have acquisitionDate, start_datetime, and end_datetime filled out. The start_datetime and end_datetime fields provide the start and end of the acquisition date range.

      JSON 

          {
  "features": [
    {
      "properties": {
        "acquisitionDate": "2020-01-01T00:00:00Z",
        "start_datetime": "2020-01-01T00:00:00Z",
        "end_datetime": "2024-02-28T00:00:00Z",
        // Other parameters
      },
      <..> // The format of the response is different for different collections
    }
  ]
}

  3. Preview data

    Some data hosts provide free, low-resolution images of data that you can view before creating an order:

    • Quicklooks are previews of full scenes on a basemap. Some quicklooks may not fully match the scene they represent.
    • Thumbnails are small, light-weighted previews of full scenes. For some data hosts, thumbnails can be cropped and rotated compared to quicklooks.

    Not all data hosts provide thumbnails or quicklooks.

    To get a quicklook of a full scene from the catalog, call the Get a quicklook endpoint with the host name and image ID as path parameters. If a quicklook is available, the response will be an image file. Otherwise, the response will be null.

    To get a thumbnail of a full scene from the catalog, call the Get a thumbnail endpoint with the host name and image ID as path parameters. If a thumbnail is available, the response will be an image file. Otherwise, the response will be null.

Step 3. Create an order

  1. Select a data product

    Data products are a type of imagery with a specific geometric and radiometric processing level and file format. All collections have different data products corresponding to their technical specifications.

    To get a list of data products available for the collection you have selected, call the Get a geospatial collection endpoint with the name of the chosen collection as the path parameter. Retrieve the data product ID of the product you want to proceed with.

  2. Get 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 Get a JSON schema of an order form endpoint with the data product ID as the path parameter.

    How to read catalog order schemas

    For example, this is Pléiades catalog collection’s schema:

    JSON 

        {
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "id": {
      "title": "Id",
      "type": "string"
    },
    "aoi": {}
  },
  "required": [
    "id",
    "aoi"
  ],
  "definitions": {
    "Polygon": { ... },
      "required": [
        "coordinates"
      ]
    }
  },
  "additionalProperties": false,
  "title": "OneAtlasParams"
}

    The parameters in the properties field are the properties you can specify.

    • For all catalog collections, you need to specify the full scene ID you retrieved in Step 2. Find and preview data.
    • For catalog collections that return AOI-clipped imagery, you also need to specify the AOI.

  3. Estimate cost

    Before creating an order, you can estimate the price in UP42 credits. The factors considered in the final price calculation are the size of the area of interest, the data collection, and the type of data product.

    To see a cost estimation before creating an order, call the Estimate the cost of an order endpoint. The structure of request bodies for estimation and order placement requests is the same.

    The response returns the overall credit amount that will be deducted from your credit balance if you decide to proceed with the ordering:

    JSON 

        {
  "summary": {
    "totalCredits": 14424, // The estimate of the order cost, in credits
    "totalSize": 8.48,
    "unit": "SQ_KM"
  },
  "results": [ // Check this if you have several geometries in your order
    {
      "index": 0,
      "credits": 13000,
      "size": 8,
      "unit": "SQ_KM"
    },
    {
      "index": 1,
      "credits": 1424,
      "size": 0.48,
      "unit": "SQ_KM"
    }
  ],
  "errors": [ ... ]
}

  4. Create an order

    Credits will be deducted upon successful completion of the created catalog order. The transaction can’t be reversed.

    To create an order, call the Create an order endpoint with your workspace ID as the query parameter.

    Create a request body for the endpoint as follows:

    • In displayName, assign a custom name to your order.
    • In dataProduct, use the chosen data product ID.
    • In featureCollection, use the geometry you want to order.
    • In params, use the required request body schema format for the chosen data product.
      • In params.id, use the chosen full scene ID.

    JSON 

        {
  "displayName": "SPOT catalog order",
  "dataProduct": "b1f8c48e-d16b-44c4-a1bb-5e8a24892e69",
  "featureCollection": { ... }, // The geometry in GeoJSON format
  "params": {
    "id": "42712243-a45c-4c8e-adfa-1ce01d27b718", // The full scene ID
    <...> // The format of the payload is different for different data products
  }
}

    If you need to change the tags of the order after it has been created, call the Update an order endpoint with the order ID as the path parameter and the new tags in the request body.

Step 4. Monitor orders

To learn about the time frames of catalog orders, see Asset delivery time.

Get information about catalog orders as follows:

  • Retrieve information about all orders by calling the Get orders endpoint.
  • Retrieve information about a specific order by calling the Get an order endpoint with the order ID as the path parameter.

The most useful parameter for monitoring is order status.

Order statuses
StatusDescription
CREATEDThe order has been created, but not yet placed.
PLACEMENT_FAILEDAn error occurred while placing the order. Please wait until it is resolved.
BEING_PLACEDThe order is being placed.
PLACEDThe order has been placed.
BEING_FULFILLEDThe order is in progress. Some assets may already be delivered to your storage.
DELIVERY_INITIALIZATION_FAILED
DOWNLOAD_FAILED		An error occurred while delivering the order assets. Please wait until it is resolved.
DOWNLOADEDThe order assets are being delivered to your storage.
FULFILLEDThe order is complete, and all assets have been delivered to your storage.
FAILED_PERMANENTLY

The order has permanently failed or has been canceled. Please create the order again and if the issue persists, contact support.

The following order statuses mean you can download assets from storage:

  • BEING_FULFILLED: some order assets might have been delivered.
  • FULFILLED: all order assets have been delivered.