{
"swagger": "2.0",
"info": {
"title": "Harmonized Landsat Sentinel Service",
"version": "1.0",
"description": "The Harmonized Landsat-Sentinel Service API produces high-resolution imagery and NDVI data for a desired area-of-interest. From NASA, the Harmonized Landsat-Sentinel-2 project is an initiative to produce a consistent, harmonized surface reflectance product from Landsat and Sentinel-2 data. \n
\n"
},
"host": "ag-analytics.azure-api.net",
"basePath": "/hls-service",
"schemes": [
"https"
],
"paths": {
"/": {
"post": {
"description": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nThe Ag-Analytics® Harmonized Landsat-Sentinel Service (HLS) API provides the service in which a user can provide an area-of-interest (AOI) with additional customized options to retrieve the dynamics of their land at various times from the Landsat-8 and Sentinel-2 satellites. This service provides information on cloud cover, statistics, and Normalized Difference Vegetation Index in addition to MSI bands information. \n
\nThe Harmonized Landsat-Sentinel (HLS) Project is a NASA initiative to produce a Virtual Constellation (VC) of surface reflectance (SR) data from the Operational Land Imager (OLI) and MultiSpectral Instrument (MSI) onboard the Landsat-8 and Sentinel-2 remote sensing satellites, respectively. The data from these satellites creates unprecedented opportunities for timely and accurate observation of Earth status and dynamics at moderate (<30 m) spatial resolution every 2-3 days.
\n\n
When a user passes an area-of-interest (AOI) in the form of a shapefile, json, raster .tif, or geojson, the service finds the correct satellite imagery and clips each image to the AOI given. The service has the options to interpolate the result and to specify the imagery weeks that are returned.
\n**When the interpolation option is chosen, the AOI will be a larger area (determined by the interpolation parameters) of the given field boundary. Otherwise, the AOI will be a rectangle polygon around the given AOI.
\n(**when interpolation is chosen)
\nDue to cloud cover, the original satellite images may have many gaps and can not fully cover the area-of-interest (AOI). The interest to solve this problem arose in 2003, and there have been many papers and methods developed for this problem since then. After comparing and testing multiple methods and algorithms that have been used in dealing with the missing data on remote sensing satellite images, we adopted a customized "inpainting" method - which means filling gaps in an image by extrapolating the existing parts of the image in our API service.
\nTo take the spatial and temporal correlation of the images into consideration, our customized inpainting algorithm "inpaints" a sequence of images with cloud covered for the given AOI. Each missing part (multiple pixels) at a certain location is inpainted by linear transformation of the intensity of pixels at the same location of other images where the data of these pixels are available.
\nParameter | \nData Type | \nRequired? | \nDefault | \nOptions | \nDescription | \n
---|---|---|---|---|---|
AOI | \nGeometry, file/text | \nYes | \n-- | \nJSON, GEOJSON, Shapefile, Raster | \nSee Fig. 2 for further explanation. | \n
Band | \nList | \nYes | \n-- | \nSee \"Band\" Parameter Options Table | \nProvide the list of HLS Spectral band names to retrieve for given AOI. See Figures 3-4. | \n
Startdate | \nDate | \nNo | \n-- | \nmm/dd/yyyy | \n• Landsat – data starts from 2013 • Sentinel – data starts from 2015 | \n
Enddate | \nDate | \nNo | \n-- | \nmm/dd/yyyy | \nIn the absence of startdate or enddate, or both, the service retrieves the latest information available on the land. | \n
byweek | \nInt, boolean | \nNo | \n1 | \n1, 0 | \nIf set to 1, result raster will be the mosaic of all the tiles in a particular week for a given satellite | \n
satellite | \ntext | \nNo | \nLandsat | \nLandsat, Sentinel | \nIf set to both Landsat, Sentinel then the result raster will be the mosaic of both satellites for the given dates | \n
showlatest | \nInt, boolean | \nNo | \n1 | \n-- | \nIf startdate or enddate is not given, shows the latest available tile. | \n
filter | \nInt, boolean | \nNo | \n0 | \n0, 1 | \nIf set to 1, returns the response which is cloud-free after mosaic. | \n
qafilter | \nInt, boolean | \nNo | \n0 | \n0, 1 | \nIf set to 1, continues to filter tiles until the invalid pixels are < qacloudperc | \n
qacloudperc | \nfloat | \nNo | \n100 | \n0-100 | \nThis parameter comes to action with qafilter. If qafilter parameter is 1, then filters the tiles until the invalid pixels in those are < qacloudperc | \n
displaynormalvalues | \nfloat | \nNo | \n2000 | \n-- | \nThis parameter is used to normalize the band values for display purposes. Used for bands like RGB, AGR, etc. | \n
legendtype | \ntext | \nNo | \nRelative | \nRelative, Absolute | \nLegend type of display ranges of resulting response. | \n
resolution | \nfloat | \nNo | \n0.0001 | \n-- | \nCellsize in meters. | \n
flatten_data | \nInt, boolean | \nNo | \n0 | \n0, 1 | \nFlatten data which has a list of Xcoord, Ycoord and Values for each band in the output. If 1, flatten_data is returned. | \n
statistics | \nInt, boolean | \nNo | \n1 | \n0, 1 | \nReturns statistical features of the output .tif file. | \n
return_tif | \nint | \nNo | \n1 | \n0, 1 | \nReturns the downloadable link to output raster. If 0, link will not be returned. | \n
projection | \ntext | \nNo | \nProjection of AOI Given | \nSee Figure 5 | \nEnter the desired projection for the result raster. See Figure 5 for details. | \n
API Variable | \nBand Definition | \nDescription | \n
---|---|---|
Red | \nRed (0.64-0.67µm) | \nReflects reds, such as tropical soils or rust-like soils. | \n
Green | \nGreen (0.53-0.59µm) | \nReflects greens, particularly leaf surfaces. | \n
Blue | \nBlue (0.45-0.51µm) | \nReflects blues, particularly helpful for deep waters. | \n
NIR | \nNear Infrared (0.76-0.90µm) | \nReflects healthy vegetation. | \n
NIR_Broad | \nNear Infrared (.842 µm central) | \nGood for mapping shorelines and biomass content, as well as at detecting and analyzing vegetation. | \n
Red_Edge_1 | \nRed Edge (.69 - .71µm) | \nCan gauge foliage chlorophyll, canopy area, and water content. Applications include growth studies, precision ag, and vegetation productivity modeling. | \n
Red_Edge_2 | \nRed Edge (0.73 – 0.75 µm) | \nCan gauge foliage chlorophyll, canopy area, and water content | \n
Red_edge_3 | \nRed Edge (0.77 – 0.79 µm) | \nCan gauge foliage chlorophyll, canopy area, and water content | \n
SWIR1 | \nShort-wave Infrared (1.57-1.65µm) | \nSensitive to moisture content. Assists in distinguishing between dry and wet soils and vegetation. | \n
SWIR2 | \nShort-wave Infrared 2 (2.08-2.35µm) | \nUsed in imaging soil types, geological features, and minerals. Sensitive to vegetation and soil moisture variations. | \n
Coastal Aerosol | \nCoastal Aerosol (0.43-0.45µm) | \nReflects blues and violets. | \n
QA | \nQuality Assessment | \nProvides useful information for optimizing the value of pixels, identifying which pixels may be affected by surface conditions, clouds, or sensor conditions. | \n
Index Name | \nAPI Variable | \nFormula | \nDescription | \n
---|---|---|---|
Normalized Difference Vegetation Index (NDVI) | \n NDVI | \n NDVI = (NIR - Red) / (NIR + Red) | \n NDVI is derived from readily available satellite imagery which is positively correlated with green vegetation cover | \n
Red-Green-Blue (RGB) | \n RGB | \n Composite of red, green, and blue bands. | \n Color imagery, how the human eye would view something. | \n
Normalized Difference Water Index (NDWI) | \n NDWI | \n NDWI = (NIR - SWIR) / (NIR + SWIR) | \n NDWI uses the NIR and SWIR bands to determine changes in water content | \n
Normalized Difference Buildup Index (NDBI) | \n NDBI | \n NDBI = (SWIR1 - NIR) / (SWIR1 + NIR) | \n NDBI uses SWIR1 and NIR bands to determine urban areas | \n
Normalized Difference Tillage Index (NDTI) | \n NDTI | \n NDTI = (SWIR1 - SWIR2) / (SWIR1 + SWIR2) | \n Similarly, NDTI is also derived from satellite imagery but calculated with different bands. It is positively correlated with crop residue cover | \n
Urban Index (UI) | \n UI | \n UI = (SWIR2 - NIR) / (SWIR2 + NIR) | \n UI uses SWIR2 and NIR bands to determine urban density | \n
Green Chlorophyll Vegetation Index (GCVI) | \n GCVI | \n GCVI = (NIR/GREEN) − 1 | \n Used to estimate the content of leaf chlorophyll in various species of plants | \n
MERIS-based Terrestrial Chlorophyll Index (MTCI) | \n MTCI | \n MTCI = (NIR_Broad - Red_Edge_1) / ( NIR_Broad + Red ) | \n MTCI can be used to gauge chlorophyll content. | \n
Normalized Difference Red Edge (NDRE) | \n NDRE | \n NDRE = (NIR – Red_Edge_1) / (NIR + Red_Edge_1) | \n NDRE uses NIR and red edge bands to gauge late season plant health. Calculated using Red_Edge_1 based on wavelength used for NDRE calculation in this paper (Carisse et al 2010). | \n
Features can be isolated to stand out by loading different combinations of bands into the red, green, and blue channels. Read more here.
\nCombo Name | \nAPI Variable | \nFormula (R-G-B) | \nDescription | \n
---|---|---|---|
Traditional Color Infrared Image (CIR) | \nCIR | \nNIR - Red - Green | \nCombination of colors within the visible spectrum with addition of NIR light; useful for determining pigments in vegetation. | \n
Urban Environment (UE) | \nUE | \nSWIR2 - SWIR1 - Red | \nFalse Color useful for visualizing urban environments. | \n
Land and Water (LW) | \nLW | \nNIR - SWIR1 - Red | \nFalse Color good for picking out land from water. | \n
Atmospheric Penetration (AP) | \nAP | \nSWIR2 - NIR - Green | \nFalse color image with good atmospheric penetration. | \n
Agriculture (AGR) | \nAGR | \nSWIR1 - NIR - Blue | \nFalse color for visualizing agricultural activity. | \n
Forest Fire Burn Scars (FFBS) | \nFFBS | \nSWIR2 - NIR - Blue | \nFalse color often used for visualizing forest fire burn scars | \n
Bare Earth (BE) | \nBE | \nSWIR1 - Green - Blue | \nFalse color for distinguishing differences in bare earth. | \n
Vegetation and Water (VW) | \nVW | \nNIR - SWIR2 - Coastal Aerosol | \nFalse color for visualizing vegetation and water. | \n
Parameter | \nData Type | \nDescription | \n
---|---|---|
download_url | \nURL | \nURL to download result raster (.tif) file | \n
flattendtext | \n-- | \nAn array of Xcoords, Ycoords values from the .tif files. | \n
tiledate | \nDate (mm/dd/yyyy) | \nThe tile dates from where the band values are retrieved. | \n
tilenames | \n-- | \nList of the Blob names from the Azure Storage Container. | \n
features | \n-- | \nAn array of features from the database. | \n
features.attributes.CellSize | \nResolution | \nResolution of result Geotiff file in meters. | \n
features.attributes.CoordinateSystem | \n-- | \nCoordinate system of the result raster. | \n
features.attributes.Extent | \n-- | \nExtents of the result raster. | \n
features.attributes.Legend | \nList | \nLegend gives ranges of values for: Area: Area covered in % Count : # of pixels from the result raster in range CountAllPixels : Total # of pixels in result Max : Maximum value in range Min : Minimum value in range Mean : Mean value in range Color : Hex color used for value ranges | \n
features.attributes.Matrix | \nList | \nRows and Columns. | \n
features.attributes.Max | \nNumber | \nMaximum value from the result raster | \n
features.attributes.Min | \nNumber | \nMinimum value from the result raster | \n
features.attributes.Mean | \nNumber | \nAverage value from the result raster | \n
features.attributes.Percentile5 | \nNumber | \n5th percentile value from result raster | \n
features.attributes.Percentile95 | \nNumber | \n95th percentile value from result raster | \n
features.attributes.pngb64 | \nURL | \nbase64png image of the result raster with legend entries | \n
Acronyms and Definitions
\n \nAcronym | \nDescription | \n
---|---|
MSI | \nMulti-Spectral Instrument | \n
HLS | \nHarmonized Landsat and Sentinel-2 | \n
HDF | \nHierarchical Data Format | \n
NIR | \nNear-Infrared | \n
GLS | \nGlobal Land Survey | \n
BRDF | \nBidirectional Reflectance Distribution Function | \n
NBAR | \nNadir BRDF-normalized Reflectance | \n
OLI | \nOperational Land Imager | \n
QA | \nQuality assessment | \n
SWIR | \nShort-wave Infrared | \n
SDS | \nScientific Data Sets | \n
SR | \nSurface reflectance | \n
SZA | \nSun Zenith angle | \n
NDVI | \nNormalized Difference Vegetation Index | \n
UTM | \nUniversal Transverse Mercator | \n
WRS | \nWorldwide Reference System | \n
AOI Structure Examples
\n\n{\"geometryType\":\"esriGeometryPolygon\",\"features\":[{\"geometry\":{\"rings\":[[[-92.678953,41.741707],[-\n92.678966,41.740563],[-92.678972,41.739963],[-92.67896,41.738874],[-92.686062,41.738873],[-92.688546,41.738868],[-92.688544,41.739223],[-92.688555,41.743961],[-92.688124,41.743969],[-92.686658,41.744045],[-92.685481,41.74411],[-92.68513,41.744086],[-92.684627,41.743993],[-92.684352,41.743833],[-92.683972,41.743603],[-92.683789,41.743476],[-92.683333,41.742983],[-92.682923,41.742627],[-92.682497,41.742283],[-92.68213,41.742294],[-92.681444,41.742131],[-92.680101,41.741842],[-92.679444,41.741817],[-92.679094,41.741713],[-92.678953,41.741707]]],\"spatialReference\":{\"wkid\":4326}}}]}\n
{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[-93.998809,41.993243],[-93.99873,41.988358],[94.001444,41.98838],[-94.00144,41.989089],[-94.003556,41.989116],[-94.003571,41.991767],[94.002054,41.991735],[-94.002086,41.993278],[-93.998809,41.993243]]]},\"properties\":{\"OBJECTID\":2038888,\"CALCACRES\":44.63000107,\"CALCACRES2\":null} ,\"id\":2038888} \n
\n A Zip folder with following files [example.shp, example.prj, example.dbf, example.shx]
\nA GeoTiff file of ‘.tif’ extension
\nBands Information and Request Syntax
\nHLS spectral bands nomenclature
\n \nBand Name | \nOLI Band Number | \nMSI Band Number | \nHLS Band Code Name L30 | \nHLS Band Code Name S30 | \nL30 Subdataset Number | \nS30 Subdataset Number | \nWavelength (micrometers) | \n
---|---|---|---|---|---|---|---|
Coastal Aerosol | \n1 | \n1 | \nband01 | \nB01 | \n01 | \n01 | \n0.43 – 0.45* | \n
Blue | \n2 | \n2 | \nband02 | \nB02 | \n02 | \n02 | \n0.45 – 0.51* | \n
Green | \n3 | \n3 | \nband03 | \nB03 | \n03 | \n03 | \n0.53 – 0.59* | \n
Red | \n4 | \n4 | \nband04 | \nB04 | \n04 | \n04 | \n0.64 – 0.67* | \n
Red-Edge 1 | \n-- | \n5 | \n-- | \nB05 | \n-- | \n05 | \n0.69 – 0.71** | \n
Red-Edge 2 | \n-- | \n6 | \n-- | \nB06 | \n-- | \n06 | \n0.73 – 0.75** | \n
Red-Edge 3 | \n-- | \n7 | \n-- | \nB07 | \n-- | \n07 | \n0.77 – 0.79** | \n
NIR Broad | \n-- | \n8 | \n-- | \nB08 | \n-- | \n08 | \n0.78 –0.88** | \n
NIR Narrow | \n5 | \n8A | \nband05 | \nB8A | \n05 | \n09 | \n0.85 – 0.88* | \n
SWIR 1 | \n6 | \n11 | \nband06 | \nB11 | \n06 | \n12 | \n1.57 – 1.65* | \n
SWIR 2 | \n7 | \n12 | \nband07 | \nB12 | \n07 | \n13 | \n2.11 – 2.29* | \n
Water vapor | \n-- | \n9 | \n-- | \nB09 | \n-- | \n10 | \n0.93 – 0.95** | \n
Cirrus | \n9 | \n10 | \nband09 | \nB10 | \n08 | \n11 | \n1.36 – 1.38* | \n
TIRS1 (Thermal Infrared 1) | \n10 | \n-- | \nband10 | \n-- | \n09 | \n-- | \n10.60 – 11.19* | \n
TIRS2 (Thermal Infrared 2) | \n11 | \n-- | \nband11 | \n-- | \n10 | \n-- | \n11.50 – 12.51* | \n
QA | \n-- | \n-- | \n-- | \n-- | \n11 | \n14 | \n-- | \n
Projection Syntax and Example
\nProjection: Projection of a new resampled raster. It may take the following forms:
\nProjection Example:\n "urn:ogc:def:crs:EPSG::n"\n
\nRequest Examples – form-data and urlencoded
\n { \n Band: \"['NDVI']\" \n Enddate: \"3/8/2019\" \n Startdate: \"3/2/2019\" \n aoi: \"{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[-93.511545,42.071053],[93.511565,42.074566],[-93.50667,42.074588],[-93.501908,42.074559],[-93.501936,42.071045],[-\n93.511545,42.071053]]]},\"properties\":{\"OBJECTID\":3350330,\"CALCACRES\":77.09999847,\"CALCACRES2\":null},\"id\":3350330}\" \nlegendtype: \"Relative\" \nsatellite: \"Landsat\" \n} \n
\n aoi=%7B%22type%22%3A%22Feature%22%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B-101.02684%2C38.598114%5D%2C%5B-101.026842%2C38.597962%5D%2C%5B-101.026956%2C38.59093%5D%2C%5B-101.028768%2C38.590943%5D%2C%5B-101.029234%2C38.590946%5D%2C%5B-101.035523%2C38.590991%5D%2C%5B-101.035526%2C38.590991%5D%2C%5B-101.035564%2C38.590991%5D%2C%5B-101.035576%2C38.590991%5D%2C%5B-101.035595%2C38.590991%5D%2C%5B-101.035956%2C38.590994%5D%2C%5B-101.035974%2C38.591099%5D%2C%5B-101.035957%2C38.594349%5D%2C%5B-101.036017%2C38.598193%5D%2C%5B-101.035203%2C38.598193%5D%2C%5B-101.033665%2C38.598182%5D%2C%5B-101.031726%2C38.598158%5D%2C%5B-101.02684%2C38.598114%5D%5D%5D%7D%2C%22properties%22%3A%7B%22OBJECTID%22%3A8091992%2C%22CALCACRES%22%3A156.1000061%2C%22CALCACRES2%22%3Anull%7D%2C%22id%22%3A8091992%7D&satellite=Landsat%2CSentinel&Band=%5B'NDVI'%5D&filter=1&interpolate=1&showlatest=1&resolution=0.0001&statistics=1&Startdate=9%2F26%2F2019&Enddate=10%2F2%2F2019&legendtype=Relative\n
\n Parameter | \nDescription | \nExample | \nRequest | \n
---|---|---|---|
filename | \nFile name to download. From POST request. Only request a single file at a time. | \nraster_bandNDVI_date2019203-2019209_20190807_174457_1233.tif | \nhttps://ag-analytics.azure-api.net/harmonized-landsat-sentinel-service/?filename=raster_bandNDVI_date2019203-2019209_20190807_174457_1233.tif | \n