Language
In this Tutorial
  1. Detect changes
    1. Authenticate
    2. Get service health status
    3. Order "monitoring and change detection" subscription
      1. Check your balance
      2. Calculate a change detection price
      3. Order a change detection
      4. Follow up your order
    4. Exploit the results of your order
      1. Retrieve your results
      2. Access images in streaming
      3. Download GeoJSON report

Detect changes

This tutorial will guide you through the process of ordering a change detection subscription. This will allow you to receive a regular report on man-made changes on your AOI.

Authenticate

First lets authenticate using your API Key and retrieve an access token. This will be used as a ‘Bearer Token’ to call services. You can get your API Key by using our API Key Generator.


Once you have your API Key use the endpoint /auth/realms/IDP/protocol/openid-connect/token to authenticate:

curl -X POST \
  https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'apikey=<api_key>&grant_type=api_key&client_id=IDP'
Not available.
headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
}

data = [
  ('apikey', '<api_key>'),
  ('grant_type', 'api_key'),
  ('client_id', 'IDP'),
]

response = requests.post('https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token', headers=headers, data=data, verify=False)

print(response.text)

Extract the access token from JSON data:

{
    "access_token": "<access_token>",
    "expires_in": 3600,
    "refresh_expires_in": 0,
    "token_type": "bearer"
}

Get service health status

Retrieve platform health status using endpoint /api/v1/health:

curl -X GET https://data.api.oneatlas.airbus.com/api/v1/health \
  -H 'Authorization: Bearer <access_token>'
Not available.
headers = {
    'Authorization': 'Bearer <access token>'
}

response = requests.get('https://data.api.oneatlas.airbus.com/api/v1/health', headers=headers, verify=False)

print (response.text);
{
    "status": "ok"
}

Order “monitoring and change detection” subscription

You should now be authenticated with a healthy service status. This next section will now guide you through the steps for ordering a a change detection subscription.

Check your balance

In order to get information about your balance call the API endpoint /api/v1/me:

curl -X GET https://data.api.oneatlas.airbus.com/api/v1/me \
  -H 'Authorization: Bearer <access_token>'
Not available.
headers = {
    'Authorization': 'Bearer <access token>'
}

response = requests.get('https://data.api.oneatlas.airbus.com/api/v1/me', headers=headers, verify=False)

print (response.text);

Examine the output (JSON format) and focus on “credit” within “contract” object:

    "contract": {
        "_links": {
        ...
            }
        },
        ...
        "balance": 500
        ...
}

Calculate a change detection price

When placing a change detection order, you can filter your subscription by using our parameters. This includes area of interest, monitoring frequency, monitoring duration and resolution of the imagery. In this example we specify an AOI and want to retrieve the price for a monthly change detection report for a duration of 3 months:

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.change-detection.monitoring",
  "title": "test",
  "aoi": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            1.1700439453125,
            43.48281929474004
          ],
          [
            1.3568115234375,
            43.48281929474004
          ],
          [
            1.3568115234375,
            43.624147145668076
          ],
          [
            1.1700439453125,
            43.624147145668076
          ],
          [
            1.1700439453125,
            43.48281929474004
          ]
        ]
      ]
    },
    "resolution":0.5,
    "frequency":"monthly",
    "duration":3      
  }
}'
Coming soon...
Coming soon...

Order a change detection

The example below shows an example of change detection using a specified AOI, with a monthly frequency for a duration of 3 months. More information on our parameters can be found in our change detection order guide.

curl -X POST \
  https://data.api.oneatlas.airbus.com/api/v1/orders \
  -H 'authorization: Bearer <access_token>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "kind": "order.monitoring.change-detection",  
  "subscription": {
    "type": "change-detection",
    "title" : "",
    "aoi": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            1.1700439453125,
            43.48281929474004
          ],
          [
            1.3568115234375,
            43.48281929474004
          ],
          [
            1.3568115234375,
            43.624147145668076
          ],
          [
            1.1700439453125,
            43.624147145668076
          ],
          [
            1.1700439453125,
            43.48281929474004
          ]
        ]
      ]
    },
    "resolution":0.5,
    "frequency":"monthly",
    "duration": 3
  }
}'
Not available
Not available.

This will return confirmation with the status ordered :

{
    "id": "9e01aca3-d72b-4609-9ef4-9c7f5bd15142",
    "_links": {
        "self": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/9e01aca3-d72b-4609-9ef4-9c7f5bd15142"
        },
        "contract": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/contracts/1a3104c2-ea70-4e15-b0a8-267ac61d5542"
        },
        "payments": {
            "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/9e01aca3-d72b-4609-9ef4-9c7f5bd15142/payments"
        }
    },
    "kind": "order.subscription.change-detection",
    "createdAt": "2018-09-07T07:40:43.198782+00:00",
    "createdBy": "e52becd2-64ae-409b-cb54-f432c19118e7",
    "status": "ordered",
    "contractId": "1a3104c2-ea70-4e15-b0a8-267ac61d5542",
    "payload": {
        "kind": "order.subscription.change-detection",
        "subscription": {
            "type": "change-detection",
            "title": "",
            "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            1.1700439453125,
                            43.48281929474004
                        ],
                        [
                            1.3568115234375,
                            43.48281929474004
                        ],
                        [
                            1.3568115234375,
                            43.624147145668076
                        ],
                        [
                            1.1700439453125,
                            43.624147145668076
                        ],
                        [
                            1.1700439453125,
                            43.48281929474004
                        ]
                    ]
                ]
            },
            "resolution": 0.5,
            "frequency": "monthly",
            "duration": 3,
            "startedAt": "2200-02-12"
        }
    }
}

Follow up your order

To get information about the status of your orders, you can call the API endpoint /api/v1/contracts/<contract_id>/. The example below will return all the change detection subscriptions you have purchased for your contract id:

curl -X GET \
  'https://data.api.oneatlas.airbus.com/api/v1/contracts/<contract_id>/subscriptions?type=change-detection' \
  -H 'authorization: Bearer <access_token>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
Not available.
headers = {
    'Authorization': 'Bearer <access_token>',
    'Content-Type': 'application/json',
}

response = requests.get('https://data.api.oneatlas.airbus.com/api/v1/contracts/<contract_id>/subscriptions?type=change-detection', headers=headers)

print (response.text);

Here you can see the change detection subscription including details about the AOI, duration and resolution:

{
    "startIndex": 0,
    "totalResults": 1,
    "itemsPerPage": 10,
    "items": [
        {
            "id": "19389e09-81fd-46bb-be57-a96381772394",
            "_links": {
                "self": {
                    "href": "https://data.api.oneatlas.airbus.com/api/v1/subscriptions/19389e09-81fd-46bb-be57-a96381772394"
                },
                "payments": {
                    "href": "https://data.api.oneatlas.airbus.com/api/v1/subscriptions/19389e09-81fd-46bb-be57-a96381772394/payments"
                },
                "order": {
                    "href": "https://data.api.oneatlas.airbus.com/api/v1/orders/c64b42b9-5278-406a-8039-10c95ec04f84"
                }
            },
            "title": "test-jro",
            "status": "active",
            "startedAt": "2018-07-15T09:21:31.552983+00:00",
            "endedAt": "2018-10-15T09:21:31.552983+00:00",
            "type": "change-detection",
            "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            1.1700439453125,
                            43.48281929474004
                        ],
                        [
                            1.3568115234375,
                            43.48281929474004
                        ],
                        [
                            1.3568115234375,
                            43.624147145668076
                        ],
                        [
                            1.1700439453125,
                            43.624147145668076
                        ],
                        [
                            1.1700439453125,
                            43.48281929474004
                        ]
                    ]
                ]
            },
            "resolution": 0.5,
            "frequency": "monthly",
            "duration": 3,
            "runs": {
                "totalAmountOfRun": 3,
                "workflows": [
                    {
                        "id": "299cfe2f-676a-47c2-af0e-c2590375606b",
                        "startedAt": "2018-08-15T00:00:04.964907+00:00",
                        "endedAt": null,
                        "status": "started"
                    },
                    {
                        "id": "1e4341c8-1201-42a7-b3c7-c843b5499c38",
                        "startedAt": "2018-07-15T09:39:10.368020+00:00",
                        "endedAt": null,
                        "status": "error"
                    }
                ]
            }
        }
    ]
}

Exploit the results of your order

You should now have a change detection subscription with your specified AOI and frequency. These next steps will focus on making full use of your order to stream and retrieve change detection reports.

Retrieve your results

To access your change detection results you need to use the /opensearch endpoint. Rather than search for everything, we need to filter for results within our workspace. To do so, you need your workspaceId which you can retrieve this from the /me endpoint. More information relating to the /me endpoint can be found within the subscription status section of the tutorials.


An example request is shown below:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch/opensearch?workspaceId=<workspace_id>' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch/opensearch?workspaceId=<workspace_id>");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch/opensearch"

querystring = {"workspaceId":"<workspace_id>"}

headers = {
    'Content-Type': "application/json",
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache",
    }

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Here is an example of subscription information returned:


            "_links": {
                "download": {
                    "href": "/api/v1/items/c546e2cd-3cd2-4e92-af04-afb2cd4bf5f0/download",
                    "name": "Download"
                },
                "geojson": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/c546e2cd-3cd2-4e92-af04-afb2cd4bf5f0/download/geojson",
                    "name": "Download geojson",
                    "type": "application/vnd.geo+json"
                },
                "delete": {
                    "href": "https://workspaces.oneatlas.private.geoapi-airbusds.com/api/v1/workspaces/af1a2a41-fcec-4ecf-9b44-1941b5808911/items/c546e2cd-3cd2-4e92-af04-afb2cd4bf5f0",
                    "name": "Delete",
                    "type": "HTTP"
                },
                "catalogInputs": {
                    "href": "https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?id=46d04255-6f5f-4c2c-8cda-04daab2dc42d,262c6d3a-9cfa-4c7b-ab1d-c6b3c0d5f794",
                    "name": "Input Images",
                    "type": "HTTP"
                }
            },
            "geometry": {
                "coordinates": [
                    [
                        [
                            -122.12814331054686,
                            37.43234100120862
                        ],
                        [
                            -121.97776794433594,
                            37.43234100120862
                        ],
                        [
                            -121.97776794433594,
                            37.3278093
                        ],
                        [
                            -122.12814331054686,
                            37.3278093
                        ],
                        [
                            -122.12814331054686,
                            37.43234100120862
                        ]
                    ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "acquisitionDate_T0": "2018-03-28T18:35:49Z",
                "acquisitionDate_T1": "2017-09-01T18:33:48Z",
                "correlationId": "258aba9f-f1f3-4638-bd20-677f348e5ca2",
                "expirationDate": "2019-07-13T16:11:16.248042397Z",
                "featureCount": 796,
                "format": "application/vnd.geo+json",
                "id": "c546e2cd-3cd2-4e92-af04-afb2cd4bf5f0",
                "productCategory": "vector",
                "productType": "changeDetectionReport",
                "projectTitle": "San Jose",
                "publicationDate": "2018-07-13T16:11:16.248042397Z",
                "sourceId_T0": "46d04255-6f5f-4c2c-8cda-04daab2dc42d",
                "sourceId_T1": "262c6d3a-9cfa-4c7b-ab1d-c6b3c0d5f794",
                "sourceIdentifier_T0": "SEN_SPOT7_20170901_183349800_000",
                "sourceIdentifier_T1": "SEN_SPOT7_20180328_183549300_000",
                "srs": {
                    "names": [
                        {
                            "type": "urn",
                            "value": "urn:ogc:def:crs:EPSG::4326"
                        }
                    ]
                },
                "title": "features_job_San_Jose_simplify.json",
                "workspaceId": "af1a2a41-fcec-4ecf-9b44-1941b5808911",
                "workspaceName": "bellproud",
                "workspaceTitle": "bellproud"
            },
            "rights": {
                "browse": {
                    "privileges": [
                        {
                            "id": "1f9e1f33-0f53-46c8-9edc-52c340cb2a7e",
                            "subscriptionId": "6e19db81-7cbb-4ce5-ae61-9c2d65bb561e",
                            "filter": {
                                "workspaceId": "af1a2a41-fcec-4ecf-9b44-1941b5808911"
                            }
                        }
                    ]
                },
                "download": {
                    "privileges": [
                        {
                            "id": "1f9e1f33-0f53-46c8-9edc-52c340cb2a7e",
                            "subscriptionId": "6e19db81-7cbb-4ce5-ae61-9c2d65bb561e",
                            "filter": {
                                "workspaceId": "af1a2a41-fcec-4ecf-9b44-1941b5808911"
                            }
                        }
                    ]
                },
                "wms": {
                    "privileges": [
                        {
                            "id": "1f9e1f33-0f53-46c8-9edc-52c340cb2a7e",
                            "subscriptionId": "6e19db81-7cbb-4ce5-ae61-9c2d65bb561e",
                            "filter": {
                                "workspaceId": "af1a2a41-fcec-4ecf-9b44-1941b5808911"
                            }
                        }
                    ]
                },
                "wmts": {
                    "privileges": [
                        {
                            "id": "1f9e1f33-0f53-46c8-9edc-52c340cb2a7e",
                            "subscriptionId": "6e19db81-7cbb-4ce5-ae61-9c2d65bb561e",
                            "filter": {
                                "workspaceId": "af1a2a41-fcec-4ecf-9b44-1941b5808911"
                            }
                        }
                    ]
                }
            },
            "type": "Feature"
        },

Access images in streaming

You can access the results of the two images which are to be compared through the catalogInput url in the previous step. Alternatively if you know the two image id’s, you can input these into your search:

curl -X GET \
  'https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?id=<image_id_1>,<image_id_2>' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch?id=<image_id_1>,<image_id_2>");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

import requests

url = "http://https://search.oneatlas.geoapi-airbusds.com/api/v1/opensearch"

querystring = {"id":"<image_id_1>,<image_id_2>"}

headers = {
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache",
    'Content-Type': "application/json",
    }

response = requests.request("GET", url, headers=headers, params=querystring, verify=False)

print(response.text)

This will return the WMS/WMTS requests to allow you to stream both images:

{
    "error": false,
    "features": [
        {
            "_links": {
                "wmts": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/items/<image_id>/wmts",
                    "name": "WMTS",
                    "type": "WMTS"
                },
                "wms": {
                    "href": "https://view.oneatlas.geoapi-airbusds.com/api/v1/<image_id>/wms",
                    "name": "WMS",
                    "type": "WMS"
                },

results continued...

Download GeoJSON report

In your results you will be provided with a download url in order to retrieve your GeoJSON change detection report. Alternatively, you can use the following request:

curl -k -o your_file_name.json \
  https://view.oneatlas.geoapi-airbusds.com/api/v1/items/<image_id>/download \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://view.oneatlas.geoapi-airbusds.com/items/<image_id>/download");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "https://view.oneatlas.geoapi-airbusds.com/<image_id>/download"

headers = {
    'Content-Type': "application/json",
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache",
    }

r = requests.request("GET", url, headers=headers, verify=False)

with open("name_of_file.json", "wb") as code:
    code.write(r.content)