Harmonized Landsat Sentinel Service
API change historyThe 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.
The 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.

Harmonized Landsat Sentinel Data in Ag-Analytics® FarmScope.



Band and Indexes Formulas and Explanation
Band | Definition | Description |
---|---|---|
Red | Red (0.64-0.67µm) | Reflects reds, such as tropical soils or rust-like soils. |
Green | Green (0.53-0.59µm) | Reflects greens, particularly leaf surfaces. |
Blue | Blue (0.45-0.51µm) | Reflects blues, particularly helpful for deep waters. |
Coastal Aerosol | Coastal Aerosol (0.43-0.45µm) | Reflects blues and violets. |
NIR | Near Infrared (0.76-0.90µm) | Reflects healthy vegetation. |
NIR B08 | Near Infrared (.842 µm central) | Good for mapping shorelines and biomass content, as well as at detecting and analyzing vegetation. |
NIR B8A | Near Infrared (.865 µm central) | For classifying vegetation. |
SWIR1 | Short-wave Infrared (1.57-1.65µm) | Sensitive to moisture content. Assists in distinguishing between dry and wet soils and vegetation. |
SWIR2 | Short-wave Infrared 2 (2.08-2.35µm) | Used in imaging soil types, geological features, and minerals. Sensitive to vegetation and soil moisture variations. |
RE 1, 2, & 3 | Red Edge (.68 - .73µm) | Can gauge foliage chlorophyll, canopy area, and water content. Applications include growth studies, precision ag, and vegetation productivity modeling. |
QA | Quality Assessment | Provides useful information for optimizing the value of pixels, identifying which pixels may be affected by surface conditions, clouds, or sensor conditions. |
NDVI | Normalized Difference Vegetation Index | Quantifies vegetation by measuring the difference between NIR and red light - healthy vegetation reflects as green, unhealthy as red. |
RGB | Red-green-blue | Composite of red, green, and blue bands. |
NDWI | Normalized Difference Water Index | Sensitive to the change in the water content of leaves. |
NDBI | Normalized Difference Built-Up Index | Highlights urban areas where there is a higher reflectance in the SWIR region, compared to the NIR region. |
NDTI | Normalized Difference Thermal Index | Used to distinguish between pavements and rooftops in more urban areas. |
NDRE | Normalized Difference Red Edge | NDRE is a better marker of plant conditions than NDVI for middle and late season crops that have already accumulated a large amount of chlorophyll. |
UI | Urban Index | Determines urban density through inverse relationship between NIR and SWIR. |
CIR | Color Infrared | Combination of colors within the visible spectrum with addition of NIR light; useful for determining pigments in vegetation. |
Normalized Difference Vegetation Index (NDVI)
NDVI is derived from readily available satellite imagery which is positively correlated with green vegetation cover.
Formula: NDVI = (NIR - Red) / (NIR + Red)
Normalized Difference Tillage Index (NDTI)
Similarly, NDTI is also derived from satellite imagery but calculated with different bands. It is positively correlated with crop residue cover.
Formula: NDTI= (SWIR1 - SWIR2) / (SWIR1 + SWIR2)
Normalized Difference Water Index (NDWI)
NDWI uses the NIR and SWIR bands to determine changes in water content.
Formula: NDWI = (NIR - SWIR) / (NIR + SWIR)
Normalized Difference Build-up Index (NDBI)
NDBI uses SWIR1 and NIR bands to determine urban areas.
Formula: NDBI= (SWIR1 - NIR) / (SWIR1 + NIR)
Urban Index (UI)
UI uses SWIR2 and NIR bands to determine urban density.
Formula: UI= (SWIR2 - NIR) / (SWIR2 + NIR)
General Flow of Service
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.
General Algorithm Flow
- Determine the AOI polygon given.
**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.
- Identify the corresponding satellite imageries based on the AOI, acquisition date, interpolation parameters, and other options passed by users.
- The satellite imageries will then be clipped to the AOI. If the imageries from the same date overlay with each other on the AOI, the mean of the overlay area will be returned and merged with the area without overlay from each imagery.
- The imageries of the AOI will then be mosaiced to get weekly average imageries.
- (**) If the interpolation option is chosen, the selected interpolation method and parameters will be applied to each weekly imagery where has cloud cover.
(**when interpolation is chosen)
Interpolation Function
Due 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.
To 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.
Interpolation Algorithm Flow
- Identify the missing parts of the image and find the contours of each gap.
- Find the best candidates from similar sequences of images which have non-missing pixels to fill the largest part of a given gap.
- Define an outline – a thin curve around each gap, then used for obtaining the linear transformation of the pixel intensity between the two images for each of the best candidates. The candidate image with the best linear fit of the outline is chosen.
- To better-fit the area close to the outline, an intensity correction mask is then created by blurring the patch-intensity difference image.
- The mask is applied to the gap area on the best candidate and generates an inpainted patch.
- Finally, this inpainted patch is used to fill the gap in the image.
API Specifications
Request Parameters
Parameter | Data Type | Required? | Default | Options | Description |
---|---|---|---|---|---|
AOI | Geometry, file/text | Yes | - | JSON, GEOJSON, Shapefile, Raster | See Fig. 2 for further explanation. |
Band | List | Yes | - | Red, Green, Blue, Coastal Aerosol, NIR, SWIR1, SWIR2, QA, NDVI, RGB, NDWI, NDBI, NDTI, UI, CIR, UE, LW, AP, AGR, FFBS, BE, VW | Provide the list of HLS Spectral band names to retrieve for given AOI. See Figures 3-4. |
Startdate | Date, mm/dd/yyyy | No | - | - | • Landsat – data starts from 2013 •Sentinel – data starts from 2015 |
Enddate | Date, mm/dd/yyyy | No | - | - | In the absence of startdate or enddate, or both, the service retrieves the latest information available on the land. |
byweek | Int, boolean | No | 1 | 1, 0 | If set to 1, result raster will be the mosaic of all the tiles in a particular week for a given satellite |
satellite | text | No | Landsat | Landsat, Sentinel | If set to both Landsat, Sentinel then the result raster will be the mosaic of both satellites for the given dates |
showlatest | Int, boolean | No | 1 | - | If startdate or enddate is not given, shows the latest available tile. |
filter | Int, boolean | No | 0 | 0, 1 | If set to 1, returns the response which is cloud-free after mosaic. |
qafilter | Int, boolean | No | 0 | 0, 1 | If set to 1, continues to filter tiles until the invalid pixels are < qacloudperc |
qacloudperc | float | No | 100 | 0-100 | This parameter comes to action with qafilter. If qafilter parameter is 1, then filters the tiles until the invalid pixels in those are < qacloudperc |
displaynormalvalues | float | No | 2000 | - | This parameter is used to normalize the band values for display purposes. Used for bands like RGB, AGR, etc. |
legendtype | text | No | Relative | Relative, Absolute | Legend type of display ranges of resulting response. |
resolution | float | No | 0.0001 | - | Cellsize in meters. |
flatten_data | Int, boolean | No | 0 | 0, 1 | Flatten data which has a list of Xcoord, Ycoord and Values for each band in the output. If 1, flatten_data is returned. |
statistics | Int, boolean | No | 1 | 0, 1 | Returns statistical features of the output .tif file. |
return_tif | int | No | 1 | 0, 1 | Returns the downloadable link to output raster. If 0, link will not be returned. |
projection | text | No | Projection of AOI Given | See Figure 5. | Enter the desired projection for the result raster. See Figure 5 for details. |
Response Parameters
Parameter | Data Type | Description |
---|---|---|
download_url | URL | URL to download result raster (.tif) file |
flattendtext | - | An array of Xcoords, Ycoords values from the .tif files. |
tiledate | Date (mm/dd/yyyy) | The tile dates from where the band values are retrieved. |
tilenames | - | List of the Blob names from the Azure Storage Container. |
features | - | An array of features from the database. |
features.attributes.CellSize | Resolution | Resolution of result Geotiff file in meters. |
features.attributes.CoordinateSystem | - | Coordinate system of the result raster. |
features.attributes.Extent | - | Extents of the result raster. |
features.attributes.Legend | List | Legend 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 |
features.attributes.Matrix | List | Rows and Columns. |
features.attributes.Max | Number | Maximum value from the result raster |
features.attributes.Min | Number | Minimum value from the result raster |
features.attributes.Mean | Number | Average value from the result raster |
features.attributes.Percentile5 | Number | 5th percentile value from result raster |
features.attributes.Percentile95 | Number | 95th percentile value from result raster |
features.attributes.pngb64 | URL | base64png image of the result raster with legend entries |
Figure 1.
Acronyms and Definitions
Acronym | Definition |
---|---|
MSI | Multi-Spectral Instrument |
HLS | Harmonized Landsat and Sentinel-2 |
HDF | Hierarchical Data Format |
NIR | Near-Infrared |
GLS | Global Land Survey |
BRDF | Bidirectional Reflectance Distribution Function |
NBAR | Nadir BRDF-normalized Reflectance |
OLI | Operational Land Imager |
QA | Quality assessment |
SWIR | Short-wave Infrared |
SDS | Scientific Data Sets |
SR | Surface reflectance |
SZA | Sun Zenith angle |
NDVI | Normalized Difference Vegetation Index |
UTM | Universal Transverse Mercator |
WRS | Worldwide Reference System |
Figure 2.
AOI Structure Examples
JSON Example
{"geometryType":"esriGeometryPolygon","features":[{"geometry":{"rings":[[[-92.678953,41.741707],[-
92.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}}}]}
GEOJSON Example
{"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}
Shapefile Example
A Zip folder with following files [example.shp, example.prj, example.dbf, example.shx]
Raster Example
A GeoTiff file of ‘.tif’ extension
Figure 3.
Bands Information and Request Syntax
Figure 3.
HLS spectral bands nomenclature
Band name | OLI band number | MSI band number | HLS band code name L8 | HLS band code name S2 | L30** Subdataset number ** | S30 **Subdataset number** | Wavelength (micrometers) |
---|---|---|---|---|---|---|---|
Coastal Aerosol | 1 | 1 | band01 | B01 | 01 | 01 | 0.43 – 0.45* |
Blue | 2 | 2 | band02 | B02 | 02 | 02 | 0.45 – 0.51* |
Green | 3 | 3 | band03 | B03 | 03 | 03 | 0.53 – 0.59* |
Red | 4 | 4 | band04 | B04 | 04 | 04 | 0.64 – 0.67* |
Red-Edge 1 | 5 | B05 | 05 | 0.69 – 0.71** | |||
Red-Edge 2 | 6 | B06 | 06 | 0.73 – 0.75** | |||
Red-Edge 3 | 7 | B07 | 07 | 0.77 – 0.79** | |||
NIR Broad | 8 | B08 | 08 | 0.78 –0.88** | |||
NIR Narrow | 5 | 8A | band05 | B8A | 05 | 09 | 0.85 – 0.88* |
SWIR 1 | 6 | 11 | band06 | B11 | 06 | 10 | 1.57 – 1.65* |
SWIR 2 | 7 | 12 | band07 | B12 | 07 | 11 | 2.11 – 2.29* |
Water vapor | 9 | B09 | 12 | 0.93 – 0.95** | |||
Cirrus | 9 | 10 | band09 | B10 | 08 | 13 | 1.36 – 1.38* |
Thermal Infrared 1 | 10 | band10 | 09 | 10.60 – 11.19* | |||
Thermal Infrared 2 | 11 | band11 | 10 | 11.50 – 12.51* | |||
QA | 11 | 14 |
Figure 4
Projection Syntax and Example
Projection Syntax
Projection: Projection of a new resampled raster. It may take the following forms:
- Well Known Text definition
- "EPSG:n"
- "EPSGA:n"
- "AUTO:proj_id,unit_id,lon0,lat0" - WMS auto projections
- "urn:ogc:def:crs:EPSG::n" - ogc urns
- PROJ.4 definitions
- 6.__well known name, such as NAD27, NAD83, WGS84 or WGS72
- 7.__"IGNF:xxxx", "ESRI:xxxx", etc. definitions from the PROJ database
Projection Example: "urn:ogc:def:crs:EPSG::n"
Figure 5
Request Examples – form-data and urlencoded
form-data
application/json
{
Band: "['NDVI']"
Enddate: "3/8/2019"
Startdate: "3/2/2019"
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],[-
93.511545,42.071053]]]},"properties":{"OBJECTID":3350330,"CALCACRES":77.09999847,"CALCACRES2":null},"id":3350330}"
legendtype: "Relative"
satellite: "Landsat"
}
application/x-www-form-urlencoded
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
References
Claverie, M., Ju, J., Masek, J. G., Dungan, J. L., Vermote, E. F., Roger, J.-C., Skakun, S. V., & Justice, C. (2018). The Harmonized Landsat and Sentinel-2 surface reflectance data set. Remote Sensing of Environment, 219, 145-161. (https://doi.org/10.1016/j.rse.2018.09.002).
Get HLS Service
The 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.
The 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.

Harmonized Landsat Sentinel Data in Ag-Analytics® FarmScope.


Request
Request URL
Request parameters
-
enter the filename to download from post request