{"__v":19,"_id":"5661fdcb55e4450d00e62c7a","category":{"__v":1,"_id":"5661fdcb55e4450d00e62c74","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"},"parentDoc":null,"project":"5511df3be2990b0d00fb071d","user":"5511dee39171e82b00897349","version":{"__v":2,"_id":"5661fdca55e4450d00e62c73","project":"5511df3be2990b0d00fb071d","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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-06T19:27:56.731Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"About the Astro Digital Platform\"\n}\n[/block]\nAstro Digital is the API for your satellite data. Define your areas of interest, set custom trigger criteria, and receive notifications when new matching imagery is available. When you find something you like, our imagery processing pipeline turns raw satellite data into processed scenes and makes them available as a web service for embedding on internal and external websites.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to find, process and utilize imagery\"\n}\n[/block]\nAt Astro Digital we love arugula and decided to plant a large field of it just outside the city. We needed a way to continuously monitor the health of the field without having to take the bus across town. Programmatically accessing the latest images of our arugula field from space, analyzing the images to assess vegetation health, and receiving a map to display at the office turned out to be the best way to keep the arugula happy and the team healthy.\n\nAs an overview of the workflow, we will be looking at the following:\n1. How to create an account on the Astro Digital platform and find your access token\n2. Using the [search](doc:search) endpoint to find imagery of interest manually\n3. Enable monitoring process by creating [/tasks](doc:tasks) for each Area Of Interest [/aois](doc:aois). More about how to work with areas of interest is covered in this [article](doc:areas-of-interest-best-practices) \n4. Get all [/results](doc:results) generated for a task\n5. Using the [/products](doc:products) endpoint to determine satellite data products are available\n6. Get statistical information about account and data usage by calling [/user](doc:user)\n7. How to use available web tools to make the most of the API\n8. Reviewing ways to use the tiled map id we receive\n\n## Account Creation\nMany of the services provided by the Astro Digital platform can be used freely with no restrictions. However, to get the most out of the service (like using [tasks](doc:tasks) and [results](doc:results) and keeping track of your published imagery), you will want to create an account. You can do this by visiting the [website](https://fetch.astrodigital.com/) and signing up. You can continue with the steps below while you wait for the confirmation email to show up in your inbox.\n\n## Searching for imagery manually\nThe [search](doc:search) endpoint is a fast imagery search service that finds images corresponding to an area of interest. This example request gets images over our arugula field. By including the date range and setting it to end at some point in the future, we're ensuring we will get the latest images.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"How to find locations\",\n  \"body\": \"In the search below, we are using the center latitude and longitude of our field. There are a number of options for finding latitude and longitude for searches including [Google Maps](https://maps.google.com), [Google Geocoder API](https://developers.google.com/maps/documentation/geocoding/) and [geojson.io](http://geojson.io/).\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\"https://api.astrodigital.com/v2.0/search/?contains=-122.4376,37.7577\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"request\"\n    },\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"credit\\\": \\\"This API is based on the openFDA's API https://github.com/FDA/openfda/tree/master/api \\\",\\n    \\\"license\\\": \\\"http://creativecommons.org/publicdomain/zero/1.0/legalcode\\\",\\n    \\\"last_updated\\\": \\\"2015-04-13\\\",\\n    \\\"results\\\": {\\n      \\\"skip\\\": 0,\\n      \\\"limit\\\": 1,\\n      \\\"total\\\": 1\\n    }\\n  },\\n  \\\"results\\\": [\\n    {\\n      \\\"THERMAL_LINES\\\": \\\"\\\",\\n      \\\"SCAN_GAP_INTERPOLATION\\\": \\\"\\\",\\n      \\\"cloudCover\\\": 2,\\n      \\\"satelliteNumber\\\": \\\"\\\",\\n      \\\"row\\\": 34,\\n      \\\"DATE_ACQUIRED_GAP_FILL\\\": \\\"\\\",\\n      \\\"GEOMETRIC_RMSE_MODEL\\\": \\\"\\\",\\n      \\\"browseURL\\\": \\\"http://earthexplorer.usgs.gov/browse/landsat_8/2015/044/034/LC80440342015096LGN00.jpg\\\",\\n      \\\"ELEVATION_SOURCE\\\": \\\"\\\",\\n      \\\"gainBand6L\\\": \\\"\\\",\\n      \\\"gainBand6H\\\": \\\"\\\",\\n      \\\"FALSE_EASTING\\\": \\\"\\\",\\n      \\\"ELLIPSOID\\\": \\\"\\\",\\n      \\\"lowerRightCornerLongitude\\\": -121.34825,\\n      \\\"lowerLeftCornerLatitude\\\": 36.80333,\\n      \\\"sceneCenterLatitude\\\": 37.47432,\\n      \\\"sceneStopTime\\\": \\\"2015:096:18:45:43.2744260\\\",\\n      \\\"GROUND_CONTROL_POINTS_VERIFY\\\": \\\"\\\",\\n      \\\"sceneID\\\": \\\"LC80440342015096LGN00\\\",\\n      \\\"gainChangeBand6H\\\": \\\"\\\",\\n      \\\"FALSE_NORTHING\\\": \\\"\\\",\\n      \\\"gainChangeBand6L\\\": \\\"\\\",\\n      \\\"TRUE_SCALE_LAT\\\": \\\"\\\",\\n      \\\"REFLECTIVE_LINES\\\": \\\"\\\",\\n      \\\"cloudCoverFull\\\": 27.31,\\n      \\\"dayOrNight\\\": \\\"DAY\\\",\\n      \\\"flightPath\\\": \\\"\\\",\\n      \\\"dateUpdated\\\": \\\"2015-04-06\\\",\\n      \\\"sensor\\\": \\\"OLI_TIRS\\\",\\n      \\\"MAP_PROJECTION_L0RA\\\": \\\"\\\",\\n      \\\"GRID_CELL_SIZE_REFLECTIVE\\\": \\\"\\\",\\n      \\\"upperLeftCornerLongitude\\\": -122.93336,\\n      \\\"path\\\": 44,\\n      \\\"lowerLeftCornerLongitude\\\": -123.42307,\\n      \\\"GEOMETRIC_RMSE_MODEL_X\\\": 5.028,\\n      \\\"GEOMETRIC_RMSE_MODEL_Y\\\": 4.986,\\n      \\\"THERMAL_SAMPLES\\\": \\\"\\\",\\n      \\\"upperRightCornerLongitude\\\": -120.81027,\\n      \\\"DATA_TYPE_L0RP\\\": \\\"\\\",\\n      \\\"GRID_CELL_SIZE_THERMAL\\\": \\\"\\\",\\n      \\\"FULL_UL_QUAD_CCA\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_2\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_3\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_1\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_6\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_7\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_4\\\": \\\"\\\",\\n      \\\"PRESENT_BAND_5\\\": \\\"\\\",\\n      \\\"sunAzimuth\\\": 142.39446862,\\n      \\\"PRESENT_BAND_8\\\": \\\"\\\",\\n      \\\"cartURL\\\": \\\"http://earthexplorer.usgs.gov/order/process?dataset_name=LANDSAT_8&ordered=LC80440342015096LGN00\\\",\\n      \\\"PANCHROMATIC_LINES\\\": \\\"\\\",\\n      \\\"NADIR_OFFNADIR\\\": \\\"NADIR\\\",\\n      \\\"EPHEMERIS_TYPE\\\": \\\"\\\",\\n      \\\"GEOMETRIC_RMSE_VERIFY\\\": \\\"\\\",\\n      \\\"imageQuality2\\\": \\\"\\\",\\n      \\\"imageQuality1\\\": 9,\\n      \\\"ORIENTATION\\\": \\\"\\\",\\n      \\\"upperLeftCornerLatitude\\\": 38.52805,\\n      \\\"GAP_FILL\\\": \\\"\\\",\\n      \\\"PANCHROMATIC_SAMPLES\\\": \\\"\\\",\\n      \\\"L1_AVAILABLE\\\": \\\"\\\",\\n      \\\"UTM_ZONE\\\": \\\"\\\",\\n      \\\"FULL_LL_QUAD_CCA\\\": \\\"\\\",\\n      \\\"sceneCenterLongitude\\\": -122.12726,\\n      \\\"gainBand8\\\": \\\"\\\",\\n      \\\"gainBand5\\\": \\\"\\\",\\n      \\\"gainBand4\\\": \\\"\\\",\\n      \\\"gainBand7\\\": \\\"\\\",\\n      \\\"gainBand1\\\": \\\"\\\",\\n      \\\"gainBand3\\\": \\\"\\\",\\n      \\\"gainBand2\\\": \\\"\\\",\\n      \\\"MAP_PROJECTION_L1\\\": \\\"\\\",\\n      \\\"RESAMPLING_OPTION\\\": \\\"\\\",\\n      \\\"VERTICAL_LON_FROM_POLE\\\": \\\"\\\",\\n      \\\"receivingStation\\\": \\\"LGN\\\",\\n      \\\"gainChangeBand7\\\": \\\"\\\",\\n      \\\"gainChangeBand5\\\": \\\"\\\",\\n      \\\"gainChangeBand4\\\": \\\"\\\",\\n      \\\"gainChangeBand3\\\": \\\"\\\",\\n      \\\"gainChangeBand2\\\": \\\"\\\",\\n      \\\"gainChangeBand1\\\": \\\"\\\",\\n      \\\"REFLECTIVE_SAMPLES\\\": \\\"\\\",\\n      \\\"GRID_CELL_SIZE_PANCHROMATIC\\\": \\\"\\\",\\n      \\\"gainChangeBand8\\\": \\\"\\\",\\n      \\\"FULL_UR_QUAD_CCA\\\": \\\"\\\",\\n      \\\"GROUND_CONTROL_POINTS_MODEL\\\": \\\"\\\",\\n      \\\"browseAvailable\\\": \\\"Y\\\",\\n      \\\"DATA_TYPE_L1\\\": \\\"L1T\\\",\\n      \\\"lowerRightCornerLatitude\\\": 36.40608,\\n      \\\"sceneStartTime\\\": \\\"2015:096:18:45:11.5044300\\\",\\n      \\\"sunElevation\\\": 53.62064698,\\n      \\\"acquisitionDate\\\": \\\"2015-04-06\\\",\\n      \\\"OUTPUT_FORMAT\\\": \\\"\\\",\\n      \\\"FULL_LR_QUAD_CCA\\\": \\\"\\\",\\n      \\\"lookAngle\\\": \\\"\\\",\\n      \\\"DATUM\\\": \\\"\\\",\\n      \\\"upperRightCornerLatitude\\\": 38.12951\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response\"\n    }\n  ]\n}\n[/block]\nIn the results, find the `scene_id` which is a unique identifier for every image in the system and what you will use to identify the image for processing.\n\n## Automate that search, set up a Task\nInstead of going through the process of manually searching each time to see when new imagery is available, we can also set up a Task to automatically notify us and generate products for the Task. To do this, you will need to have an authentication token, so make sure you have successfully created your account. When you visit your [Account Page](https://fetch.astrodigital.com) you can find your token on the **sidebar** like below.\n\n![](https://cloud.githubusercontent.com/assets/848934/13092325/4fa32540-d4cd-11e5-8d14-402ae8b32604.png)\n\nTo set up a new Task for our arugula field, we can make a call like below and should receive a Task object as an indication of success.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl 'https://api.astrodigital.com/v2.0/tasks' --data '{\\n  \\\"name\\\":\\\"Our Arugula Field\\\", \\n  \\\"products\\\": [{\\\"product\\\": \\\"ndvi_image\\\", \\\"actions\\\": [\\\"mapbox\\\"]}], \\t\\t\\n  \\\"query\\\": {\\n    \\\"date_from\\\": \\\"2015-11-01\\\",\\n    \\\"date_to\\\": \\\"2016-01-01\\\",\\n    \\\"aoi\\\": {\\n      \\\"type\\\": \\\"Polygon\\\",\\n      \\\"coordinates\\\": [\\n        [\\n            [-122.62664794921874, 38.81403111409755],\\n            [-122.62664794921874, 39.07464374293249],\\n            [-122.16796875, 39.07464374293249],\\n            [-122.16796875, 38.81403111409755],\\n            [-122.62664794921874, 38.81403111409755]\\n        ]\\n      ]\\n    }\\n  }\\n}' -H 'Content-Type: application/json' -H 'Authorization: Token YOUR_TOKEN'\",\n      \"language\": \"curl\",\n      \"name\": \"request\"\n    },\n    {\n      \"code\": \"{\\n    \\\"id\\\":1,\\n    \\\"name\\\":\\\"My Alert\\\",\\n    \\\"created_at\\\":\\\"2016-01-27T15:24:03.126309Z\\\",\\n    \\\"updated_at\\\":\\\"2016-01-27T15:24:03.126335Z\\\",\\n    \\\"query\\\":{\\n        \\\"date_to\\\":\\\"2017-01-01\\\",\\n        \\\"aoi\\\":{\\n            \\\"coordinates\\\":[\\n              [\\n                [-121.9482421875, 38.19718009396176],\\n                [-121.9482421875, 38.29424797320529],\\n                [-121.805419921875, 38.29424797320529],\\n                [-121.805419921875, 38.19718009396176],\\n                [-121.9482421875, 38.19718009396176]\\n              ]\\n            ],\\n            \\\"type\\\":\\\"Polygon\\\"\\n        },\\n        \\\"date_from\\\":\\\"2015-01-01\\\"\\n    },\\n    \\\"recurring\\\":true,\\n    \\\"end_date\\\":null,\\n    \\\"status\\\":\\\"ACTIVE\\\",\\n    \\\"status_time\\\":\\\"2016-01-27T15:24:03.126087Z\\\",\\n    \\\"expected_results\\\":20,\\n    \\\"aoi\\\":1,\\n    \\\"products\\\":[\\n        {\\n            \\\"product\\\":\\\"ndvi_image\\\",\\n            \\\"actions\\\":[\\\"mapbox\\\", \\\"notify\\\"]\\n        }\\n    ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response\"\n    }\n  ]\n}\n[/block]\nAnd that's it! We've just created a Task on the system representing our custom imagery pipeline. Whenever new imagery meets your criteria, it will be be run through an NDVI process and the resulting image will be made available as a webmap and you will receive an email. Tasks and Results are very powerful so make sure to read the [Overview](doc:overview).\n\n## Check to see if you have new Results available\nNew imagery is currently added to the platform once a night at midnight Pacific Time. So you don't need to keep checking back constantly. If you chose to be notified by email when there is new matching imagery, we'll send that along, but if you're sticking with the API, you can check the [results](doc:results) endpoint to see if you have anything new waiting for you. Below is an example of a request and response.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl 'https://api.astrodigital.com/v2.0/results' -H 'Authorization: Token YOUR_TOKEN'\",\n      \"language\": \"curl\",\n      \"name\": \"request\"\n    },\n    {\n      \"code\": \"{\\n    \\\"count\\\":2,\\n    \\\"next\\\":null,\\n    \\\"previous\\\":null,\\n    \\\"results\\\":[\\n        {\\n            \\\"id\\\":19,\\n            \\\"created_at\\\":\\\"2016-01-29T18:59:52.090109Z\\\",\\n            \\\"value\\\":{\\n                \\\"map_id\\\":\\\"astrodigital.56abb16f4959330006010a83\\\",\\n                \\\"raw_image_url\\\":\\\"http://storage.googleapis.com/earthengine-public/landsat/L8/099/066/LC80990662016021LGN00.tar.bz\\\"\\n            },\\n            \\\"product\\\": \\\"true_color\\\",\\n            \\\"status\\\":\\\"COMPLETED\\\",\\n            \\\"status_time\\\":\\\"2016-01-29T18:59:52.101871Z\\\",\\n            \\\"secondary_status\\\":null,\\n            \\\"is_failed\\\":false,\\n            \\\"fail_reason\\\":null,\\n            \\\"fail_time\\\":null,\\n            \\\"is_ready\\\":true,\\n            \\\"task\\\":42\\n        },\\n        {\\n            \\\"id\\\":17,\\n            \\\"created_at\\\":\\\"2016-01-29T18:47:02.932512Z\\\",\\n            \\\"value\\\":{\\n                \\\"raw_image_url\\\":\\\"http://storage.googleapis.com/earthengine-public/landsat/L8/099/066/LC80990662016021LGN00.tar.bz\\\"\\n            },\\n            \\\"product\\\": \\\"urban_false\\\",\\n            \\\"status\\\":\\\"COMPLETED\\\",\\n            \\\"status_time\\\":\\\"2016-01-29T18:51:08.801238Z\\\",\\n            \\\"secondary_status\\\":null,\\n            \\\"is_failed\\\":false,\\n            \\\"fail_reason\\\":null,\\n            \\\"fail_time\\\":null,\\n            \\\"is_ready\\\":true,\\n            \\\"task\\\":40\\n        }\\n    ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response\"\n    }\n  ]\n}\n[/block]\n## How to Determine the best processing method for your imagery\nWhen we set up the Task above, we chose the `ndvi_image` product because we knew we wanted to see how healthy the vegetation was in our area of interest. But the platform supports many other types of processing, called [Products](doc:products). Knowing what you want to do with the imagery dictates the way you process the imagery.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\"https://api.astrodigital.com/v2.0/products\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"request\"\n    },\n    {\n      \"code\": \"{\\n  \\\"count\\\": 6,\\n  \\\"next\\\": null,\\n  \\\"previous\\\": null,\\n  \\\"results\\\": [\\n    {\\n      \\\"id\\\": 1,\\n      \\\"description\\\": \\\"A visually appealing approximation of the image's natural appearance.\\\",\\n      \\\"name\\\": \\\"True Color Image\\\",\\n      \\\"product\\\": \\\"true_color\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\",\\n        \\\"mapbox\\\",\\n        \\\"raw\\\",\\n        \\\"processed\\\"\\n      ]\\n    },\\n    {\\n      \\\"id\\\": 2,\\n      \\\"description\\\": \\\"Visualize the health of vegetation; the densest vegetation is shown in orange.\\\",\\n      \\\"name\\\": \\\"NDVI\\\",\\n      \\\"product\\\": \\\"ndvi_image\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\",\\n        \\\"mapbox\\\",\\n        \\\"raw\\\",\\n        \\\"processed\\\"\\n      ]\\n    },\\n    {\\n      \\\"id\\\": 3,\\n      \\\"description\\\": \\\"Monitor city growth; blues and grays show urban areas.\\\",\\n      \\\"name\\\": \\\"Urban False Color\\\",\\n      \\\"product\\\": \\\"urban_false\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\",\\n        \\\"mapbox\\\",\\n        \\\"raw\\\",\\n        \\\"processed\\\"\\n      ]\\n    },\\n    {\\n      \\\"id\\\": 4,\\n      \\\"description\\\": \\\"Uses the near infrared band to easily identify shorelines.\\\",\\n      \\\"name\\\": \\\"Land/Water Boundary\\\",\\n      \\\"product\\\": \\\"land_water\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\",\\n        \\\"mapbox\\\",\\n        \\\"raw\\\",\\n        \\\"processed\\\"\\n      ]\\n    },\\n    {\\n      \\\"id\\\": 5,\\n      \\\"description\\\": \\\"Retrieve an averaged NDVI value for your AOIs.\\\",\\n      \\\"name\\\": \\\"NDVI Values\\\",\\n      \\\"product\\\": \\\"ndvi_value\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\"\\n      ]\\n    },\\n    {\\n      \\\"id\\\": 6,\\n      \\\"description\\\": \\\"Search our full imagery catalog for matches and receive metadata.\\\",\\n      \\\"name\\\": \\\"Get Metadata\\\",\\n      \\\"product\\\": \\\"metadata\\\",\\n      \\\"actions\\\": [\\n        \\\"notify\\\",\\n        \\\"raw\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response\"\n    }\n  ]\n}\n[/block]\n## Check on the status of your Tasks\nYou can check in on the status of your Task at any time by looking at the Results it is creating. You can use the [/results/](doc:results) endpoint to see a list of all your recent Results.\n\n## Using available web tools\nEverything we've talked about so far has been built upon the powerful API that the Astro Digital platform exposes. But we have also built a suite of web tools that will help you achieve many of the same tasks. \n\nFor example, you can go through the entire Search, Create Task and View Results starting at [Fetch](https://fetch.astrodigital.com).\n\n## Using the imagery in your project\nWhen the processing completes you are given a `map_id` which is a pointer to a tiled image layer. There are two ways you can use this `map_id`:\n\n1. Display it using our map at [http://publish.astrodigital.com/#{map_id}](http://publish.astrodigital.com/#astrodigital.LC80440342015080LGN00_bands_543). For example - http://publish.astrodigital.com/#astrodigital.LC80440342015080LGN00_bands_543). \n\n2. Use it within any mapping platform that consumes such resources like [Mapbox](http://mapbox.com) or [Leaflet](http://leafletjs.com/).\n\nThat's it! In this workflow we stepped through finding imagery in an area of interest; discovering a processing method and executing that request for processing; watching for the processing to be finished; getting a link to visualize the processed image.","excerpt":"Welcome to the Astro Digital developer hub. [Create an account](https://fetch.astrodigital.com/), get your API key, and start building.","slug":"getting-started","type":"basic","title":"Quick Start"}

Quick Start

Welcome to the Astro Digital developer hub. [Create an account](https://fetch.astrodigital.com/), get your API key, and start building.

[block:api-header] { "type": "basic", "title": "About the Astro Digital Platform" } [/block] Astro Digital is the API for your satellite data. Define your areas of interest, set custom trigger criteria, and receive notifications when new matching imagery is available. When you find something you like, our imagery processing pipeline turns raw satellite data into processed scenes and makes them available as a web service for embedding on internal and external websites. [block:api-header] { "type": "basic", "title": "How to find, process and utilize imagery" } [/block] At Astro Digital we love arugula and decided to plant a large field of it just outside the city. We needed a way to continuously monitor the health of the field without having to take the bus across town. Programmatically accessing the latest images of our arugula field from space, analyzing the images to assess vegetation health, and receiving a map to display at the office turned out to be the best way to keep the arugula happy and the team healthy. As an overview of the workflow, we will be looking at the following: 1. How to create an account on the Astro Digital platform and find your access token 2. Using the [search](doc:search) endpoint to find imagery of interest manually 3. Enable monitoring process by creating [/tasks](doc:tasks) for each Area Of Interest [/aois](doc:aois). More about how to work with areas of interest is covered in this [article](doc:areas-of-interest-best-practices) 4. Get all [/results](doc:results) generated for a task 5. Using the [/products](doc:products) endpoint to determine satellite data products are available 6. Get statistical information about account and data usage by calling [/user](doc:user) 7. How to use available web tools to make the most of the API 8. Reviewing ways to use the tiled map id we receive ## Account Creation Many of the services provided by the Astro Digital platform can be used freely with no restrictions. However, to get the most out of the service (like using [tasks](doc:tasks) and [results](doc:results) and keeping track of your published imagery), you will want to create an account. You can do this by visiting the [website](https://fetch.astrodigital.com/) and signing up. You can continue with the steps below while you wait for the confirmation email to show up in your inbox. ## Searching for imagery manually The [search](doc:search) endpoint is a fast imagery search service that finds images corresponding to an area of interest. This example request gets images over our arugula field. By including the date range and setting it to end at some point in the future, we're ensuring we will get the latest images. [block:callout] { "type": "info", "title": "How to find locations", "body": "In the search below, we are using the center latitude and longitude of our field. There are a number of options for finding latitude and longitude for searches including [Google Maps](https://maps.google.com), [Google Geocoder API](https://developers.google.com/maps/documentation/geocoding/) and [geojson.io](http://geojson.io/)." } [/block] [block:code] { "codes": [ { "code": "curl \"https://api.astrodigital.com/v2.0/search/?contains=-122.4376,37.7577\"", "language": "curl", "name": "request" }, { "code": "{\n \"meta\": {\n \"credit\": \"This API is based on the openFDA's API https://github.com/FDA/openfda/tree/master/api \",\n \"license\": \"http://creativecommons.org/publicdomain/zero/1.0/legalcode\",\n \"last_updated\": \"2015-04-13\",\n \"results\": {\n \"skip\": 0,\n \"limit\": 1,\n \"total\": 1\n }\n },\n \"results\": [\n {\n \"THERMAL_LINES\": \"\",\n \"SCAN_GAP_INTERPOLATION\": \"\",\n \"cloudCover\": 2,\n \"satelliteNumber\": \"\",\n \"row\": 34,\n \"DATE_ACQUIRED_GAP_FILL\": \"\",\n \"GEOMETRIC_RMSE_MODEL\": \"\",\n \"browseURL\": \"http://earthexplorer.usgs.gov/browse/landsat_8/2015/044/034/LC80440342015096LGN00.jpg\",\n \"ELEVATION_SOURCE\": \"\",\n \"gainBand6L\": \"\",\n \"gainBand6H\": \"\",\n \"FALSE_EASTING\": \"\",\n \"ELLIPSOID\": \"\",\n \"lowerRightCornerLongitude\": -121.34825,\n \"lowerLeftCornerLatitude\": 36.80333,\n \"sceneCenterLatitude\": 37.47432,\n \"sceneStopTime\": \"2015:096:18:45:43.2744260\",\n \"GROUND_CONTROL_POINTS_VERIFY\": \"\",\n \"sceneID\": \"LC80440342015096LGN00\",\n \"gainChangeBand6H\": \"\",\n \"FALSE_NORTHING\": \"\",\n \"gainChangeBand6L\": \"\",\n \"TRUE_SCALE_LAT\": \"\",\n \"REFLECTIVE_LINES\": \"\",\n \"cloudCoverFull\": 27.31,\n \"dayOrNight\": \"DAY\",\n \"flightPath\": \"\",\n \"dateUpdated\": \"2015-04-06\",\n \"sensor\": \"OLI_TIRS\",\n \"MAP_PROJECTION_L0RA\": \"\",\n \"GRID_CELL_SIZE_REFLECTIVE\": \"\",\n \"upperLeftCornerLongitude\": -122.93336,\n \"path\": 44,\n \"lowerLeftCornerLongitude\": -123.42307,\n \"GEOMETRIC_RMSE_MODEL_X\": 5.028,\n \"GEOMETRIC_RMSE_MODEL_Y\": 4.986,\n \"THERMAL_SAMPLES\": \"\",\n \"upperRightCornerLongitude\": -120.81027,\n \"DATA_TYPE_L0RP\": \"\",\n \"GRID_CELL_SIZE_THERMAL\": \"\",\n \"FULL_UL_QUAD_CCA\": \"\",\n \"PRESENT_BAND_2\": \"\",\n \"PRESENT_BAND_3\": \"\",\n \"PRESENT_BAND_1\": \"\",\n \"PRESENT_BAND_6\": \"\",\n \"PRESENT_BAND_7\": \"\",\n \"PRESENT_BAND_4\": \"\",\n \"PRESENT_BAND_5\": \"\",\n \"sunAzimuth\": 142.39446862,\n \"PRESENT_BAND_8\": \"\",\n \"cartURL\": \"http://earthexplorer.usgs.gov/order/process?dataset_name=LANDSAT_8&ordered=LC80440342015096LGN00\",\n \"PANCHROMATIC_LINES\": \"\",\n \"NADIR_OFFNADIR\": \"NADIR\",\n \"EPHEMERIS_TYPE\": \"\",\n \"GEOMETRIC_RMSE_VERIFY\": \"\",\n \"imageQuality2\": \"\",\n \"imageQuality1\": 9,\n \"ORIENTATION\": \"\",\n \"upperLeftCornerLatitude\": 38.52805,\n \"GAP_FILL\": \"\",\n \"PANCHROMATIC_SAMPLES\": \"\",\n \"L1_AVAILABLE\": \"\",\n \"UTM_ZONE\": \"\",\n \"FULL_LL_QUAD_CCA\": \"\",\n \"sceneCenterLongitude\": -122.12726,\n \"gainBand8\": \"\",\n \"gainBand5\": \"\",\n \"gainBand4\": \"\",\n \"gainBand7\": \"\",\n \"gainBand1\": \"\",\n \"gainBand3\": \"\",\n \"gainBand2\": \"\",\n \"MAP_PROJECTION_L1\": \"\",\n \"RESAMPLING_OPTION\": \"\",\n \"VERTICAL_LON_FROM_POLE\": \"\",\n \"receivingStation\": \"LGN\",\n \"gainChangeBand7\": \"\",\n \"gainChangeBand5\": \"\",\n \"gainChangeBand4\": \"\",\n \"gainChangeBand3\": \"\",\n \"gainChangeBand2\": \"\",\n \"gainChangeBand1\": \"\",\n \"REFLECTIVE_SAMPLES\": \"\",\n \"GRID_CELL_SIZE_PANCHROMATIC\": \"\",\n \"gainChangeBand8\": \"\",\n \"FULL_UR_QUAD_CCA\": \"\",\n \"GROUND_CONTROL_POINTS_MODEL\": \"\",\n \"browseAvailable\": \"Y\",\n \"DATA_TYPE_L1\": \"L1T\",\n \"lowerRightCornerLatitude\": 36.40608,\n \"sceneStartTime\": \"2015:096:18:45:11.5044300\",\n \"sunElevation\": 53.62064698,\n \"acquisitionDate\": \"2015-04-06\",\n \"OUTPUT_FORMAT\": \"\",\n \"FULL_LR_QUAD_CCA\": \"\",\n \"lookAngle\": \"\",\n \"DATUM\": \"\",\n \"upperRightCornerLatitude\": 38.12951\n }\n ]\n}", "language": "json", "name": "response" } ] } [/block] In the results, find the `scene_id` which is a unique identifier for every image in the system and what you will use to identify the image for processing. ## Automate that search, set up a Task Instead of going through the process of manually searching each time to see when new imagery is available, we can also set up a Task to automatically notify us and generate products for the Task. To do this, you will need to have an authentication token, so make sure you have successfully created your account. When you visit your [Account Page](https://fetch.astrodigital.com) you can find your token on the **sidebar** like below. ![](https://cloud.githubusercontent.com/assets/848934/13092325/4fa32540-d4cd-11e5-8d14-402ae8b32604.png) To set up a new Task for our arugula field, we can make a call like below and should receive a Task object as an indication of success. [block:code] { "codes": [ { "code": "curl 'https://api.astrodigital.com/v2.0/tasks' --data '{\n \"name\":\"Our Arugula Field\", \n \"products\": [{\"product\": \"ndvi_image\", \"actions\": [\"mapbox\"]}], \t\t\n \"query\": {\n \"date_from\": \"2015-11-01\",\n \"date_to\": \"2016-01-01\",\n \"aoi\": {\n \"type\": \"Polygon\",\n \"coordinates\": [\n [\n [-122.62664794921874, 38.81403111409755],\n [-122.62664794921874, 39.07464374293249],\n [-122.16796875, 39.07464374293249],\n [-122.16796875, 38.81403111409755],\n [-122.62664794921874, 38.81403111409755]\n ]\n ]\n }\n }\n}' -H 'Content-Type: application/json' -H 'Authorization: Token YOUR_TOKEN'", "language": "curl", "name": "request" }, { "code": "{\n \"id\":1,\n \"name\":\"My Alert\",\n \"created_at\":\"2016-01-27T15:24:03.126309Z\",\n \"updated_at\":\"2016-01-27T15:24:03.126335Z\",\n \"query\":{\n \"date_to\":\"2017-01-01\",\n \"aoi\":{\n \"coordinates\":[\n [\n [-121.9482421875, 38.19718009396176],\n [-121.9482421875, 38.29424797320529],\n [-121.805419921875, 38.29424797320529],\n [-121.805419921875, 38.19718009396176],\n [-121.9482421875, 38.19718009396176]\n ]\n ],\n \"type\":\"Polygon\"\n },\n \"date_from\":\"2015-01-01\"\n },\n \"recurring\":true,\n \"end_date\":null,\n \"status\":\"ACTIVE\",\n \"status_time\":\"2016-01-27T15:24:03.126087Z\",\n \"expected_results\":20,\n \"aoi\":1,\n \"products\":[\n {\n \"product\":\"ndvi_image\",\n \"actions\":[\"mapbox\", \"notify\"]\n }\n ]\n}", "language": "json", "name": "response" } ] } [/block] And that's it! We've just created a Task on the system representing our custom imagery pipeline. Whenever new imagery meets your criteria, it will be be run through an NDVI process and the resulting image will be made available as a webmap and you will receive an email. Tasks and Results are very powerful so make sure to read the [Overview](doc:overview). ## Check to see if you have new Results available New imagery is currently added to the platform once a night at midnight Pacific Time. So you don't need to keep checking back constantly. If you chose to be notified by email when there is new matching imagery, we'll send that along, but if you're sticking with the API, you can check the [results](doc:results) endpoint to see if you have anything new waiting for you. Below is an example of a request and response. [block:code] { "codes": [ { "code": "curl 'https://api.astrodigital.com/v2.0/results' -H 'Authorization: Token YOUR_TOKEN'", "language": "curl", "name": "request" }, { "code": "{\n \"count\":2,\n \"next\":null,\n \"previous\":null,\n \"results\":[\n {\n \"id\":19,\n \"created_at\":\"2016-01-29T18:59:52.090109Z\",\n \"value\":{\n \"map_id\":\"astrodigital.56abb16f4959330006010a83\",\n \"raw_image_url\":\"http://storage.googleapis.com/earthengine-public/landsat/L8/099/066/LC80990662016021LGN00.tar.bz\"\n },\n \"product\": \"true_color\",\n \"status\":\"COMPLETED\",\n \"status_time\":\"2016-01-29T18:59:52.101871Z\",\n \"secondary_status\":null,\n \"is_failed\":false,\n \"fail_reason\":null,\n \"fail_time\":null,\n \"is_ready\":true,\n \"task\":42\n },\n {\n \"id\":17,\n \"created_at\":\"2016-01-29T18:47:02.932512Z\",\n \"value\":{\n \"raw_image_url\":\"http://storage.googleapis.com/earthengine-public/landsat/L8/099/066/LC80990662016021LGN00.tar.bz\"\n },\n \"product\": \"urban_false\",\n \"status\":\"COMPLETED\",\n \"status_time\":\"2016-01-29T18:51:08.801238Z\",\n \"secondary_status\":null,\n \"is_failed\":false,\n \"fail_reason\":null,\n \"fail_time\":null,\n \"is_ready\":true,\n \"task\":40\n }\n ]\n}", "language": "json", "name": "response" } ] } [/block] ## How to Determine the best processing method for your imagery When we set up the Task above, we chose the `ndvi_image` product because we knew we wanted to see how healthy the vegetation was in our area of interest. But the platform supports many other types of processing, called [Products](doc:products). Knowing what you want to do with the imagery dictates the way you process the imagery. [block:code] { "codes": [ { "code": "curl \"https://api.astrodigital.com/v2.0/products\"", "language": "curl", "name": "request" }, { "code": "{\n \"count\": 6,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": 1,\n \"description\": \"A visually appealing approximation of the image's natural appearance.\",\n \"name\": \"True Color Image\",\n \"product\": \"true_color\",\n \"actions\": [\n \"notify\",\n \"mapbox\",\n \"raw\",\n \"processed\"\n ]\n },\n {\n \"id\": 2,\n \"description\": \"Visualize the health of vegetation; the densest vegetation is shown in orange.\",\n \"name\": \"NDVI\",\n \"product\": \"ndvi_image\",\n \"actions\": [\n \"notify\",\n \"mapbox\",\n \"raw\",\n \"processed\"\n ]\n },\n {\n \"id\": 3,\n \"description\": \"Monitor city growth; blues and grays show urban areas.\",\n \"name\": \"Urban False Color\",\n \"product\": \"urban_false\",\n \"actions\": [\n \"notify\",\n \"mapbox\",\n \"raw\",\n \"processed\"\n ]\n },\n {\n \"id\": 4,\n \"description\": \"Uses the near infrared band to easily identify shorelines.\",\n \"name\": \"Land/Water Boundary\",\n \"product\": \"land_water\",\n \"actions\": [\n \"notify\",\n \"mapbox\",\n \"raw\",\n \"processed\"\n ]\n },\n {\n \"id\": 5,\n \"description\": \"Retrieve an averaged NDVI value for your AOIs.\",\n \"name\": \"NDVI Values\",\n \"product\": \"ndvi_value\",\n \"actions\": [\n \"notify\"\n ]\n },\n {\n \"id\": 6,\n \"description\": \"Search our full imagery catalog for matches and receive metadata.\",\n \"name\": \"Get Metadata\",\n \"product\": \"metadata\",\n \"actions\": [\n \"notify\",\n \"raw\"\n ]\n }\n ]\n}", "language": "json", "name": "response" } ] } [/block] ## Check on the status of your Tasks You can check in on the status of your Task at any time by looking at the Results it is creating. You can use the [/results/](doc:results) endpoint to see a list of all your recent Results. ## Using available web tools Everything we've talked about so far has been built upon the powerful API that the Astro Digital platform exposes. But we have also built a suite of web tools that will help you achieve many of the same tasks. For example, you can go through the entire Search, Create Task and View Results starting at [Fetch](https://fetch.astrodigital.com). ## Using the imagery in your project When the processing completes you are given a `map_id` which is a pointer to a tiled image layer. There are two ways you can use this `map_id`: 1. Display it using our map at [http://publish.astrodigital.com/#{map_id}](http://publish.astrodigital.com/#astrodigital.LC80440342015080LGN00_bands_543). For example - http://publish.astrodigital.com/#astrodigital.LC80440342015080LGN00_bands_543). 2. Use it within any mapping platform that consumes such resources like [Mapbox](http://mapbox.com) or [Leaflet](http://leafletjs.com/). That's it! In this workflow we stepped through finding imagery in an area of interest; discovering a processing method and executing that request for processing; watching for the processing to be finished; getting a link to visualize the processed image.