{"_id":"59838fedf06c6a003441d433","project":"5511df3be2990b0d00fb071d","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,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-03T21:04:45.347Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"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 GeoJson format of AOIs.\n3. Specify query parameters of a Task. Basically all the manipulations with data happen by working with Tasks and Results for each Task.\n4. Post Task for the data to AD Platform\n5. Call the API to get the Results.\n\n\n## Part 1 - Get Token, Preparing AOIs, Specifying parameters, Posting tasks\n\n\n### Get an API Token\n\n1. Signup using a link from the email\n3. Go to fetch.astrodigital.com and log in\n4. See the API  token on the righthand panel \n\n### Prepare Areas Of Interest (AOIs)\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 an Example:\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\nFor a Vegetation Trends product (weekly updated average NDVI for a field) we have a limitation for a minimal area of **30 ha** per Polygon. \n\nFor NDVI maps and True Color maps you can specify polygons of any area but keep in mind that the size of a pixel is **10 meters** and we'll process this AOI as a square with a side of 10 meters.\n\n\n### Specifying Parameters of a Task\n\nBesides the AOI to create a Task some more parameters should be specified. 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\": [\"mapbox\",\"raw\",\"processed\"]},{\"product\": \"true_color\", \"actions\": [\"mapbox\",\"processed\"]}]``` - for each data product you specify what actions should be performed with this product. ```mapbox``` means posting the images into Mapbox cloud storage.\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\n##### Vegetation Trends Task\n\n \n* ```\"name\": \"Field 1 Vegetation Trends\"``` - name of the Task corresponding the entire farm\n* ```\"date_from\": \"2013-01-01\"``` - the earliest date for imagery is 2012-01-01 while industry standard is 3 years archive.\n* ```\"date_to\": \"2117-01-01\"``` - you can specify any data in past, present or future. It should be greater than ```date_from```\n* ```\"recurring\":true``` - this make the Task search for newly available data.\n* ```\"products\":  \"products\": [{\"product\": \"ndvi_value\", \"actions\": [\"notify\"]}]``` - for each data product you specify what actions should be performed with this product. ```notify``` means that you'll be emailed when the data is ready.\n\nYou can see the full list of parameters of imagery [here](https://docs.astrodigital.com/docs/search) and all 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\",\"processed\"]}], \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\nHere's an example of how to POST a task for Vegetation Trends using ```curl``` utility:\n\n```\ncurl 'https://api.astrodigital.com/v2.0/tasks' --data '\n{\"name\":\"Field 1 Values\", \n\"products\": [\n    {\"product\": \"ndvi_value\", \"actions\": [\"notify\"]}], \n\"recurring\":true,\n\"query\": \n    {\"date_from\": \"2013-01-01\",\n    \"date_to\": \"2117-01-01\",\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, visualization of the Vegetation Trends\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### Visualization of the Vegetation Trends\n\n#### Product Description\n\nVegetation Trends is an analytical product showing average vegetation for a field for the last week. In API it is represented as a set of data points in the following format:\n\n```\n\"ndvi_values\": [\n    {\n      \"date\": \"2013-01-01\",\n      \"value\": 0.145\n    }\n```\n\n\nNDVI is ranged in [-1;1] where values in [-1;0] mean no-vegetated areas and everything above 1 shows vegetation where the higher - the more active vegetation is on the field. \n\n#### Limitations\nAlso it's important to consider clouds. In case you see a NDVI value around zero in a period of expected high vegetation it usually means that there was a week of cloudy images and all the results should be corrected. For South Africa it is a very unlikely situation.\n\n#### Tools\nNDVI values can be plotted on chart having dates on 1 axis and NDVI values on another. I like using [Highcharts](http://www.highcharts.com/) JS library to have professionally looking charts though it is commercial. [Chart.js](www.chartjs.org/) is Open Sources and gives good results.\n\n#### Information to visualize\nBesides visualizing a chart for a ongoing year you can analyze previous years and plot average, minimal, maximal or confidence interval for values. Reliable results can be generated by analyzing from 3 to 5 years of observation.\n\n#### Example 1:\n\nYou can visualize how much NDVI changes from the previous time in %.\nGreen is NDVI for 2015, Grey - average NDVI for 3 years, Red - NDVI change in %, Blue - zeros\n\n![image](https://cloud.githubusercontent.com/assets/4834199/13893421/622b8e76-ed1b-11e5-8f56-b2a985da7625.png)\n\n#### Example 2: \n\nFor commodity crops like corn, wheat and potatoes because they have a short vegetation cycle and properly described so an agronomist knows how each stage correlates with the next stages and what should be done/changed to improve the final results.\n\nThere're 2 ways of smoothing this curve:\n1. Add more years (5-7 years)\n2. Smooth it mathematically around local maximum. For this case a number of vegetation cycles per year should be an additional parameter:\n\n* Green - NDVI for 2015\n* Grey - Mathematical average calculated with the [JS library](http://mourner.github.io/simplify-js/)\n* Red - smoothed curve for 1 season\n\n![image](https://cloud.githubusercontent.com/assets/4834199/13892326/d060931c-ed13-11e5-9533-bf3820616a66.png)\n\n## Part 3 -  Working with Maps: mapping platform, placing AD tiles, legend, over-zooming and z-index.\n\n### mapping platform\n\nBasically mapping platform is a map with ability to place satellite images on the top of it.\n\nMy favorite Mapping platform (a JavaScript library and a cloud storage) is Mapbox (https://www.mapbox.com/) it has the most powerful functionality in storing and visualizing the data. Also you can look at open sources Leaflet.js (http://leafletjs.com/) and popular Google Maps API (https://developers.google.com/maps/?hl=en)\n\n### placing AD tiles\n\nGet processed Results:\n\n```curl https://api.astrodigital.com/v2.0/results?task_id=175 -H 'Authorization: Token MY-TOKEN'```\n\nIn the response you will get map_id. You can use it to place on the map.\n\nBeyond just embedding the processed image on your site, you can use JavaScript to build an interactive experience around the imagery. Below is an example of using mapbox.js to interact with the processed imagery by embedding it within a webpage.\n\nBefore you can utilize the mapbox.js tools, you will need a developer account and token which you can create here.\n\n```\n<html>\n  <head>\n      <title>Embed Example</title>\n      <script src='https://api.tiles.mapbox.com/mapbox.js/v2.1.9/mapbox.js'></script>\n      <link href='https://api.tiles.mapbox.com/mapbox.js/v2.1.9/mapbox.css' rel='stylesheet' />\n      <style>\n          body { margin:0; padding:0; }\n          #map { position:absolute; top:0; bottom:0; width:100%; }\n      </style>    \n  </head>\n\n  <body>\n      <div id='map'></div>\n      <script>\n          L.mapbox.accessToken = 'MAPBOX_TOKEN'; // Mapbox public key - please email me if you need help with it\n          var map = L.mapbox.map('map');\n          L.mapbox.tileLayer('astrodigital.LC80010802014240LGN00_bands_432', { format: 'png' }).addTo(map); // add satellite image to the map\n          map.setView([-28.6713,-71.1475], 8); // specify initial view\n      </script>\n  </body>\n</html>\n```\n\nThis simple example will give you a webpage with your processed image embedded on it. See Mapbox documentation for more information on how to add multiple images and data layers and enable greater interactivity.\n\nAfter you develop the first map you'll need some additional functionality. Based on experience of existing customers here's a list of articles you may find helpful:\n\n* map legend - https://bl.ocks.org/tristen/34589b26dafc70d30834 - to customize map legend with an image\n* over-zooming - https://www.mapbox.com/mapbox.js/example/v1.0.0/overzoom/ - to zoom very deep to the image\n* z-index - https://www.mapbox.com/mapbox-gl-js/example/toggle-layers/ - to switch between images from different dates quickly.","excerpt":"","slug":"getting-started-for-agricultural-applications","type":"basic","title":"Getting started for web applications"}

Getting started for web applications


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 GeoJson format of AOIs. 3. Specify query parameters of a Task. Basically all the manipulations with data happen by working with Tasks and Results for each Task. 4. Post Task for the data to AD Platform 5. Call the API to get the Results. ## Part 1 - Get Token, Preparing AOIs, Specifying parameters, Posting tasks ### Get an API Token 1. Signup using a link from the email 3. Go to fetch.astrodigital.com and log in 4. See the API token on the righthand panel ### Prepare Areas Of Interest (AOIs) 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 an Example: ``` { "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) For a Vegetation Trends product (weekly updated average NDVI for a field) we have a limitation for a minimal area of **30 ha** per Polygon. For NDVI maps and True Color maps you can specify polygons of any area but keep in mind that the size of a pixel is **10 meters** and we'll process this AOI as a square with a side of 10 meters. ### Specifying Parameters of a Task Besides the AOI to create a Task some more parameters should be specified. 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": ["mapbox","raw","processed"]},{"product": "true_color", "actions": ["mapbox","processed"]}]``` - for each data product you specify what actions should be performed with this product. ```mapbox``` means posting the images into Mapbox cloud storage. *```"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. ##### Vegetation Trends Task * ```"name": "Field 1 Vegetation Trends"``` - name of the Task corresponding the entire farm * ```"date_from": "2013-01-01"``` - the earliest date for imagery is 2012-01-01 while industry standard is 3 years archive. * ```"date_to": "2117-01-01"``` - you can specify any data in past, present or future. It should be greater than ```date_from``` * ```"recurring":true``` - this make the Task search for newly available data. * ```"products": "products": [{"product": "ndvi_value", "actions": ["notify"]}]``` - for each data product you specify what actions should be performed with this product. ```notify``` means that you'll be emailed when the data is ready. You can see the full list of parameters of imagery [here](https://docs.astrodigital.com/docs/search) and all 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","processed"]}], "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 ***' ``` Here's an example of how to POST a task for Vegetation Trends using ```curl``` utility: ``` curl 'https://api.astrodigital.com/v2.0/tasks' --data ' {"name":"Field 1 Values", "products": [ {"product": "ndvi_value", "actions": ["notify"]}], "recurring":true, "query": {"date_from": "2013-01-01", "date_to": "2117-01-01", "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, visualization of the Vegetation Trends ### 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 ***' ``` ### Visualization of the Vegetation Trends #### Product Description Vegetation Trends is an analytical product showing average vegetation for a field for the last week. In API it is represented as a set of data points in the following format: ``` "ndvi_values": [ { "date": "2013-01-01", "value": 0.145 } ``` NDVI is ranged in [-1;1] where values in [-1;0] mean no-vegetated areas and everything above 1 shows vegetation where the higher - the more active vegetation is on the field. #### Limitations Also it's important to consider clouds. In case you see a NDVI value around zero in a period of expected high vegetation it usually means that there was a week of cloudy images and all the results should be corrected. For South Africa it is a very unlikely situation. #### Tools NDVI values can be plotted on chart having dates on 1 axis and NDVI values on another. I like using [Highcharts](http://www.highcharts.com/) JS library to have professionally looking charts though it is commercial. [Chart.js](www.chartjs.org/) is Open Sources and gives good results. #### Information to visualize Besides visualizing a chart for a ongoing year you can analyze previous years and plot average, minimal, maximal or confidence interval for values. Reliable results can be generated by analyzing from 3 to 5 years of observation. #### Example 1: You can visualize how much NDVI changes from the previous time in %. Green is NDVI for 2015, Grey - average NDVI for 3 years, Red - NDVI change in %, Blue - zeros ![image](https://cloud.githubusercontent.com/assets/4834199/13893421/622b8e76-ed1b-11e5-8f56-b2a985da7625.png) #### Example 2: For commodity crops like corn, wheat and potatoes because they have a short vegetation cycle and properly described so an agronomist knows how each stage correlates with the next stages and what should be done/changed to improve the final results. There're 2 ways of smoothing this curve: 1. Add more years (5-7 years) 2. Smooth it mathematically around local maximum. For this case a number of vegetation cycles per year should be an additional parameter: * Green - NDVI for 2015 * Grey - Mathematical average calculated with the [JS library](http://mourner.github.io/simplify-js/) * Red - smoothed curve for 1 season ![image](https://cloud.githubusercontent.com/assets/4834199/13892326/d060931c-ed13-11e5-9533-bf3820616a66.png) ## Part 3 - Working with Maps: mapping platform, placing AD tiles, legend, over-zooming and z-index. ### mapping platform Basically mapping platform is a map with ability to place satellite images on the top of it. My favorite Mapping platform (a JavaScript library and a cloud storage) is Mapbox (https://www.mapbox.com/) it has the most powerful functionality in storing and visualizing the data. Also you can look at open sources Leaflet.js (http://leafletjs.com/) and popular Google Maps API (https://developers.google.com/maps/?hl=en) ### placing AD tiles Get processed Results: ```curl https://api.astrodigital.com/v2.0/results?task_id=175 -H 'Authorization: Token MY-TOKEN'``` In the response you will get map_id. You can use it to place on the map. Beyond just embedding the processed image on your site, you can use JavaScript to build an interactive experience around the imagery. Below is an example of using mapbox.js to interact with the processed imagery by embedding it within a webpage. Before you can utilize the mapbox.js tools, you will need a developer account and token which you can create here. ``` <html> <head> <title>Embed Example</title> <script src='https://api.tiles.mapbox.com/mapbox.js/v2.1.9/mapbox.js'></script> <link href='https://api.tiles.mapbox.com/mapbox.js/v2.1.9/mapbox.css' rel='stylesheet' /> <style> body { margin:0; padding:0; } #map { position:absolute; top:0; bottom:0; width:100%; } </style> </head> <body> <div id='map'></div> <script> L.mapbox.accessToken = 'MAPBOX_TOKEN'; // Mapbox public key - please email me if you need help with it var map = L.mapbox.map('map'); L.mapbox.tileLayer('astrodigital.LC80010802014240LGN00_bands_432', { format: 'png' }).addTo(map); // add satellite image to the map map.setView([-28.6713,-71.1475], 8); // specify initial view </script> </body> </html> ``` This simple example will give you a webpage with your processed image embedded on it. See Mapbox documentation for more information on how to add multiple images and data layers and enable greater interactivity. After you develop the first map you'll need some additional functionality. Based on experience of existing customers here's a list of articles you may find helpful: * map legend - https://bl.ocks.org/tristen/34589b26dafc70d30834 - to customize map legend with an image * over-zooming - https://www.mapbox.com/mapbox.js/example/v1.0.0/overzoom/ - to zoom very deep to the image * z-index - https://www.mapbox.com/mapbox-gl-js/example/toggle-layers/ - to switch between images from different dates quickly.