Introduction

Welcome to the AρρEEARS API! This API allows users to write programs to interact with AρρEEARS. This is largely the same API that powers the AρρEEARS user interface.

The AρρEEARS API adheres to basic REST principles. The API has predictable resource-oriented URLs and uses HTTP response codes to indicate success or failure of API calls. The API uses JSON for all request and response payloads and makes use of standard HTTP constructs which are understood by publicly availabile HTTP clients and code modules.

The AρρEEARS API is segmented into several endpoints to logically divide the different resources available. Some endpoints require an authentication token which is necessary for resources that are directly associated with a user account. See the Authentication section for more details.

Please send any questions or feedback you may have through the AppEEARS Feedback Form. The API is currently in a non-operational Beta release and we appreciate all comments, questions, and suggestions.

Login

The API leverages the same NASA Earthdata Login as the AρρEEARS user interface. In addition to having a valid NASA Earthdata Login account, the API feature must be enabled for the user within AρρEEARS. See the AρρEEARS help documentation for more details on enabling this for your user account.

Whenever a request is made to one of the secure API endpoints, HTTP Basic Authentication credentials are required. Authentication first requires a call to the login service using the NASA Earthdata Login username and password to generate a Bearer token. This Bearer token will be then used for all subsequent calls to secure endpoints. This token will expire approximately 48 hours after being acquired. All programs should check for an HTTP 403 Forbidden status code to successfully handle token expiration by acquiring a new token.

POST
/login

Example request

$ curl --request POST --user your-username:your-password --header "Content-Length: 0" "https://lpdaacsvc.cr.usgs.gov/appeears/api/login"

Example response for a successful login

{
    "token_type": "Bearer",
    "token": "31ncqphv-1jpPjcTe-hgWXM2xZ1bBqQxST5pcieiHKq0cMwz8IFKOxG3FZgLQonk8hBsLV_ruAqikYXfzWy7kw",
    "expiration": "2017-10-12T19:32:05Z"
}

Example response for a user that doesn't have the API enabled

{
    "message": "API access is not enabled.  See the API Login Documentation to enable API access for the user account."
}

Example response for invalid user/password combination

{
    "message": "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required."
}

Logout

The API also supports disposing of an authentication prior to its expiration date/time. This is a secure endpoint which will require the Bearer token acquired by a /login call to be passed in via an Authorization header. The Authorization header must be in the form of Authorization: Bearer <your-token>.

e.g. Authorization: Bearer hgWXM2xZ1bBqQxST5pcieiHKq...

POST
/logout

Example request

$ curl --request POST --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/logout"

Example response for a successful logout

HTTP 204 No Content

Example response for a token that has already expired

{
  "message": "You don't have the permission to access the requested resource. It is either read-protected or not readable by the server."
}

Pagination

API resources that can possibly return many results will provide query parameters to limit the number of results that are returned by a single request. The API utilizes a cursor-based pagination mechanism allowing you to specify a limit to the number of results returned and an offset into the desired results.

For example, you would specify limit=10&offset=0 for the first 10 results, limit=10&offset=10 for the next 10 results, etc. If the number of results returned is less than the limit number specified, you've reached the end of the list of results.

Query Parameter Description
limit The maximum number of results to return. If the number of results returned is less than the specified limit , the end of the results has been reached.
offset The number of results to skip before starting to return them.

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/product?limit=2&offset=2"

Example response

[
    {
        "Product": "GPW_UN_Adj_PopDensity",
        "Platform": "GPW",
        "Description": "UN-adjusted population density",
        "RasterType": "Tile",
        "Resolution": "1000m",
        "TemporalGranularity": "Quinquennial",
        "Version": "004",
        "Available": true,
        "DocLink": "http://dx.doi.org/10.7927/H4HX19NJ",
        "Source": "SEDAC",
        "TemporalExtentStart": "2000",
        "TemporalExtentEnd": "2020",
        "ProductAndVersion": "GPW_UN_Adj_PopDensity.004",
        "DOI": ""
    },
    {
        "Product": "GPW_UN_Adj_PopCount",
        "Platform": "GPW",
        "Description": "UN-adjusted Population Count",
        "RasterType": "Tile",
        "Resolution": "1000m",
        "TemporalGranularity": "Quinquennial",
        "Version": "004",
        "Available": true,
        "DocLink": "http://dx.doi.org/10.7927/H4SF2T42",
        "Source": "SEDAC",
        "TemporalExtentStart": "2000-01-01",
        "TemporalExtentEnd": "2020-12-31",
        "Deleted": false,
        "DOI": "10.7927/H4SF2T42",
        "ProductAndVersion": "GPW_UN_Adj_PopCount.004"
    }
]

Formatting

API resources that can return a large JSON response include support for an additional formatting option. The additional formatting is optional and can be enabled by specifying the pretty parameter. This behavior is disabled by default as it does increase the size of the JSON response, but it can make the response much easier to read.

Query Parameter Description
pretty A boolean used to toggle formatting, either true or false .

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/product/SRTMGL1.003?pretty=true"

Example response

{
    "Band1": {
        "AddOffset": "",
        "Available": true,
        "DataType": "int16",
        "Description": "Elevation",
        "Dimensions": [
            "time",
            "lat",
            "lon"
        ],
        "FillValue": -32768,
        "Layer": "Band1",
        "OrigDataType": "int16",
        "OrigValidMax": 32767,
        "OrigValidMin": -32767,
        "QualityLayers": "['Band1']",
        "QualityProductAndVersion": "SRTMGL1N.003",
        "ScaleFactor": "",
        "Units": "Meters",
        "ValidMax": 32767,
        "ValidMin": -32767,
        "XSize": 3601,
        "YSize": 3601
    }
}

Caching

API calls that return data will include ETag and Last-Modified headers. These can be used to make subsequent requests using the If-None-Match and If-Modified-Since headers respectively. If the resource matches the specified ETag or has not changed since the Last-Modified timestamp, the server will return a 304 Not Modified response.

Please note that the ETag value contains double quotation marks (e.g. "lpdms-1508507462.2111995-40336-2044139119") and must be included in its entirety when submitting a conditional request.

Example request

$ curl --include "https://lpdaacsvc.cr.usgs.gov/appeears/api/product"

Example response

HTTP/1.0 200 OK
Content-Type: application/json
Cache-Control: private, no-transform, must-revalidate, max-age=0
Expires: Mon, 23 Oct 2017 12:46:07 GMT
ETag: "lpdms-1508507462.2111995-40336-2044139119"
Last-Modified: Fri, 20 Oct 2017 13:51:02 GMT
Content-Length: 64154

Example conditional request based on ETag

$ curl --include --header "If-None-Match: \"lpdms-1508507462.2111995-40336-2044139119\"" "https://lpdaacsvc.cr.usgs.gov/appeears/api/product"

Example response

HTTP/1.0 304 NOT MODIFIED
Cache-Control: private, no-transform, must-revalidate, max-age=0
Expires: Mon, 23 Oct 2017 12:52:02 GMT
ETag: "lpdms-1508507462.2111995-40336-2044139119"

Example conditional request based on Last-Modified

$ curl --include --header "If-Modified-Since: Fri, 20 Oct 2017 13:51:02 GMT" "https://lpdaacsvc.cr.usgs.gov/appeears/api/product"

Example response

HTTP/1.0 304 NOT MODIFIED
Cache-Control: private, no-transform, must-revalidate, max-age=0
Expires: Mon, 23 Oct 2017 12:54:29 GMT
ETag: "lpdms-1508507462.2111995-40336-2044139119"

Tasks

Tasks in AρρEEARS correspond to each request associated with your user account. Therefore, each of the calls to this service require an authentication token as described above.

Task object

Tasks are defined as a JSON payload with several properties that are common between area and point sample requests. One simple way to view the properties for a task JSON is to observe the output request JSON from a completed AρρEEARS request or make an API call to list the tasks for your account as described below.

The following properties are required for all tasks.

Property Description
task_name The user-defined name of the task.
task_type The type of the task, either area or point .
params The parameters for the request, including the required dates and layers definition as well as any area or point specific parameters.
The dates parameter consists of a date_object and the layers parameter consists of one or more layer_object .

The date_object is defined as follows:

Property Description
startDate The start of the date range for which to extract data.

All date formats should be in MM-DD-YYYY format for non-recurring date ranges and MM-DD for recurring date ranges.
endDate The end of the date range for which to extract data.
recurring
(optional)
Specify true for a recurring date range.
yearRange
(optional)
Specify the starting and ending years for a recurring date range (e.g. [ 2010, 2015 ] ).

The layer_object is defined as follows:

Property Description
product The product and version identifier for the product (e.g. MOD11A1.006 ).
layer The name of the layer (e.g. LST_Day_1km ).

There are additional properties that are required for area requests.

Property Description
geo A GeoJSON object defining the spatial region of interest.
The projection of any coordinates must be in a geographic projection.
output The details about how the output files should be formatted.
The file_type must be one of geotiff or netcdf4 .
The projection_name must be one of the supported projections (e.g. native , geographic ). The list of supported projections can be generated via an API call described here .

There are additional properties that are required for point requests.

Property Description
coordinates A GeoJSON object defining the spatial region of interest.
The projection of any coordinates must be in a geographic projection.

id (optional) - User-defined unique string identifier for the coordinate that can be used to identify a specific coordinate.

category (optional) - User-defined string category used to group one or more coordinates.

latitude - Numeric geographic latitude for the coordinate.

longitude - Numeric geographic longitude for the coordinate.

Parameters required for all task requests

{
    "task_type": "{task_type}",
    "task_name": "{task_name}",
    "params":
    {
        "dates": [
            "startDate": "{startDate}",
            "endDate": "{endDate}",
            "recurring": true,
            "yearRange": [start,end]
        ],
        "layers": [
            "product": "{product_id}",
            "layer": "{layer_name}"
        ]
    }
}

Parameters required for all area requests

{
    "params":
    {
        "geo": "{GeoJSON}",
        "output":
        {
            "format":
            {
                "type": "{file_type}"
            },
            "projection": "{projection_name}"
        }
    }
}

Parameters required for all point requests

{
    "params":
    {
        "coordinates": [
          "latitude": "{latitude}",
          "longitude": "{longitude}",
          "id": "{id}",
          "category": "{category}"
        ]
    }
}

Task query parameters

In addition to the JSON payload described in the Task object, data passed into the URL's query string can be used to specify properties for the task.

If provided, query parameter properties take precedent over any JSON payload present. For instance, if the value for the task_name property in the task object is 'task1' and the query parameter for task_name with a value of 'task2' is provided, the value for task_name will be 'task2'.

Space and other white space characters must not be present in the query parameter values.

The parameters that are supported in the query string are listed in the tables below.

Parameters applicable to all requests:

Parameter Description
task_name The user-defined name of the task.
task_type The type of the task, either area or point .
startDate or start_date The start of the date range for which to extract data.

All date formats should be in MM-DD-YYYY format for non-recurring date ranges and MM-DD for recurring date ranges.
endDate or end_date The end of the date range for which to extract data.
recurring
(optional)
Specify true for a recurring date range.
yearRange or year_range
(optional)
Specify the starting and ending years for a recurring date range (e.g. 2010,2015 ).
layer The product and version identifier for the product and the name of the layer (e.g. MOD11A1.006,LST_Day_1km ).

Multiple layers can be specified by using multiple layer parameters (e.g. layer=MOD11A1.006,LST_Day_1km,
&layer=MOD11A1.006,LST_Night_1km ).

Parameters required for area requests:

Parameter Description
bbox A rectangular bounding box in the form of {min_longitude},{min_latitude},{max_longitude},{max_latitude} (lower left, upper right) where the longitude and latitude values are in a geographic projection (e.g. -96.626640,43.735557,-95.624623,44.736689 ).

Multiple bounding boxes can be specified by using multiple bbox parameters (e.g. bbox=-96.626640,43.735557,-95.624623,44.736689
&bbox=-76.852609,38.991712,-76.851965,38.992137 ).
polygon A polygon constructed from geographic coordinate vertices. The value must be in the form of {coordinate_1_longitude},{coordinate_1_latitude}...{coordinate_N_longitude},{coordinate_N_latitude} , where the last coordinate specified is the same as the first coordinate, closing the polygon (e.g. -96.625589,43.735247,-96.626823,43.736084,
-96.625750,43.737022,-96.623669,43.735495,
-96.624956,43.734751,-96.625589,43.735247 ).

Multiple polygons can be specified by using multiple polygon parameters (e.g. polygon=-96.625589,43.735247,-96.626823,43.736084,
-96.625750,43.737022,-96.623669,43.735495,
-96.624956,43.734751,-96.625589,43.735247&
polygon=-76.852455,38.991464,-76.853120,38.992023,
-76.852680,38.992590,-76.851500,38.992673,
-76.850760,38.991872,-76.852455,38.991464 ).
file_type The file format of the output files. It must be one of geotiff or netcdf4
projection_name The name of the projection of the output files. It must be one of the supported projections (e.g. native , geographic ). The list of supported projections can be generated via an API call described here .

At least one bbox or polygon parameter is required.

Parameters required for point requests:

Parameter Description
coordinate A coordinate in the form of {id},{category},{latitude},{longitiude} where id and category are optional (e.g. US-Ha1,DBF,42.5378,-72.1715 or 42.5378,-72.1715 ).

Multiple coordinates can be specified by using multiple coordinate parameters (e.g. coordinate=US-Ha1,DBF,42.5378,-72.1715&coordinate=US-Ha2,DBF,44.5378,-73.1715 ).

Parameters applicable to all task requests

task_name={task_name}&task_type={task_type}&startDate={startDate}&endDate={endDate}&recurring={recurring}&yearRange={yearRange}&layer={layer}

Parameters required for all area requests

bbox={bbox}&polygon={polygon}&file_type={file_type}&projection_name={projection_name}

Parameters required for all point requests

coordinate={coordinate}

List tasks

This API call will list all of the requests associated with your user account and supports pagination. The list will automatically be sorted by date descending with the most recent requests being listed first.

You can also filter the list of tasks by specifying the following optional query parameters.

Filter Parameter Description
status The status of the sample request (see table below).
task_type The type of sample request (e.g. point, area).

A task can be in one of several states.

Status Description
pending The task has been submitted and is waiting until resources are available before it begins processing.
processing The task is currently processing.
done The task has finished processing.
error An error occurred while processing the task and all retries have been exhausted.
GET
/task

Example request

$ curl --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task"

Example response

[{
    "attempts": 2,
    "created": "2017-09-07T16:01:08.263000",
    "error": None,
    "params":
    {
        "dates": [
        {
            "endDate": "10-31-2009",
            "startDate": "01-01-2009",
            "yearRange": [2000, 2050]
        }],
        "layers": [
        {
            "layer": "LST_Night_1km",
            "product": "MOD11A1.006"
        },
        {
            "layer": "QC_Night",
            "product": "MOD11A1.006"
        }],
        "output":
        {
            "format":
            {
                "type": "netcdf4"
            },
            "projection": "native"
        }
    },
    "retry_at": None,
    "status": "done",
    "svc_version": "1.9.1",
    "task_id": "4d9f7647-0319-4ab7-9c85-c82f4f574664",
    "task_name": "slow",
    "task_type": "area",
    "updated": "2017-09-07T16:50:40.917000",
    "user_id": "user@example.com",
    "web_version": "1.9.1"
},
{
    "attempts": 1,
    "created": "2017-09-05T14:16:21.638000",
    "error": None,
    "params":
    {
        "dates": [
        {
            "endDate": "07-01-2010",
            "startDate": "07-01-2010",
            "yearRange": [2000, 2050]
        }],
        "layers": [
        {
            "layer": "LC_Type1",
            "product": "MCD12Q1.006"
        }],
        "output":
        {
            "format":
            {
                "type": "geotiff"
            },
            "projection": "native"
        }
    },
    "retry_at": None,
    "status": "done",
    "svc_version": "1.9.1",
    "task_id": "7a71e792-139d-49c5-9b04-72fc95bca6bb",
    "task_name": "polygon",
    "task_type": "area",
    "updated": "2017-09-05T14:24:28.195000",
    "user_id": "user@example.com",
    "web_version": "1.9.1"
}]

Submit task

This API call provides a way to submit a new request to be processed. It can accept data via JSON, query string, or a combination of both. If both are specified, data from the query string takes precedent over JSON data (see query parameters for more information).

In order for your request JSON to be accepted, it must be defined with certain required properties as described in the task object section. In order for query string data to be accepted, it must be defined as described in the task query parameters section.

When a request has been successfully submitted, a task_id will be returned in the HTTP Location header with a relative URL that defines where you can access the status of the newly submitted request. The task_id is the unique identifier used to access anything relating to the request.

Below are example JSON files that can be used to load the task request from a file:

Point Example JSON

Area Example JSON

POST
/task

Example submitting a task from a file

$ curl --request POST --data @sample-request.json --header "Content-Type: application/json" --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task"

Example submitting a task from JSON

$ curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task" --data "{\"task_type\": \"point\", \"task_name\": \"my-task\",\"params\": {\"dates\": [{\"startDate\": \"01-01-2010\", \"endDate\": \"01-31-2010\"}], \"layers\": [{\"product\": \"MOD11A1.006\", \"layer\": \"LST_Day_1km\"}], \"coordinates\": [{\"latitude\": 42, \"longitude\": -72}]}}"

Example submitting a task using a query string

$ curl --request POST --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task?task_type=point&task_name=my-task&startDate=01-01-2010&endDate=01-31-2010&layer=MOD11A1.006,LST_Day_1km&coordinate=42,-72"

Example response for a successful submit

HTTP/1.0 202
Content-Type: text/html; charset=utf-8
Location: /status/48f0e054-b536-4857-92f6-0c0d7e98c2de
Content-Length: 0
Date: Mon, 16 Oct 2017 12:22:44 GMT
{
    "task_id": "7b390348-0740-45a2-af36-00bf8304cb67", 
    "status": "pending"
}

Example response for a invalid request

HTTP/1.0 400 Bad Request
Content-Type: application/json
Content-Length: 49
Date: Fri, 27 Oct 2017 17:39:55 GMT
{
    "message": "'task_name' is a required property"
}

Retrieve task

This API call allows you to get the details about a specific task.

GET
/task/{task_id}

Example request

$ curl --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task/4d9f7647-0319-4ab7-9c85-c82f4f574664"

Example response

{
    "attempts": 2,
    "created": "2017-09-07T16:01:08.263000",
    "error": None,
    "params":
    {
        "dates": [
        {
            "endDate": "10-31-2009",
            "startDate": "01-01-2009"
        }],
        "layers": [
        {
            "layer": "LST_Night_1km",
            "product": "MOD11A1.006"
        },
        {
            "layer": "QC_Night",
            "product": "MOD11A1.006"
        }],
        "output":
        {
            "format":
            {
                "type": "netcdf4"
            },
            "projection": "native"
        },
        "geo": {
            "type": "FeatureCollection",
            "fileName": "User-Drawn-Polygon",
            "features": [
                {
                    "type": "Feature",
                    "properties": {},
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    -3.427734375,
                                    4.5
                                ],
                                [
                                    -3.427734375,
                                    11.70703125
                                ],
                                [
                                    1.248046875,
                                    11.70703125
                                ],
                                [
                                    1.248046875,
                                    4.5
                                ],
                                [
                                    -3.427734375,
                                    4.5
                                ]
                            ]
                        ]
                    }
                }
            ]
        }
    },
    "retry_at": None,
    "status": "done",
    "svc_version": "1.9.1",
    "task_id": "4d9f7647-0319-4ab7-9c85-c82f4f574664",
    "task_name": "my task",
    "task_type": "area",
    "updated": "2017-09-07T16:50:40.917000",
    "user_id": "user@example.com",
    "web_version": "1.9.1"
}

Delete task

This API call provides a way to delete a request.

DELETE
/task/{task_id}

Example request

$ curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/task/4d9f7647-0319-4ab7-9c85-c82f4f574664"

Example response for a successful deletion

HTTP 204 No Content

Status

The status API provides information on the status of all task requests that are currently being processed for your account. Therefore, each of the calls to this service require an authentication token as described above.

List statuses

This API call will retrieve the status information for all tasks that are currently being processed.

The status information may contain one or more of the properties below, depending on the status of the task request.

Property Description
task_id The unique identifier for the task.
user_id The user id for the task.
status_id The unique identifier for the status entry.
progress A number indicating the summary percent complete in addition to the details listing information about each step in the process.
status_type The type of the status entry (e.g. task ).
updated The timestamp for when the status was last modified.
GET
/status

Example request

$ curl --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/status"

Example response

[{
    "task_id": "7a71e792-139d-49c5-9b04-72fc95bca6bb",
    "user_id": "user@example.com",
    "progress": {
        "details": [
            {
                "step": 1,
                "desc": "Initializing",
                "pct_complete": 100
            },
            {
                "step": 2,
                "desc": "Downloading",
                "pct_complete": 100
            },
            {
                "step": 3,
                "desc": "Generating Files",
                "pct_complete": 100
            },
            {
                "step": 4,
                "desc": "Extracting Stats",
                "pct_complete": 0
            },
            {
                "step": 5,
                "desc": "Finalizing",
                "pct_complete": 0
            }
        ],
        "summary": 85
    },
    "status_id": "18fc2894-fbb3-4777-b751-26255cea9d70",
    "status_type": "task",
    "updated": "2017-10-11T12:14:57.975000"
},
{
    "task_id": "299ec6e2-652c-456b-8303-fb4ffaf66be0",
    "user_id": "user@example.com",
    "progress": {
        "details": [
            {
                "step": 1,
                "desc": "Initializing",
                "pct_complete": 100
            },
            {
                "step": 2,
                "desc": "Downloading",
                "pct_complete": 100
            },
            {
                "step": 3,
                "desc": "Generating Files",
                "pct_complete": 75
            },
            {
                "step": 4,
                "desc": "Extracting Stats",
                "pct_complete": 0
            },
            {
                "step": 5,
                "desc": "Finalizing",
                "pct_complete": 0
            }
        ],
        "summary": 65
    },
    "status_id": "d6c36957-7337-4ceb-ac38-36e58038a9fb",
    "status_type": "task",
    "updated": "2017-08-28T20:56:36.903000"
}]

Task status

This API call will retrieve the status for the specified task. This will include the overall state as well as a percent complete for any tasks that are currently processing.

If the task status is done, a 303 See Other status code is returned along with a Location header defining where the finished task can be found. Some tools and languages will automatically redirect to the URL defined in the Location header which would retrieve the details for the task.

GET
/status/{task_id}

Example request

$ curl --header "Authorization: Bearer your-token" "https://lpdaacsvc.cr.usgs.gov/appeears/api/status/4d9f7647-0319-4ab7-9c85-c82f4f574664"

Example response

{
    "updated": "2017-06-12T14:24:21.097000",
    "user_id": "user@example.com",
    "task_id": "da6deb42-4667-4acf-93e1-e78f8a7484ee",
    "progress": {
        "details": [
            {
                "desc": "Initializing",
                "pct_complete": 100,
                "step": 1
            },
            {
                "desc": "Downloading",
                "pct_complete": 75,
                "step": 2
            },
            {
                "desc": "Generating Files",
                "pct_complete": 0,
                "step": 3
            },
            {
                "desc": "Extracting Stats",
                "pct_complete": 0,
                "step": 4
            },
            {
                "desc": "Finalizing",
                "pct_complete": 0,
                "step": 5
            }
        ],
        "summary": 20
    },
    "status_type": "task",
    "status_id": "b3bdc587-95ed-4f65-900f-4564dbe258d0"
}

Example response for completed task

HTTP/1.0 303
Content-Type: application/json
Location: /task/4d9f7647-0319-4ab7-9c85-c82f4f574664
Content-Length: 198
Date: Wed, 18 Oct 2017 20:41:44 GMT
{
    "task_id": "4d9f7647-0319-4ab7-9c85-c82f4f574664",
    "status": "done",
    "user_id": "user@example.com",
    "updated": "2017-09-07T16:50:40.917000",
    "status_type": "task"
}

Bundle

The bundle API provides information about completed tasks and does not require authentication. For any tasks that have a status of done, a bundle will be generated containing all of the files that were generated as part of the task request. The bundle is associated with the task_id that was returned when the task was submitted.

List files

This API call lists all of the files contained in the bundle which are available for download.

The following properties describe the bundle.

Property Description
task_id The unique identifier for the task.
files The list of all of the files that make up the bundle.

file_id - The unique identifier for the file.

file_name - The name of the file.

file_size - The size of the file in bytes.

file_type - The content type of the file.

sha256 - The SHA-256 checksum of the file content.
created The timestamp for when the bundle was created.
updated The timestamp for when the bundle was last modified.
bundle_type The type of bundle, either area or point .
GET
/bundle/{task_id}

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/bundle/4d9f7647-0319-4ab7-9c85-c82f4f574664"

Example response

{
    "task_id": "4d9f7647-0319-4ab7-9c85-c82f4f574664",
    "files": [
        {
            "file_id": "9055b657-fcba-43aa-8386-a6ec3fa1c074",
            "file_name": "MCD12Q1.006_2010182_to_2010182\\MCD12Q1.006_LC_Type1_doy2010001_aid0001.tif",
            "file_size": 8979,
            "file_type": "tif",
            "sha256": "63e260b143c6e59ad96a2317279fd71b83771791be6a107911f831ced0c5af18"
        },
        {
            "file_id": "dbef7d9c-03e3-434f-b0f3-a8c20e53c94d",
            "file_name": "fiji-geo-request.json",
            "file_size": 45307,
            "file_type": "json",
            "sha256": "f2e90cc5c87c2017c251c7f3ce8d3e831045590f6eef253006732c51d85abe14"
        },
        {
            "file_id": "d27600a5-3098-47cb-b1fa-8b97d2f8e572",
            "file_name": "fiji-geo-MCD12Q1-006-metadata.xml",
            "file_size": 20736,
            "file_type": "xml",
            "sha256": "d8d66186f0e30adb9b6ef1eab076b8d2dd8b25e9f3f9595276b79b1d4b3e8d29"
        },
        {
            "file_id": "473fac22-4770-4759-8c0f-5f68b8d57bbf",
            "file_name": "README.txt",
            "file_size": 10867,
            "file_type": "txt",
            "sha256": "9ea1313917e59f9a33a571f947175af5ed409ffb287dd4046f79989a5ade8559"
        }
    ],
    "created": "2017-08-30T20:00:23.667000",
    "updated": "2017-08-30T20:00:31.623000",
    "bundle_type": "area"
}

Download file

Each file in a bundle can be downloaded. Just as the task has a task_id to identify it, each file in the bundle will also have a unique file_id which should be used for any operation on that specific file.

The Content-Type and Content-Disposition headers will be returned when accessing each file to give more details about the format of the file and the filename to be used when saving the file.

GET
/bundle/{task_id}/{file_id}

Example download file locally using remote name

$ curl -O --remote-header-name --location "https://lpdaacsvc.cr.usgs.gov/appeears/api/bundle/4d9f7647-0319-4ab7-9c85-c82f4f574664/9055b657-fcba-43aa-8386-a6ec3fa1c074"

Example response

The response in this case will be the bytes contained in the file downloaded to a filename specified by the Content-Disposition header.

Product

The product API provides details about all of the products and layers available in AρρEEARS and does not require authentication.

List products

This API call will list all of the products and their details and supports pagination.

GET
/product

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/product"

Example response

{
    "Product": "VNP09A1",
    "Platform": "S-NPP NASA VIIRS",
    "Description": "Surface Reflectance 8-Day L3 Global 1km SIN Grid V001",
    "RasterType": "Tile",
    "Resolution": "1000m",
    "TemporalGranularity": "8 day",
    "Version": "001",
    "Available": true,
    "DocLink": "https://doi.org/10.5067/viirs/vnp09a1.001",
    "Source": "LP DAAC",
    "TemporalExtentStart": "January 19, 2012",
    "TemporalExtentEnd": "Present",
    "ProductAndVersion": "VNP09A1.001",
    "DOI": "10.5067/viirs/vnp09a1.001"
}

List layers

This API call will list all of the layers available for a given product. Each product is referenced by its ProductAndVersion property which is also referred to as the product_id.

GET
/product/{product_id}

Example request

# product_id = ProductAndVersion
$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/product/SRTMGL1N.003"

Example response

{
    "Band1": {
        "AddOffset": "",
        "Available": true,
        "DataType": "int16",
        "Description": "Quality Assurance",
        "Dimensions": [
            "time",
            "lat",
            "lon"
        ],
        "FillValue": 0,
        "Layer": "Band1",
        "OrigDataType": "int16",
        "OrigValidMax": 255,
        "OrigValidMin": 0,
        "QualityLayers": "",
        "QualityProductAndVersion": "",
        "ScaleFactor": "",
        "Units": "None",
        "ValidMax": 255,
        "ValidMin": 0,
        "XSize": 3601,
        "YSize": 3601
    }
}

Spatial

The spatial API provides some helper services used to support submitting task requests.

List projections

This API call will retrieve the list of supported projections.

GET
/spatial/proj

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/spatial/proj"

Example response

[
    {
        "Name": "native",
        "Description": "Native Projection",
        "Proj4": "",
        "Datum": "",
        "EPSG": "",
        "Units": "",
        "GridMapping": ""
    },
    {
        "Name": "geographic",
        "Description": "Geographic",
        "Proj4": "+proj=longlat +datum=WGS84 +no_defs",
        "Datum": "wgs84",
        "EPSG": 4326.0,
        "Units": "degrees",
        "GridMapping": "latitude_longitude"
    },
    {
        "Name": "sinu_modis",
        "Description": "MODIS Sinusoidal",
        "Proj4": "+proj=sinu +lon_0=0 +x_0=0 +y_0=0 +a=6371007.181 +b=6371007.181 +units=m +no_defs",
        "Datum": "",
        "EPSG": "",
        "Units": "meters",
        "GridMapping": "sinusoidal"
    },
    {
        "Name": "albers_weld_alaska",
        "Description": "WELD Albers Equal Area Alaska",
        "Proj4": "+proj=aea +lat_1=55 +lat_2=65 +lat_0=50 +lon_0=-154 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs",
        "Datum": "wgs84",
        "EPSG": "",
        "Units": "meters",
        "GridMapping": "albers_conical_equal_area"
    },
    {
        "Name": "albers_weld_conus",
        "Description": "WELD Albers Equal Area CONUS",
        "Proj4": "+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs",
        "Datum": "wgs84",
        "EPSG": "",
        "Units": "meters",
        "GridMapping": "albers_conical_equal_area"
    },
    {
        "Name": "easegrid_2_global",
        "Description": "EASE-Grid 2.0 Global",
        "Proj4": "+proj=cea +lon_0=0 +lat_ts=30 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs",
        "Datum": "wgs84",
        "EPSG": 6933.0,
        "Units": "meters",
        "GridMapping": "lambert_azimuthal_equal_area"
    }
]

Quality

The quality API provides quality details about all of the products available in AρρEEARS.

List quality products

This API call will list all of the product layers and where the associated quality product and layer information is located. This API call also supports pagination.

GET
/quality

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/quality"

Example response

[
    {
        "ProductAndVersion": "MCD12Q1.006",
        "Layer": "LC_Prop1",
        "QualityProductAndVersion": "MCD12Q1.006",
        "QualityLayers": [
            "QC"
        ]
    },
    {
        "ProductAndVersion": "MCD12Q1.006",
        "Layer": "LC_Prop1_Assessment",
        "QualityProductAndVersion": "MCD12Q1.006",
        "QualityLayers": [
            "QC"
        ]
    },
    ...
]

List quality layers

This API call will list all of the quality layer information for a product.

GET
/quality/{product_id}

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/quality/MCD12Q1.006"

Example response

[
    {
        "ProductAndVersion": "MCD12Q1.006",
        "Layer": "LC_Prop1",
        "QualityProductAndVersion": "MCD12Q1.006",
        "QualityLayers": [
            "QC"
        ]
    },
    {
        "ProductAndVersion": "MCD12Q1.006",
        "Layer": "LC_Prop1_Assessment",
        "QualityProductAndVersion": "MCD12Q1.006",
        "QualityLayers": [
            "QC"
        ]
    },
 ...
]

List quality values

This API call will list all of the values for a given quality layer.

GET
/quality/{product_id}/{quality_layer}

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/quality/MCD12Q1.006/QC"

Example response

[
    {
        "ProductAndVersion": "MCD12Q1.006",
        "QualityLayer": "QC",
        "Name": "Name",
        "Value": 0,
        "Description": "Classified land (Has a classification label and is land according to the water mask.)",
        "Acceptable": null
    },
    {
        "ProductAndVersion": "MCD12Q1.006",
        "QualityLayer": "QC",
        "Name": "Name",
        "Value": 1,
        "Description": "Unclassified land (Not classified because of missing data but land according to the water mask, labeled as barren.)",
        "Acceptable": null
    },
 ...
]

Decode quality values

This API call will decode the bits for a given quality value.

GET
/quality/{product_id}/{quality_layer}/{quality_value}

Example request

$ curl "https://lpdaacsvc.cr.usgs.gov/appeears/api/quality/MCD12Q1.006/QC/0"

Example response

{
    "Binary Representation": "0b00000000",
    "Name": {
        "bits": "0b00000000",
        "description": "Classified land (Has a classification label and is land according to the water mask.)"
    }
}
Show examples in:
AρρEEARS API Documentation