Download REST API

This section describes a general workflow for a set of APIs designed to crop the satellite imagery by a bounding box, evaluate spectral indices and estimate statistics for an area of interest over a time series.

For more info on each task available refer to:

To use the aforementioned APIs some simple steps must be followed which are described below.

Create a new task

To create a new task, send a POST request to the service. The request body must follow the format described in either Download Analytic, Download Visual, Download Indices or Download Multi-Temporal Statistics.

POST /api?api_key=<API_KEY>
Query Parameters:
 
  • api_key – (required) user’s API key
Request JSON Object:
 
  • task_id – task identifier

Example. Download a panchromatic band of a Landsat 8 scene cropped to a bounding box

Example request (see Download Analytic):

http

POST /api?api_key=XXX HTTP/1.1
Host: gdw.eos.com
Accept: application/json
Content-Type: application/json

{
    "type": "lbe",
    "params": {
        "view_id": "L8/LC80290332017076LGN00",
        "bands": ["B8"],
        "bbox": [-98.125390625, 38.98520989992523, -98.00079345703125, 39.0666473843245],
        "merge": false
    }
}

curl

curl -i -X POST 'https://gdw.eos.com/api?api_key=XXX' -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"params": {"bands": ["B8"], "bbox": [-98.125390625, 38.98520989992523, -98.00079345703125, 39.0666473843245], "merge": false, "view_id": "L8/LC80290332017076LGN00"}, "type": "lbe"}'

If a task has been created successfully, the server responds with 202 Accepted. The response body shall contain a unique task identifier:

HTTP/1.1 202 Accepted
X-Request-Id: 51b3e178-d328-491b-9559-bc8ccf61846e
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8

{"status": "authentication", "task_id": "fc27872d-7ef3-433c-9e06-90a072a7e6eb"}

Check status of the task

After a successful POST, we can access the task by sending a GET request to the service specifying the task_id:

GET /api/(task_id)?api_key=<API_KEY>
Parameters:
  • task_id – (requires) task identifier
Query Parameters:
 
  • api_key – (required) user’s API key

Example. Check the status of the created task

http

GET /api/fc27872d-7ef3-433c-9e06-90a072a7e6eb?api_key=XXX HTTP/1.1
Host: gdw.eos.com

curl

curl -i 'https://gdw.eos.com/api/fc27872d-7ef3-433c-9e06-90a072a7e6eb?api_key=XXX'

Successful Responses

Task started

The following response indicates that the task had been received and the processing had started. Wait some time and then repeat the request to update the task status.

HTTP/1.1 200 OK
Content-Type: application/json

{
        "task_type": "started",
        "reference": null,
        "token": "apk.e9c25096d90787dd0f21a0ea1946dd6635556ccec7d4145f4402aea843748e49",
        "result_url": "https://lvproc-result.s3.amazonaws.com/1111.kmz",
        "client_id": 0,
        "download_id": 0
}

Task finished

The following responses indicate that the processing had been finished successfully.

Task finished for a download

The tasks designed for download (Download Analytic, Download Visual, Download Indices) provide a URL of a resulting file on AWS S3. Follow the redirect to download the result:

Example response:

HTTP/1.1 303 See Other
Content-Type: text/plain; charset=utf-8
Location: https://lvproc-result.s3.amazonaws.com/test_download_api.tif
Task finished for a time series analysis

The tasks Download Multi-Temporal Statistics provides a response in JSON (Content-Type is application/json). Save the response.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "errors": [{
            "status": false,
            "date": "2018-09-30",
            "scene_id": "LC08_L1TP_180026_20180930_20181010_01_T1",
            "error": "Scene with given ID does not exist"
    }],
    "result": [{
            "q1": 0.0205063559114933,
            "q3": 0.02711761463433504,
            "min": 0.01099664717912674,
            "p90": 0.029728015884757042,
            "max": 0.04058815538883209,
            "average": 0.023794656071338915,
            "median": 0.02409234829246998,
            "p10": 0.016829398274421693,
            "date": "2018-01-26",
            "scene_id": "LC08_L1TP_179026_20180126_20180126_01_RT",
            "variance": 2.458548522568638e-05,
            "cloud": 0.0
    }, {
            "q1": 0.18435029685497284,
            "q3": 0.20106831938028336,
            "min": -0.05357639864087105,
            "p90": 0.21829643845558175,
            "max": 0.7094192504882812,
            "average": 0.1850922020896449,
            "median": 0.19363175332546234,
            "p10": 0.07619943767786028,
            "date": "2018-08-13",
            "scene_id": "LC08_L1TP_180026_20180813_20180828_01_T1",
            "variance": 0.00861295855986984,
            "cloud": 0.0
    }]
}