Language
OneAtlas Data Guide
  1. Order from Analytics Toolbox
    1. Prerequisites
    2. List available Analytics
    3. Search Images
    4. Calculate the Price of an Analytic Report
    5. Order of an Analytic Report
    6. Order Status
    7. List Orders
    8. Retrieve the Report

Order from Analytics Toolbox

Ordering from Analytics Toolbox allows you to run an analytic on selected Living Library image(s) to generate a geojson report on your AOI that can be directly used in your GIS tool.

Prerequisites

If you haven’t already, see our Authentication Guide for information on how to acquire and use an API key and generate tokens to access to our endpoints.

List available Analytics

To place an order for an Analytics Toolbox report, you will need the code and type of the analytic you want to run. The endpoint to get the list of available analytics in Analytics Toolbox is:

API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/analytics
REST verbGET
AuthenticationJWT Token

Here below is an example of a call:

curl -X GET \
  'https://data.api.oneatlas.airbus.com/api/v1/analytics' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json'

And the associated response :

{
    "startIndex": 0,
    "totalResults": 5,
    "countLimitReached": false,
    "itemsPerPage": 10,
    "items": [
        {
            "code": "analytic.airbus.change-detection",
            "version": "5.3.0",
            "vendor": "Airbus",
            "name": "Change Detection",
            "order": 0,
            "description": "Detect infrastructure changes (buildings, houses, constructions) on images with 0.50m and 1.50m resolution",
            "type": "changes",
            "sensor": [
                "SPOT",
                "PHR"
            ],
            "commercialStatus": "commercial",
            "qualityControl": {
                "default": "standard",
                "availableModes": [
                    "standard",
                    "auto"
                ]
            }
        },
        {
            "code": "analytic.orbitalinsight.cars-detection",
            "version": "3.2.0",
            "vendor": "Orbital Insight",
            "name": "Cars Detection",
            "order": 1,
            "description": "Detect and count cars on images with 0.50m resolution",
            "type": "objects",
            "sensor": [
                "PHR"
            ],
            "commercialStatus": "commercial",
            "qualityControl": {
                "default": "auto",
                "availableModes": [
                    "auto"
                ]
            }
        },
        {
            "code": "analytic.orbitalinsight.trucks-detection",
            "version": "3.2.0",
            "vendor": "Orbital Insight",
            "name": "Trucks Detection",
            "order": 2,
            "description": "Detect and count trucks on images with 0.50m resolution",
            "type": "objects",
            "sensor": [
                "PHR"
            ],
            "commercialStatus": "commercial",
            "qualityControl": {
                "default": "auto",
                "availableModes": [
                    "auto"
                ]
            }
        },
        {
            "code": "analytic.airbus.ships-detection",
            "version": "5.0.0",
            "vendor": "Airbus",
            "name": "Ships Detection",
            "order": 3,
            "description": "Detect and count ships on images with 0.50m and 1.50m resolution",
            "type": "objects",
            "sensor": [
                "SPOT",
                "PHR"
            ],
            "commercialStatus": "trial",
            "qualityControl": {
                "default": "auto",
                "availableModes": [
                    "auto"
                ]
            }
        },
        {
            "code": "analytic.orbitalinsight.aircraft-detection",
            "version": "1.0.1",
            "vendor": "Orbital Insight",
            "name": "Aircraft Detection",
            "order": 4,
            "description": "[Beta] Detect and count planes on images with 0.50m resolution",
            "type": "objects",
            "sensor": [
                "PHR"
            ],
            "commercialStatus": "commercial",
            "classification": {
                "classes": [
                    {
                        "code": "carrier_aircraft",
                        "label": "Carrier aircraft",
                        "abrv": "C",
                        "color": "#49C5FF"
                    },
                    {
                        "code": "large_commercial",
                        "label": "Commercial carrier",
                        "abrv": "C",
                        "color": "#49C5FF"
                    },
                    {
                        "code": "fighter",
                        "label": "Fighter",
                        "abrv": "F",
                        "color": "#6CBE20"
                    },
                    {
                        "code": "bomber",
                        "label": "Bomber",
                        "abrv": "B",
                        "color": "#167DDE"
                    },
                    {
                        "code": "other_large_military",
                        "label": "Large military",
                        "abrv": "M",
                        "color": "#E4032B"
                    },
                    {
                        "code": "helicopter",
                        "label": "Helicopter",
                        "abrv": "H",
                        "color": "#F5A623"
                    },
                    {
                        "code": "small_aircraft",
                        "label": "Small aircraft and other",
                        "abrv": "S",
                        "color": "#FF92C7"
                    }
                ]
            },
            "qualityControl": {
                "default": "auto",
                "availableModes": [
                    "auto"
                ]
            }
        }
    ]
}

The sensor indicates which constellation / resolution this analytic supports. Selected images must be in a supported resolution.

The type indicates the number of images this analytic requires objects analytics run on a single image to detect elements changes analytics compare a pair of images

If there are a lot of results, there is a pagination mechanism, you can use the itemsPerPage parameter to set the number of results per page and page parameter to navigate through the pages.

Search Images

To place an order for an Analytics Toolbox report, you will also need the id of the image(s) on which you want to run the analytic.

See our detailed Search Guide for information on how to search images within One Atlas.

Note: Only PRIMARY images are fully supported by all analytics therefore the images you use must have processingLevel=SENSOR

The endpoint to search images is:

API Endpointhttps://search.foundation.api.oneatlas.airbus.com/api/v1/opensearch
REST verbGET
AuthenticationJWT Token
API ReferenceSearch API

For our example, we will search all PHR images available on our AOI between May 1st and Aug 31st 2019, that have no more that 10% clouds, a maximum incidence angle of 20° and have SENSOR processingLevel.

In this case the JSON structure would be:

{
    "constellation":"PHR",
    "itemsPerPage": 100,
    "processingLevel": "SENSOR",
    "cloudCover":"[0,10]",
    "incidenceAngle":"[0,20]",  
    "acquisitionDate":"[2022-01-01T00:00:00.000Z,2022-01-31T00:00:00.000Z]",
    "relation":"intersects",
    "geometry":{
        "type": "Polygon",
        "coordinates": [
            [
                [-115.257324821538006, 36.135202530042903],
                [-115.119528582773995, 36.137064237966598],
                [-115.118644547198002, 36.062608357774501],
                [-115.256536683516998, 36.062233041334402],
                [-115.257324821538006, 36.135202530042903]
            ]
        ]
    }
}

We will pick the 2 following images: 37bbfd56-7230-4875-a85f-5d9dc4b6e440 and 95e0b8fc-7bd1-404f-8f9c-a1798a45d57a

Calculate the Price of an Analytic Report

When calculating the price of an Analytic Report, you must provide the following parameters.

aoiThe AOI must be described as GeoJSON geometry. Only polygons are accepted.
analyticThe code of the analytic to run.
resolutionThe imagery resolution in meters. Accepted values are either 0.5 for Pléiades or 1.5 for SPOT. Some analytics only work on specific resolution, see analytics sensor.
imageIdsThe code of the image(s). The analytic type indicate the number of images to provide: objects analytics require 1 image while changes analytics require 2 images.
titleThe name/reference you want to give the report.

The endpoint to get a price for an Analytic Report is:

API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/prices
REST verbPOST
AuthenticationJWT Token
API ReferenceOrder API

The only and mandatory parameter is a JSON payload following this schema:

{
    "kind": "order.analytics-toolbox.archive",
    "aoi": {
        "type": "Polygon",
        "coordinates": [
            [
                [-115.257324821538006, 36.135202530042903],
                [-115.119528582773995, 36.137064237966598],
                [-115.118644547198002, 36.062608357774501],
                [-115.256536683516998, 36.062233041334402],
                [-115.257324821538006, 36.135202530042903]
            ]
        ]
    },
    "analytic": "analytic.airbus.change-detection",
    "resolution": 0.5,
    "imageIds": [
        "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
        "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
    ],  
    "title": "Change Detection - Las Vegas"
}

Below is an example of the call:

curl -X POST \
  'https://data.api.oneatlas.airbus.com/api/v1/prices' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'
  -d '{
    "kind": "order.analytics-toolbox.archive",
    "aoi": {
        "type": "Polygon",
        "coordinates": [
            [
                [-115.257324821538006, 36.135202530042903],
                [-115.119528582773995, 36.137064237966598],
                [-115.118644547198002, 36.062608357774501],
                [-115.256536683516998, 36.062233041334402],
                [-115.257324821538006, 36.135202530042903]
            ]
        ]
    },
    "analytic": "analytic.airbus.change-detection",
    "resolution": 0.5,
    "imageIds": [
        "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
        "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
    ],  
    "title": "Change Detection - Las Vegas"
}

The response is shown below:

{
    "payload": {
        "kind": "order.analytics-toolbox.archive",
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-115.257324821538006, 36.135202530042903],
                    [-115.119528582773995, 36.137064237966598],
                    [-115.118644547198002, 36.062608357774501],
                    [-115.256536683516998, 36.062233041334402],
                    [-115.257324821538006, 36.135202530042903]
                ]
            ]
        },
        "analytic": "analytic.airbus.change-detection",
        "resolution": 0.5,
        "imageIds": [
            "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
            "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
        ],
        "title": "Change Detection - Las Vegas",
        "qualityControl": "standard"
    },
    "deliveries": [
        {
            "kind": "delivery.analytics-toolbox.report",
            "datas": {
                "kind": "order.analytics-toolbox.archive",
                "aoi": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [-115.257324821538006, 36.135202530042903],
                            [-115.119528582773995, 36.137064237966598],
                            [-115.118644547198002, 36.062608357774501],
                            [-115.256536683516998, 36.062233041334402],
                            [-115.257324821538006, 36.135202530042903]
                        ]
                    ]
                },
                "analytic": "analytic.airbus.change-detection",
                "resolution": 0.5,
                "imageIds": [
                    "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
                    "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
                ],
                "title": "Change Detection - Las Vegas",
                "analyticName": "Change Detection"
            },
            "isAmountEstimated": "false",
            "price": 709,
            "amount": 709,
            "amountUnit": "EUR",
            "area": "101.48",
            "unit": "km2"
        }
    ],
    "price": {
        "credits": 709,
        "amount": 709,
        "isAmountEstimated": "false",
        "areaKm2": 101.48,
        "amountUnit": "EUR"
    },
    "feasibility": "automatic",
    "orderable": "ok"
}

The results are split into three different sections; payload, deliveries and price. The payload shows the input that you have submitted to the server. The deliveries will contains the link to the report file once generated. The price indicate the amount of credits that the order will cost.

Order of an Analytic Report

Once you calculated the price of a report you can then place the order. To proceed, the following endpoint must be used:

API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/orders
REST verbPOST
AuthenticationJWT Token
API ReferenceOrder API

The payload of the order request is exactly like the one used to calculate the price:

{
    "kind": "order.analytics-toolbox.archive",
    "aoi": {
        "type": "Polygon",
        "coordinates": [
            [
                [-115.257324821538006, 36.135202530042903],
                [-115.119528582773995, 36.137064237966598],
                [-115.118644547198002, 36.062608357774501],
                [-115.256536683516998, 36.062233041334402],
                [-115.257324821538006, 36.135202530042903]
            ]
        ]
    },
    "analytic": "analytic.airbus.change-detection",
    "resolution": 0.5,
    "imageIds": [
        "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
        "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
    ],  
    "title": "Change Detection - Las Vegas"
}

Below is an example of the call:

curl -X POST \
  'https://data.api.oneatlas.airbus.com/api/v1/prices' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'
  -d '{
    "kind": "order.analytics-toolbox.archive",
    "aoi": {
        "type": "Polygon",
        "coordinates": [
            [
                [-115.257324821538006, 36.135202530042903],
                [-115.119528582773995, 36.137064237966598],
                [-115.118644547198002, 36.062608357774501],
                [-115.256536683516998, 36.062233041334402],
                [-115.257324821538006, 36.135202530042903]
            ]
        ]
    },
    "analytic": "analytic.airbus.change-detection",
    "resolution": 0.5,
    "imageIds": [
        "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
        "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
    ],  
    "title": "Change Detection - Las Vegas"
}

The response is shown below:

{
    "_links": {
        "self": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/01ff8528-e42f-43bd-9473-260dbd177b5a"
        },
        "cancel": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/01ff8528-e42f-43bd-9473-260dbd177b5a/cancel"
        },
        "contract": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/contracts/070225dc-caaa-476c-ba8e-8c01d379de26"
        },
        "payments": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/01ff8528-e42f-43bd-9473-260dbd177b5a/payments"
        },
        "deliveries": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/01ff8528-e42f-43bd-9473-260dbd177b5a/deliveries"
        },
        "subscription": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/subscriptions/25474831-2765-4bda-9e10-7e00971ac99a"
        },
        "reset": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/01ff8528-e42f-43bd-9473-260dbd177b5a/reset"
        }
    },
    "id": "01ff8528-e42f-43bd-9473-260dbd177b5a",
    "kind": "order.analytics-toolbox.archive",
    "service": "analytics-toolbox",
    "createdAt": "2019-08-22T09:28:02.754371+00:00",
    "createdBy": "7443d6bd-9319-40a2-00fb-9abda3dd5653",
    "status": "ordered",
    "contractId": "070225dc-caaa-476c-ba8e-8c01d379de26",
    "isAmountEstimated": "false",
    "price": 709,
    "amount": 709,
    "amountUnit": "credits",
    "payload": {
        "kind": "order.analytics-toolbox.archive",
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-115.257324821538006, 36.135202530042903],
                    [-115.119528582773995, 36.137064237966598],
                    [-115.118644547198002, 36.062608357774501],
                    [-115.256536683516998, 36.062233041334402],
                    [-115.257324821538006, 36.135202530042903]
                ]
            ]
        },
        "analytic": "analytic.airbus.change-detection",
        "resolution": 0.5,
        "imageIds": [
            "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
            "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
        ],  
        "title": "Change Detection - Las Vegas"
    },
    "deliveries": [
        {
            "_links": {
                "self": {
                    "href": "https://data.api.oneatlas.airbus.com/api/v1/deliveries/86433e23-3cf2-49a5-98a6-456dd6369db1"
                },
                "contract": {
                    "href": "https://data.api.oneatlas.airbus.com/api/v1/contracts/070225dc-caaa-476c-ba8e-8c01d379de26"
                }
            },
            "id": "86433e23-3cf2-49a5-98a6-456dd6369db1",
            "kind": "delivery.analytics-toolbox.report",
            "service": "analytics-toolbox",
            "createdAt": "2019-08-22T09:28:03.146330+00:00",
            "status": "processing",
            "isAmountEstimated": "false",
            "price": 709,
            "amount": 709,
            "amountUnit": "credits",
            "area": "101.48",
            "unit": "km2",
            "datas": {
                "kind": "order.analytics-toolbox.archive",
                "analytic": "analytic.airbus.change-detection",
                "aoi": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [-115.257324821538006, 36.135202530042903],
                            [-115.119528582773995, 36.137064237966598],
                            [-115.118644547198002, 36.062608357774501],
                            [-115.256536683516998, 36.062233041334402],
                            [-115.257324821538006, 36.135202530042903]
                        ]
                    ]
                },
                "resolution": 0.5,
                "imageIds": [
                    "37bbfd56-7230-4875-a85f-5d9dc4b6e440",
                    "95e0b8fc-7bd1-404f-8f9c-a1798a45d57a"
                ],
                "title": "Change Detection - Las Vegas",
                "analyticName": "Change Detection"
            },
            "updatedAt": "2022-02-22T09:28:03.945650+00:00"
        }
    ]
}

The results give you the id of the order.

Order Status

To get the most current order status, you can call the following endpoint using the id obtained above.

API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/orders/
REST verbGET
AuthenticationJWT Token
API ReferenceOrder API
curl -X GET \
  'https://data.api.oneatlas.airbus.com/api/v1/orders/<order_id>' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Note: You can also just follow the link _links.self.href in the response above to get the most recent result.

The order status will say ordered while it is being processed. Once the report produced, the order will switch to delivered. The order can have the following statuses:

StatusAn error occurred during the production process.
errorPOST
deliveredThe report has been produced and available in your private workspace.
orderedThe report has just been ordered and will be processed; the production is in progress.
rejectedThe order has been rejected, insufficient balance.

List Orders

The /orders endpoint can be used to retrieve your orders:

API Endpointhttps://data.api.oneatlas.airbus.com/api/v1/orders/
REST verbPOST
AuthenticationJWT Token
API ReferenceOrder API

A filter could be associated to this request to display orders that have a specific status.

For example, listing the 10 last delivered orders could be requested by using the following:

curl -X GET \
  'https://data.api.oneatlas.airbus.com/api/v1/orders?status=delivered&kind=order.analytics-toolbox.archive&page=1&itemsPerPage=10' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

If there are a lot of results, there is a pagination mechanism, you can use the itemsPerPage parameter to set the number of results per page and page parameter to navigate through the pages.

Retrieve the Report

Once your order status is delivered, the deliveries[0]._links.download.href in the order response will contain a link to download your report.

You can then send a GET request to output your file as a geojson file:

curl -X GET \
  'https://access.foundation.api.oneatlas.airbus.com/api/v1/items/90ebd420-fab4-49b7-85cd-ced051ea2343/download' \
  -H 'Authorization: Bearer <access_token>' \
  -o output_file.geojson

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

Contact Us