Provides download operations of geospatial datasets to client machines. This involves packaging all supplemental files that make up the dataset into a ZIP based on the download.
Note: Before attempting to make request to our Foundation API, please ensure you are properly authenticated. For instructions on the authentication process, please see the Foundation - Authentication API article.
A successful request to this endpoint will return a JSON array of objects. Each object will contain information about a specific download that is current processing.
GET /api/v1/downloads
HTTP Status Code | Description | Payload |
200 | Successfully retrieved all running downloads |
[ { "id": "", "displayableStatus": "COMPLETE", "progress": "100", "state": "COMPLETE", "startTime": "2016-9-14T15:28:17Z", "endTime": "" }, ... ] |
HTTP Status Code | Description |
---|---|
401 | Error, not authorized to access the catalog. |
403 | Error, forbidden to access the item. |
404 | Error, item not found. |
500 | Unexpected error while processing the request. |
This request will initiate the packaging of every catalog item that corresponds to an id included. When status is complete, the location of the packaged ZIP file will be in the response location header.
Downloading datasets using the Download API is a three-step process. This process begins with the user initiating a download request. The second, optional step, is to request the status of the download. Finally, the third step is to download the packaged ZIP file. The HTTP request method must be a POST, and the following endpoint is used will make the request:
POST /api/v1/downloads
The user must include a JSON payload to be sent with the request. This payload will contain a JSON string array with the catalog id of each catalog item the user wants to download. With this structure the user can create an array with as many ids as necessary, meaning a single download job can handle downloading multiple catalog items. The request payload should follow the structure below:
[ "id1", "id2", ... ]
HTTP Status Code | Description | Payload |
201 | This indicates that your download request has been accepted, and that your download job has started. |
{ "id": "download-1553c2bv-42dp-4841-82e3-2e2163369165", "displayableStatus": "WAITING", "progress": "15", "state": "WAITING", "startTime": "2016-10-19T18:17:50Z", "endTime": "", "datasetIds": [ "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de5379742f", "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de60847447" ], "downloadURI": null } |
HTTP Status Code | Description |
---|---|
401 | Error, not authorized to access the catalog |
403 | Error, forbidden to access the item |
404 | Error, item not found |
500 | Unexpected Error while processing the request |
This endpoint will return all information about a specific download job.
While a download job is running, a user can check the status of this job. This is done by using the downloadId (returned in the HTTP response of the initial request) to make another request to the following endpoint:
GET /api/v1/downloads/{downloadId}
Title | Required | Type | Values | Description |
downloadId | true | QueryString Parameter | Any valid download job id | Id of the download job. |
Note: When a download is started in M.App Chest, M.App Chest uses this endpoint to update the user about the status of the running download job. When the job is complete, M.App Chest updates the user of the completion and enables the option to download the resulting ZIP file.
HTTP Status Code | Description | Payload |
200 | Successfully retrieved the status of the requested download job. |
{ "id": "download-1553c2bv-42dp-4841-82e3-2e2163369165", "displayableStatus": "COMPLETE", "progress": "100", "state": "COMPLETE", "startTime": "2016-10-19T18:17:50Z", "endTime": "2016-10-19T18:17:55Z", "datasetIds": [ "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de5379742f", "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de60847447" ], "downloadURI": null } |
HTTP Status Code | Description |
---|---|
401 | Error, not authorized to access the catalog |
403 | Error, forbidden to access the item |
404 | Error, item not found |
500 | Unexpected error while processing the request |
When the creation of the ZIP file is complete, the user should initiate this request using the original download id.
When the download job is complete, users must make a final request to the following endpoint to actually download the ZIP file:
GET /api/v1/downloads/{downloadId}/zip
Title | Required | Type | Values | Description |
downloadId | true | QueryString Parameter | Any valid download job id | Id of the job responsible for packaging catalog items |
This endpoint will contain the resulting ZIP file from the download job. When users make a request from the endpoint above the browser should handle the rest with its default download workflow.
HTTP Status Code | Description | Payload |
200 | Successful request made to this endpoint will also provide the user with additional download information. The JSON payload will match the sample payload. |
{ "description": "string", "filename": "string", "inputStream": {}, "open": true, "outputStream": {}, "path": "string", "readable": true, "writable": true } |
HTTP Status Code | Description |
---|---|
401 | Error, not authorized to access the catalog |
403 | Error, forbidden to access the item |
404 | Error, item not found |
500 | Unexpected error while processing the request |
Uses the given download id to stop all effort on completing the corresponding job.
PUT /api/v1/downloads/{downloadId}/cancel
Title | Required | Type | Values | Description |
downloadId | true | QueryString Parameter | Any valid download job id | Id of the download job responsible for packaging catalog items |
HTTP Status Code | Description | Payload |
202 | Successfully canceled this download job | There is no payload for this response. |
HTTP Status Code | Description | Payload |
---|---|---|
401 | Error, not authorized to access the catalog | There is no payload for this response. |
403 | Error, forbidden to access the item | |
500 | Unexpected error while processing the request |
Uses the given download id to delete an existing download.
DELETE /api/v1/downloads/{downloadId}
Title | Required | Type | Values | Description |
downloadId | true | QueryString Parameter | Any valid download job id | Id of the download job responsible for packaging catalog items |
HTTP Status Code | Description | Payload |
204 | Successfully deleted the download content from the download location. | There is no payload for this response. |
HTTP Status Code | Description | Payload |
---|---|---|
400 | Error with details in the response body | There is no payload for this response. |
401 | Error, not authorized to access the catalog | |
403 | Error, forbidden to access the item | |
404 | Error, item not found | |
500 | Unexpected error while processing the request |