{"_id":"591cf4f56a9ac10f00f3d7e9","githubsync":"","version":{"_id":"5661fdca55e4450d00e62c73","project":"5511df3be2990b0d00fb071d","__v":2,"createdAt":"2015-12-04T20:55:38.639Z","releaseDate":"2015-12-04T20:55:38.639Z","categories":["5661fdcb55e4450d00e62c74","5661fdcb55e4450d00e62c75","5661fdcb55e4450d00e62c76","5661fdcb55e4450d00e62c77","5661fdcb55e4450d00e62c78","5661fdcb55e4450d00e62c79","567c42b13241c20d00b7312e"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"category":{"_id":"5661fdcb55e4450d00e62c74","__v":1,"pages":["5661fdcb55e4450d00e62c7a","5661fdcb55e4450d00e62c7b","5661fdcb55e4450d00e62c7c","5661fdcb55e4450d00e62c7d","5661fdcb55e4450d00e62c7e","5661fdcb55e4450d00e62c7f"],"project":"5511df3be2990b0d00fb071d","version":"5661fdca55e4450d00e62c73","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-24T22:03:40.337Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"user":"5535326bf07d6b0d0077be75","__v":0,"project":"5511df3be2990b0d00fb071d","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-18T01:12:21.448Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"examples":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"The workflow of getting data from Astro Digital platform consists of the following steps:\n\n1. Get an API Token\n2. Prepare an Area Of Interest (AOI) to provide AD API the desired location. System backend works with AOIs in GeoJSON format.\n3. Specify query parameters of a [Task](doc:tasks-1). Basically all the manipulations with data happen by working with Tasks and [Results](doc:results) for each Task.\n4. Post Task for the data to AD Platform\n5. Call the API to get the Results.\n\n### 1. Get an API Token\n\n1.  Email to help:::at:::astrodigital.com and tell a couple of words about your project\n2. We'll respond with an API key\n\n### 2. Prepare Area Of Interest (AOI)\n\nAD API accepts AOIs in [GeoJSON](http://geojson.org/) format as Features or FeatureCollection containing Polygons. \n\nWe recommend to specify a farm as a FeatureCollection of Features (fields) with 1 Polygon each. Still we accept individual fields as AOIs. Here's [Geojson.io](http://geojson.io/#map=2/20.0/0.0) tool from Mapbox to perform operations over GeoJSON files\n\n\n```\n{\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"properties\": {},\n      \"geometry\": {\n        \"type\": \"Polygon\",\n        \"coordinates\": [[[ -96.922405577, 43.728754527 ], [ -96.922405577, 43.744199908 ], [ -96.907458434, 43.744199908 ], [ -96.907458434, 43.728754527 ], [ -96.922405577, 43.728754527 ]]]\n      }\n    }\n  ]\n}\n```\n\nMore about how to work with AOIs is covered in this [article](doc:areas-of-interest-best-practices) \n\n### Specifying Parameters of a Task\n\nBesides the AOI to create a Task some more parameters required. Here's an example of what parameters I specified for:\n\n##### Imagery Task\n\n* ```\"name\": \"Field 1 imagery\"``` - name of the Task corresponding the entire farm\n* ```\"date_from\": \"2013-05-30\"``` - the earliest date for imagery is 2013-05-30\n* ```\"date_to\": \"2117-01-01\"``` - you can specify any data in past, present or future. It should be greater than ```date_from```\n* ```\"cloud_to\":20``` - maximum % of clouds. Larger cloud coverage causes incorrect NDVI estimates\n* ```\"recurring\":true``` - this make the Task search for newly available data.\n* ```\"products\": [{\"product\": \"ndvi_value\", \"actions\": [\"raw\",\"processed\"]},{\"product\": \"true_color\", \"actions\": [\"raw\",\"processed\"]}]``` - for each data product you specify what actions should be performed with this product. ```raw``` refers to \"clip and ship product\" where all the bands used for a specified imagery product are provided like \"Red\", \"Green\" and \"Blue\" bands for a true_color image. \"processed\" refers to a band combination like ```true_color``` or ```urban_false``` or a calculated index with a colormap applied like ```ndvi_image```\n*```\"aoi_coverage_percentage\":90```- this parameter shows the minimal % of overlapping between a satellite scene and the AOI. High value of this parameter helps to make sure that the result fully covers the AOI.\n\nYou can see the full list of parameters of tasks [here](https://docs.astrodigital.com/docs/tasks-1)\n\n### Posting a task\n\nHere's an example of how to POST a task for NDVI and TrueColor maps using ```curl``` utility:\n\n```\ncurl 'https://api.astrodigital.com/v2.0/tasks' --data '\n{\"name\":\"Field 1 Imagery\", \n\"products\": [\n    {\"product\": \"ndvi_image\", \"actions\": [\"mapbox\",\"raw\"]},\n    {\"product\": \"true_color\", \"actions\": [\"mapbox\",\"raw\"]}], \n\"recurring\":true,\n\"aoi_coverage_percentage\":90,\n\"query\": \n    {\"date_from\": \"2013-05-13\",\n    \"date_to\": \"2117-01-01\",\n\"cloud_from\":0,\n\"cloud_to\":20,\n  \n    \"aoi\":{\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"properties\": {},\n      \"geometry\": {\n        \"type\": \"Polygon\",\n        \"coordinates\": [[[ -96.922405577, 43.728754527 ], [ -96.922405577, 43.744199908 ], [ -96.907458434, 43.744199908 ], [ -96.907458434, 43.728754527 ], [ -96.922405577, 43.728754527 ]]]\n      }\n    }\n  ]\n}}}\n    ' -H 'Content-Type: application/json' -H 'Authorization: Token ***'\n```\n\n## Part 2 - Getting the results from the API\n\n### Get task id\n\nIn Part 1 we've created a task. Each task has an ID. It can be retrieved by calling all the tasks and searching one by name. Example:\n\n```\ncurl https://api.astrodigital.com/v2.0/tasks -H 'Authorization: Token ***'\n```\n\n### Get all results for a task\n\nYou can call all the results for a task with this query:\n\n```\ncurl https://api.astrodigital.com/v2.0/results?task_id=175 -H 'Authorization: Token ***'\n```\n\n### Get all updates for tasks\n\nFor recurring tasks Astro Digital platform checks for updates of imagery sources on daily basis. When a new image for a task is avaliable it will be processed automatically and the task will updated. To get all updates for the tasks that occurred on August 2, 2017 the following query can be used:\n\n```\ncurl https://api.astrodigital.com/v2.0/results?updated_from=2017-08-02&updated_from=2017-08-03 -H 'Authorization: Token ***'\n```\n\n## Part 3 - Getting information from the API response\n\nHere's an example of a typical API response for results. \n\n```\n{\n    \"count\": 1,\n    \"next\": null,\n    \"previous\": null,\n    \"results\": [\n        {\n            \"id\": 1501675073484209200,\n            \"created_at\": \"2017-08-02T11:57:53Z\",\n            \"identifier\": \"S2A_tile_20170728_37TDM_0\",\n            \"status_time\": \"2017-08-02T23:09:39Z\",\n            \"secondary_status\": null,\n            \"is_failed\": false,\n            \"fail_reason\": \"\",\n            \"fail_time\": null,\n            \"is_ready\": true,\n            \"is_seen\": false,\n            \"task\": 150814,\n            \"value\": {\n                \"meta\": {\n                    \"scene_id\": \"S2A_tile_20170728_37TDM_0\",\n                    \"cloud_cover\": 0.04,\n                    \"satellite_name\": \"Sentinel-2A\",\n                    \"acquisitionDate\": \"2017-07-28\"\n                },\n                \"raw_image_url\": [\n                    \"https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B04.tif\",\n                    \"https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B03.tif\",\n                    \"https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B02.tif\"\n                ],\n                \"processed_tif_url\": \"https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5.tif\"\n            },\n            \"product\": \"true_color\",\n            \"status\": \"COMPLETED\"\n        }\n]\n}\n```\n\nEach result contains actual links for downloading raw and processed GeoTIFFs for each results. They will be active for 30 days after the processing.\n\nAlso each result contains information about the sensor, acquisition date, cloud coverage, status of processing .These fields can be searchable.","excerpt":"","slug":"getting-started-for-developers-1","type":"basic","title":"Getting started for analytic workflows"}

Getting started for analytic workflows


The workflow of getting data from Astro Digital platform consists of the following steps: 1. Get an API Token 2. Prepare an Area Of Interest (AOI) to provide AD API the desired location. System backend works with AOIs in GeoJSON format. 3. Specify query parameters of a [Task](doc:tasks-1). Basically all the manipulations with data happen by working with Tasks and [Results](doc:results) for each Task. 4. Post Task for the data to AD Platform 5. Call the API to get the Results. ### 1. Get an API Token 1. Email to [email protected] and tell a couple of words about your project 2. We'll respond with an API key ### 2. Prepare Area Of Interest (AOI) AD API accepts AOIs in [GeoJSON](http://geojson.org/) format as Features or FeatureCollection containing Polygons. We recommend to specify a farm as a FeatureCollection of Features (fields) with 1 Polygon each. Still we accept individual fields as AOIs. Here's [Geojson.io](http://geojson.io/#map=2/20.0/0.0) tool from Mapbox to perform operations over GeoJSON files ``` { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {}, "geometry": { "type": "Polygon", "coordinates": [[[ -96.922405577, 43.728754527 ], [ -96.922405577, 43.744199908 ], [ -96.907458434, 43.744199908 ], [ -96.907458434, 43.728754527 ], [ -96.922405577, 43.728754527 ]]] } } ] } ``` More about how to work with AOIs is covered in this [article](doc:areas-of-interest-best-practices) ### Specifying Parameters of a Task Besides the AOI to create a Task some more parameters required. Here's an example of what parameters I specified for: ##### Imagery Task * ```"name": "Field 1 imagery"``` - name of the Task corresponding the entire farm * ```"date_from": "2013-05-30"``` - the earliest date for imagery is 2013-05-30 * ```"date_to": "2117-01-01"``` - you can specify any data in past, present or future. It should be greater than ```date_from``` * ```"cloud_to":20``` - maximum % of clouds. Larger cloud coverage causes incorrect NDVI estimates * ```"recurring":true``` - this make the Task search for newly available data. * ```"products": [{"product": "ndvi_value", "actions": ["raw","processed"]},{"product": "true_color", "actions": ["raw","processed"]}]``` - for each data product you specify what actions should be performed with this product. ```raw``` refers to "clip and ship product" where all the bands used for a specified imagery product are provided like "Red", "Green" and "Blue" bands for a true_color image. "processed" refers to a band combination like ```true_color``` or ```urban_false``` or a calculated index with a colormap applied like ```ndvi_image``` *```"aoi_coverage_percentage":90```- this parameter shows the minimal % of overlapping between a satellite scene and the AOI. High value of this parameter helps to make sure that the result fully covers the AOI. You can see the full list of parameters of tasks [here](https://docs.astrodigital.com/docs/tasks-1) ### Posting a task Here's an example of how to POST a task for NDVI and TrueColor maps using ```curl``` utility: ``` curl 'https://api.astrodigital.com/v2.0/tasks' --data ' {"name":"Field 1 Imagery", "products": [ {"product": "ndvi_image", "actions": ["mapbox","raw"]}, {"product": "true_color", "actions": ["mapbox","raw"]}], "recurring":true, "aoi_coverage_percentage":90, "query": {"date_from": "2013-05-13", "date_to": "2117-01-01", "cloud_from":0, "cloud_to":20, "aoi":{ "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {}, "geometry": { "type": "Polygon", "coordinates": [[[ -96.922405577, 43.728754527 ], [ -96.922405577, 43.744199908 ], [ -96.907458434, 43.744199908 ], [ -96.907458434, 43.728754527 ], [ -96.922405577, 43.728754527 ]]] } } ] }}} ' -H 'Content-Type: application/json' -H 'Authorization: Token ***' ``` ## Part 2 - Getting the results from the API ### Get task id In Part 1 we've created a task. Each task has an ID. It can be retrieved by calling all the tasks and searching one by name. Example: ``` curl https://api.astrodigital.com/v2.0/tasks -H 'Authorization: Token ***' ``` ### Get all results for a task You can call all the results for a task with this query: ``` curl https://api.astrodigital.com/v2.0/results?task_id=175 -H 'Authorization: Token ***' ``` ### Get all updates for tasks For recurring tasks Astro Digital platform checks for updates of imagery sources on daily basis. When a new image for a task is avaliable it will be processed automatically and the task will updated. To get all updates for the tasks that occurred on August 2, 2017 the following query can be used: ``` curl https://api.astrodigital.com/v2.0/results?updated_from=2017-08-02&updated_from=2017-08-03 -H 'Authorization: Token ***' ``` ## Part 3 - Getting information from the API response Here's an example of a typical API response for results. ``` { "count": 1, "next": null, "previous": null, "results": [ { "id": 1501675073484209200, "created_at": "2017-08-02T11:57:53Z", "identifier": "S2A_tile_20170728_37TDM_0", "status_time": "2017-08-02T23:09:39Z", "secondary_status": null, "is_failed": false, "fail_reason": "", "fail_time": null, "is_ready": true, "is_seen": false, "task": 150814, "value": { "meta": { "scene_id": "S2A_tile_20170728_37TDM_0", "cloud_cover": 0.04, "satellite_name": "Sentinel-2A", "acquisitionDate": "2017-07-28" }, "raw_image_url": [ "https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B04.tif", "https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B03.tif", "https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5_clipped_B02.tif" ], "processed_tif_url": "https://s3-us-west-2.amazonaws.com/ad-api-images/96f1dc49e02346148a599f5e732c31f5.tif" }, "product": "true_color", "status": "COMPLETED" } ] } ``` Each result contains actual links for downloading raw and processed GeoTIFFs for each results. They will be active for 30 days after the processing. Also each result contains information about the sensor, acquisition date, cloud coverage, status of processing .These fields can be searchable.