Language

Detailed step-by-step explanations for tasking

Before performing a tasking operation, you need to gather mandatory information that you will need later for the tasking itself. Steps 0.1 to 0.6 will lead you through this process. Afterwards, step 1 to 8 will allow you to place tasking orders from AOI definition to product download.

Step 0.1: Get contracts

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts
REST verbGET
AuthenticationBearer token

Response

{
    "contracts": [
        {
            "contractId": "CisContractId",
            "customerId": "customerId",
            "name": "ContractName",
            "tradeAgreementUrl": "https://www.intelligence-airbusds.com/cgf/",
            "creditRemaining": "150.0",
            "currency": "EUR",
            "language": "en",
            "contractType": "ONEATLASDATA",
            "backendSource": "legacy"
        }
    ]
}

Export your CisContractId.

Note: “backendSource” can be either “legacy” or “neo”. SPOT and Pléiades can only be ordered through “legacy” type contract. Pléiades Neo can only be ordered through “neo” back-end.

Step 0.2: Get workspace

Note: method to retrieve workspace_id differs between SPOT / Pléiades and Pléiades Neo


Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts
REST verbGET
AuthenticationBearer token

Response





Export your deliveryWorkspace.

Step 0.3: Get Product Types

This request displays the possible ordered productTypes associated to your contract.

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts/<CisContractId>/productTypes
REST verbGET
AuthenticationBearer token

Response




Choose one productTypeId among the possibilities.
The product type chosen indicates both the mission (SPOT or PLEIADES or PLEIADESNEO) and the tasking offer (ONEDAY, ONENOW, ONEPLAN).

Step 0.4: Get markets

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/<cisContractId>/properties
REST verbGET
AuthenticationBearer access token

Response is a list of markets. Primary market is mandatory for ordering.




Step 0.5: Get available delivery types

You can see which delivery type are available thanks to the following request:

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts/<CisContractId>/deliveryTypes
REST verbGET
AuthenticationBearer access token

Response

{ 
    "deliveryTypes": [
        {
            "deliveryTypeId": "network",
            "label": "FTP + My Data"
        },
        {
            "deliveryTypeId": "MEDIA",
            "label": "MEDIA"
        }
    ]
}

All commercial imagery products will be made available in your private workspace (= ‘MyData’). For SPOT & Pléiades orders, we ensure - until further notice - double deliveries of products also on the Geodelivery (= ‘FTP’)

Step 0.6: Get Production Options

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts/<CisContractId>/productTypes/<productTypeId>/options
REST verbPOST
AuthenticationBearer token

Body request sample:




Response




Step 0.7: Get country label

Request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/properties
REST verbGET
AuthenticationBearer token

Response is a list of countries and available labels. A label is mandatory to identify an user for ordering.




Step 1: Authenticate

Using you API Key, you will need to get an access token that enables authorization. Authorization refers to the process of determining what permissions an authenticated client has for a set of resources.
For security reasons this access token expires regularly then it’s necessary to renew the authentication process to get a new one.
Please refer to the dedicated Authentication Guide

Step 2: AOI Tutorial

For any request over a location you will be asked to define an AOI (Area Of Interest). This AOI definition follows the requirement of GeoJSON specifications, which is an open standard format designed for representing simple geographical features. The specified AOI must always have a GeoJSON geometric type (Polygon, Point, LineString, etc) and coordinates. The only supported type in our case is Polygon, which defines a shape composed by straight lines.

The coordinates of the polygon are an array of points defined by latitude and longitude. They must follow certain rules:

  • The first and last point are the same

  • The points define the outline of the shape. Complex shapes with multiples points are accepted up to 999 vertices.

  • Each AOI must have at least 4 coordinates (triangle)

  • An AOI with a “hole” inside (donut shape) is forbidden.

    Forbidden donut shape aoi

  • The order of the points is important. Each line defined between two consecutive points must not intersect with any other line of the polygon.

    • {“type”:“Polygon”,“coordinates”:[[[2.0,1.0],[1.0,1.0],[1.0,2.0],[2.0,2.0],[2.0,1.0]]]} is good

      Allowed shape aoi

    • {“type”:“Polygon”,“coordinates”:[[[2.0,1.0],[1.0,2.0],[1.0,1.0],[2.0,2.0],[2.0,1.0]]]} is not good

    Forbidden shape aoi with intersection

If you need to use a map to draw your AOI, you may use the AOI manager that is available within the OneAtlas platform. It allows a user to draw complex shapes and export the coordinates in many different formats that may suit your needs.

AOI manager menu

  • You can check the validity of your AOI with the following endpoint:
API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/geometry/valid
REST verbPOST
AuthenticationBearer token

Request




Response

{
    "status": "valid",
    "defects": []
}

Step 3: Check Feasibility

The following request returns an automatic feasibility study result for the requested tasking. This allows to:

  • know if the request needs to go through manual feasibility study (AUTOMATIC or MANUAL).

  • get the classification of your request in case of a OnePlan automatic request (EASY or CHALLENGING with an impact on price). classification is used for OnePlan only.

ProgTypeNames can be:

  • For Pléiades Neo: ONEPLAN, ONEDAY, ONENOWATTEMPTS, ONENOWWEATHER

  • For SPOT & Pléiades: ONEPLAN

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/feasibility
REST verbPOST
AuthenticationBearer token

Body request sample:




Response




classification and automation will be needed later.

classification is used for OnePlan only

If the automation is “MANUAL” a feasibility study will be needed. A feasibility study is a diagnosis performed by our tasking experts in order to organise the acquisition plan and estimate the confidence in covering the area of interest within the defined acquisition period and parameters. In that case the feasiblity study will be launched when you pass th eorder with the features you checked. For a better understanding of the tasking automation parameters, you can visit our automated tasking section.

Step 4: Get Attempts

Note: This step is only mandatory (and available) for ONEDAY and ONENOWATTEMPTS.

This API allows to get the first possible attempts matching your criteria, within a 7-day timeframe from the defined start date.
Start date can be set at any time. Note that if you try to set it in the past, the value will be replace by the current date.

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/attempts
REST verbPOST
AuthenticationBearer token

Body request sample:




Response example




For Pléiades Neo, acquisitionStartDate & acquisitionEndDate will be mandatory to define an acqPeriod to complete your OneDay or OneNow order.
For SPOT and for Pléiades tasking, segmentKey will be necessary as well.
You will receive an error message similar to the following if the AOI size is not correct.
Example:




Step 5: Calculate Price

Note: Price can be calculated ONLY for orders that does not require feasibility study, ie AUTOMATIC tasking

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/prices
REST verbPOST
AuthenticationBearer token



Step 6: Request a quotation

Note: Quotations are mandatory only in case of non-AUTOMATIC tasking but can be requested in any cases if necessary


API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/quotations
REST verbPOST
AuthenticationBearer token



Step 7: Create an order

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/orders
REST verbPOST
AuthenticationBearer token



Response

{
    "quotationId": "QUO22054547",
    "currency": "EUR",
    "discountPercentage": 0.0,
    "discountValue": 0.0,
    "totalAmount": 0.0
}


Notes:

  • productTypeId can be retrieved using Get product types

  • Please refer to the dedicated Get production options for processing options

  • classification and feasibilityAutomation are the results of the feasibility study step.

  • customerReference can be used throughout the ordering process to get the status of your order and find the images in your delivery workspace. It is as a consequence better to use 1 customerReference specific to each order

  • Notification on event WEATHER_PREDICTION is ONLY for OneDay, an e-mail is generated with the weather forecast of your acquisition about 24h before the acquisition

  • For OneDay offer, notificationThreshold and maxCloudCover will not be considered and forced to 100%

  • Dem and projection are not mandatory for primary, Dem is not mandatory for projected

  • The QUOid sent back in the response can be used to search for your order


About multi-item and multi-aoi orders:

  • The number aoiId corresponds to both the id of the aoi

  • The number 1 in dem_1 and projection_1 refers to both the aoiId

Step 8: Get your imagery product

Once delivered, the acquisition will be placed in your private workspace. You can run this request to access these images:

API Endpointhttps://search.foundation.api.oneatlas.airbus.com/api/v2/opensearch
REST verbPOST
AuthenticationBearer access token

Request

{
    "itemsPerPage": 10,
    "startPage": 1,
    "workspace": ""
}

Our search API supports following criteria:

  • acquisitionDate

  • cloudCover

  • publicationDate: this key is convenient if you want implement an automatic harvesting sequence

  • incidenceAngle

  • geometry

  • customerReference: if you used a specific reference while ordering, this will allow you to easily identify your data

Each image is returned as a GeoJSON feature under the /features[] property. The download link is part of the returned links.

Response




Track your orders

You can see all your tasking orders thanks to this request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v2/orders/search
REST verbPOST
AuthenticationBearer token

Request



Some insight about the interesting keys to be used (not all keys are mandatory):

  • customerReference: is the reference you used when creating your order
  • quotationStatus: can be ACCEPTED (quotation has been accepted, order is running) or SENT(quotation not yet validated, order not yet running)
  • cis.quotation: id of the quotation can be used to search

  • contractId: id of the contract can be used to search

  • status: can be IN_PROGRESS (order is running) or DELIVERED (order finished, all data delivered) or CANCELLED (order cancelled)

  • technicalProduct.source.id: can be tasking or archive




Response





Multi-item ordering specificities

  • You can order different products with different AOIs and different timeframes within a single command.

  • You can order a maximum number of 10 items with a single call.

  • For a better tracking of your individual products, we advise to execute single orders for each of them. Nevertheless, if you want to limit your calls to the endpoint, multi-item ordering is a valid option.

  • This functionality is available exclusively for Pléiades Neo. We advise to use the quotation option instead of the direct order if you are not familiar with the multi-item ordering

  • Each AOI you want to use shall be documented at the beginning of the payload with individual IDs. Then each item shall be described with its specific product type, ID of the AOI you wish to use and acquisition period. Ultimately the production options shall be defined for each product type (example below).

Note: For each AOI used by a product type, the parameters dem_XX and projection_XX must be described in the production options, XX being the id of the AOI concerned. A product type used for an order concerning 4 different AOIs must define 8 parameters for dem and projection.

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/quotations
REST verbPOST
AuthenticationBearer access token

Request






Stereo and tristereo specificities

  • STEREO and TRISTEREO options are available for all tasking offers (OneDay, OneNow, OnePlan) for Pléiades Neo. For SPOT and Pléiades, it is available for OnePlan only.
  • STEREO and TRISTEREO require a manual feasibility process. If the order is for Pléiades Neo, you can use a quotation process. Otherwise, it will require manual confirmation after the feasibility study.
  • In the request payload, within items/properties:
    • acquisitionMode can be set to “STEREO” or “TRISTEREO”
    • the key “acquisitionModeMinBH” must be present and its value set as a string between “0.2” and “0.8”
    • the key “acquisitionModeMaxBH” must be present and its value set as a string between “0.2” and “0.8”
  • Production parameters are limited:
    • processing_level : “primary”
    • spectral_processing : “full_bundle”
    • image_format : “dimap_jpeg2000_regular” or “dimap_geotiff”
    • pixel_coding: “12bits”
    • radiometric_processing: “reflectance”

bh-details


Request example




Retrieve acquisitions on an order

Note: Pléiades and SPOT are working at segment level while Pléiades Neo at coverage item (1 coverage item is by default a scene equivalent)

You can see all your tasking orders thanks to this request

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/coverages/search
REST verbPOST
AuthenticationBearer token

Request



Status of a coverage item can be:

  • VALIDATED: the coverage item fits initial automatic acceptance criteria
  • PROPOSED: the coverage item fits initial manual acceptance criteria - requires action from the user to accept / refuse (see dedicated chapter)
  • REFUSED: the coverage item has been proposed by the system then refused by the user

  • PENDING: the coverage item is in a temporary state managed by the system - no user actions expected

  • REJECTED: the coverage item has been refused by the system based on the acceptance criteria provided by the user



Response



Export the coverage item id coverageItemId

Accept or refuse an acquisition

Note: Pléiades and SPOT are working at segment level while Pléiades Neo at coverage item (1 coverage item is by default a scene equivalent)

In case you get acquisitions that are above the automatic acceptance threshold and under the notification threshold, you will have to validate or refuse the acquisition.

coverageItemId or segmentId to be validated or refused can be found under the Retrieve acquisitions on an order section.


For Pléiades Neo


You can then accept an acquisition using:

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/coverages/{coverageItemId}/accept
REST verbPOST
AuthenticationBearer token

You can refuse a acquisition using:

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/coverages/{coverageItemId}/refuse
REST verbPOST
AuthenticationBearer token

Cancel a tasking order

You have the possibility to cancel the tasking until 12 hours before the start of your tasking window using:


API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/orders/{orderItemId}/cancel
REST verbPOST
AuthenticationBearer token


For Pléiades Neo orderItemId information can be retrieved from Track your orders


Request



Stop a tasking order


If your tasking is not completed yet, you have the possibility to stop the future acquisitions using:


API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/orders/{orderItemId}/stop
REST verbPOST
AuthenticationBearer token


For Pléiades Neo orderItemId information can be retrieved from Track your orders


Request



Note: Acquisitions already done - and within acceptance criteria - will be invoiced

Manage quotations

For Pléiades Neo only
You can get access quotations using the following request. The customer reference is the personal reference you defined when sending the quotation request.

API Endpointhttps://order.api.oneatlas.airbus.com/api/v2/orders/search
REST verbPOST
AuthenticationBearer access token

Request

{
    "paging": {
        "itemsPerPage": 25,
        "startIndex": 0,
        "pagingMode": "item"
    },
    "criteria": {
        "q": "(customerReference:**) AND (quotationStatus:SENT) AND (contractId:)"
    }
}

Retrieve quotationId then

If you need to get a PDF version of the quotation:

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/quotations/<quotationId>/export
REST verbGET
AuthenticationBearer access token



To accept a quotation:

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts/<CisContractId>/quotations/<quotationId>/accept
REST verbPUT
AuthenticationBearer access token


Once accepted, the order is automatically created.

To refuse a quotation:

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/contracts/<CisContractId>/quotations/<quotationId>/refuse
REST verbPUT
AuthenticationBearer access token

Request

{"rejectionReasonId":1}

The rejectionReasonId matches the following rationals:

1: “The quote has expired”,

2": “I chose another imagery provider”,

3: “It doesn’t correspond to my budget expectations”,

4: “The tasking proposal is not answering my needs”,

5: “The licence doesn’t answer my operational needs”,

6: “I need to modify my request”,

7: “Other”

Orbitography

For Pléiades Neo only

If you wish to increase the accuracy of your tasking requests, you can see the exact trajectories of the Pléiades Neo satellites at any moment in the future. You can see the maximum reach according to your target incidence angle.

Below, is an example of the trajectory and reach of Pléiades Neo, and can be visualized in OneAtlas

Orbitography visual on OneAtlas Data portal

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/orbits
REST verbPOST
AuthenticationBearer access token


Request

{
    "satellites": [
        "PNEO3",
        "PNEO4"
    ],
    "startDate": "2024-02-14T00:00:00.000Z",
    "endDate": "2024-02-16T23:59:59.999Z",
    "mode": "DESCENDING",
    "angle": 26.77,
    "track": true,
    "corridor": true
}

The angle, startDate and endDate are the parameters you can update to fit your needs.

You also have the possibility to include and focus on an AOI in your payload

API Endpointhttps://order.api.oneatlas.airbus.com/api/v1/orbitsShape
REST verbPOST
AuthenticationBearer access token


Request

{
    "satellites": [
        "PNEO3",
        "PNEO4"
    ],
    "startDate": "2024-02-15T00:00:00.000Z",
    "endDate": "2024-02-22T23:59:59.999Z",
    "mode": "DESCENDING",
    "angle": 26.77,
    "shape": {
        "polygon": {
            "exterior": {
                "linearRing": {
                    "pos": "6.503906250000023 16.720385051693995 8.437500000000004 16.720385051693995 8.437500000000004 18.396230138028827 6.503906250000023 18.396230138028827 6.503906250000023 16.720385051693995"
                }
            }
        }
    }
}



Response



The response will give you all the trajectories for each Pléiades Neo satellite from North pole to South pole (or the other way around if you choose the ASCENDING mode), the start and end time and the span you can reach with the desired angle you choose.

The track will represent the trajectory of the satellite and the corridor, the area you can reach.



Automated Tasking

Feasibility study

Automatic acceptance parameters

The feasibility study is a process required to determine if the tasking request can be completed under the requested parameters, including: cloud coverage, incidence angle and the time frame for collection. The final step of this process includes a tasking proposal from the Airbus Tasking team as well as a validation to launch the process. In the case of a OnePlan tasking, if you need to go throuhg the feasibility study process, this will be a OnePlan Pro.

The following parameters will guarantee that the feasibility study is not mandatory (OnePlan) and the tasking will automatically be accepted:

  • maxCloudCover >= 10

  • maxIncidenceAngle >= 20

  • acquisitionMode = MONO

  • For SPOT and Pléiades, feasibility study endpoints work only with ONEPLAN

  • ONEPLAN requires the timespan to be at least 30 days for automatic tasking and at least 60 days for EASY classification.

  • ONEDAY and ONENOW ATTEMPTS depend on the satellite orbit but have only little timeline requirement. However, we recommand to orderyour tasking at least 60 min before the first acquisition.

  • ONENOWWEATHER requires the timespan to be at least 3 days for automatic tasking

AOI constraints for automatic acceptance

For OneDay and OneNow

Pléiades NeoPléiadesSPOT 6/7
Minimum area invoiced (km2)100100500
Minimum AOI area (km2)24.525100
Maximum AOI area (km2)4008007200
Maximum AOI height (km)3040120
Maximum AOI width (km)1318.950

For OnePlan

Pléiades NeoPléiadesSPOT 6/7
Minimum area invoiced (km2)100100500
Minimum AOI area (km2)555
Maximum AOI area (km2)n/an/an/a
Maximum AOI height (km)100001000010000
Maximum AOI width (km)100001000010000

Workarounds

If you send a request to the check feasibility endpoint (see Step 3: Check Feasibility) and the response defines your order automation as MANUAL, you can change the parameters to be less challenging. If the parameters are good enough, your tasking can be automatically accepted and you may skip this step.

Workaround schema for feasibility study
For Pléiades Neo tasking requests , the best option to avoid human validation is to request a quotation. If the feasibility study cannot be validated through an API, a quotation, on the other hand, can be fully handled with an automated process. Since the quotation includes the feasibility study step, you can request a quotation for tasking (Step 6: Request a quotation), then either accept or refuse the quotation once it’s available. As a reminder, once the quotation is accepted, the order is passed automatically (Manage quotations).

Workaround schema for feasibility study using quotation

Accept proposed acquisition

Pléiades and SPOT are working at segment level while Pléiades Neo is acquiring smaller targeted locations. at coverage item (1 target is by default a scene equivalent). The process is the same for Pléiades Neo as well as Pléiades and SPOT but the endpoints slightly differ. As a reminder, acquisitions require your validation if they do not fill the required conditions for direct production but fit into the threshold value you have set during the order. First, you need to check if acquisitions requiring your attention are available (generally new acquisitions), then you store its reference and decide to accept or reject it.

Workaround schema for acquisition management

Product delivery Notifications

Once your tasking request is complete and your product is delivered, you may want to be notified without checking your email. In that case, you can use an automatic workflow to send a periodic request to the opensearch endpoint to check if your product is available. In order to reach maximum efficiency, you can use your customer reference to understand if your order has been delivered.

Workaround schema for product delivery

© Airbus Defence and Space 2022. All rights reserved. Privacy Policy | Legal Information

Contact Us