# info.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.

# paths./.post.description
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 DataLayers.

Documentation

Github Repo

Notebook

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.

Algorithm Flow ▼

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.

Request Parameters ▼

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

--

See "Band" Parameter Options Table

Provide the list of HLS Spectral band names to retrieve for given AOI. See Figures 3-4.

Startdate

Date

No

--

mm/dd/yyyy

• Landsat – data starts from 2013
• Sentinel – data starts from 2015

Enddate

Date

No

--

mm/dd/yyyy

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.

"Band" Parameter Options ▼

Band Information

API Variable

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.

NIR

Near Infrared (0.76-0.90µm)

Reflects healthy vegetation.

NIR_Broad

Near Infrared (.842 µm central)

Good for mapping shorelines and biomass content, as well as at detecting
and analyzing vegetation.

Red_Edge_1

Red Edge (.69 - .71µm)

Can gauge foliage chlorophyll, canopy area, and water content.
Applications include growth studies, precision ag, and vegetation productivity modeling.

Red_Edge_2

Red Edge (0.73 – 0.75 µm)

Can gauge foliage chlorophyll, canopy area, and water content

Red_edge_3

Red Edge (0.77 – 0.79 µm)

Can gauge foliage chlorophyll, canopy area, and water content

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.

Coastal Aerosol

Coastal Aerosol (0.43-0.45µm)

Reflects blues and violets.

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.

Index Information

Index Name

API Variable

Formula

Description

Normalized Difference
Vegetation Index (NDVI)

NDVI

NDVI = (NIR - Red) /
(NIR + Red)

NDVI is derived from readily available satellite imagery which is positively
correlated with green vegetation cover

Red-Green-Blue
(RGB)

RGB

Composite of red, green,
and blue bands.

Color imagery, how the human eye would view something.

Normalized Difference
Water Index (NDWI)

NDWI

NDWI = (NIR - SWIR) /
(NIR + SWIR)

NDWI uses the NIR and SWIR bands to determine changes in water content

Normalized Difference
Buildup Index (NDBI)

NDBI

NDBI = (SWIR1 - NIR) /
(SWIR1 + NIR)

NDBI uses SWIR1 and NIR bands to determine urban areas

Normalized Difference
Tillage Index (NDTI)

NDTI

NDTI = (SWIR1 - SWIR2) /
(SWIR1 + SWIR2)

Similarly, NDTI is also derived from satellite imagery but calculated with
different bands. It is positively correlated with crop residue cover

Urban Index (UI)

UI

UI = (SWIR2 - NIR) /
(SWIR2 + NIR)

UI uses SWIR2 and NIR bands to determine urban density

Green Chlorophyll
Vegetation Index (GCVI)

GCVI

GCVI = (NIR/GREEN) − 1

Used to estimate the content of leaf chlorophyll in various species of plants

MERIS-based Terrestrial
Chlorophyll Index (MTCI)

MTCI

MTCI = (NIR_Broad - Red_Edge_1) /
( NIR_Broad + Red )

MTCI can be used to gauge chlorophyll content.

Normalized Difference
Red Edge (NDRE)

NDRE

NDRE = (NIR – Red_Edge_1) /
(NIR + Red_Edge_1)

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).

Band Insertion Into RGB

Features can be isolated to stand out by loading different combinations of bands into the red, green, and blue channels. Read more here.

Combo Name

API Variable

Formula (R-G-B)

Description

Traditional Color Infrared Image (CIR)

CIR

NIR - Red - Green

Combination of colors within the visible spectrum with addition
of NIR light; useful for determining pigments in vegetation.

Urban Environment (UE)

UE

SWIR2 - SWIR1 - Red

False Color useful for visualizing urban environments.

Land and Water (LW)

LW

NIR - SWIR1 - Red

False Color good for picking out land from water.

Atmospheric Penetration (AP)

AP

SWIR2 - NIR - Green

False color image with good atmospheric penetration.

Agriculture (AGR)

AGR

SWIR1 - NIR - Blue

False color for visualizing agricultural activity.

Forest Fire Burn Scars (FFBS)

FFBS

SWIR2 - NIR - Blue

False color often used for visualizing forest fire burn scars

Bare Earth (BE)

BE

SWIR1 - Green - Blue

False color for distinguishing differences in bare earth.

Vegetation and Water (VW)

VW

NIR - SWIR2 - Coastal Aerosol

False color for visualizing vegetation and water.

Response Parameters ▼

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

Definitions and Examples ▼

Figure 1.

Acronyms and Definitions

Acronym

Description

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 L30

HLS Band Code Name S30

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

12

1.57 – 1.65*

SWIR 2

7

12

band07

B12

07

13

2.11 – 2.29*

Water vapor

--

9

--

B09

--

10

0.93 – 0.95**

Cirrus

9

10

band09

B10

08

11

1.36 – 1.38*

TIRS1 (Thermal Infrared 1)

10

--

band10

--

09

--

10.60 – 11.19*

TIRS2 (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&amp;satellite=Landsat%2CSentinel&amp;Band=%5B&#39;NDVI&#39;%5D&amp;filter=1&amp;interpolate=1&amp;showlatest=1&amp;resolution=0.0001&amp;statistics=1&amp;Startdate=9%2F26%2F2019&amp;Enddate=10%2F2%2F2019&amp;legendtype=Relative

# paths./.post.responses.200.content.application/json.example[].flattened_raster
Error: not possible calculate flattened raster

# paths./.post.responses.200.content.application/json.example[].flattened_raster
Error: not possible calculate flattened raster

# paths./.post.responses.200.content.application/json.example[].flattened_raster
Error: not possible calculate flattened raster

# paths./.get.description
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 DataLayers.

Documentation

Github Repo

Notebook

GET Request

Parameter | Description | Example | Request
filename | File name to download. From POST request. Only request a single file at a time. | raster_bandNDVI_date2019203-2019209_20190807_174457_1233.tif | https://ag-analytics.azure-api.net/harmonized-landsat-sentinel-service/?filename=raster_bandNDVI_date2019203-2019209_20190807_174457_1233.tif

# paths./.get.parameters[].description
enter the filename to download from post request.