Biodiversity

The /biodiversity API call implements a canopy height heterogeneity metric called the Rao's Q (Rocchini et al., 2021). It is based on this Earth Engine implementation of Rao's Q.

Key Datasets

The change detection algorithms implemented and datasets are the following:

1. GEDI LiDAR L2A footprints: GEDI LiDAR L4A footprints are used a way to characterize canopy height and their spatial heterogeneity. They measure footprint-level (25m radius) canopy height across landscapes. These are used to train a model to upscale canopy height estimates across supply bases and landscapes. They are available between 2018 and 2023 for most regions of the world, and ensure that a broad variety of temporal conditions are captured, enabling more robust predictions across space and time. The canopy height estimates provided at the footprint level by the GEDI L2A product is based on the 98th percentile of the returned waveform, used to approximate canopy height. It assumes that the 99th and 100th percentile are noisy and likely to over-estimate actual canopy height.

2. Dynamic World Probabilities: Dynamic World's (Brown et al., 2022) Probability time series are used in combination with Sentinel-2 red, red-edge, near-infrared and short-wave infrared bands, as well as Sentinel-1 VV and VH polarization bands, as inputs to train an Above-Ground Biomass (AGB) model. The reference data used to train the model are the GEDI LiDAR L4A footprints, described above. The Dynamic World probabilities are particularly helpful in providing land use transition context for predicting above-ground biomass.

3. Other Datasets: As more datasets become available in the form of reference data or covariates (e.g. commercial imagery offering), either due to outstanding performance according to state-of-the-art, or because regulations and enforcing agencies require specific datasets or approaches, Epoch will implement these as per required.

Key Considerations

See below a list of key considerations to keep in mind when using the /biodiversity endpoint:

1. The area calculations are weighted, which means that the exact proportion of overlapping pixels are accounted for in the reported non-compliance areas. This avoids over- and under-accounting issues.

2. The results are as consistent as the plot boundaries (geometries) provided! If the input geometries are approximate, they WILL pick up changes surrounding the plot, which may not be managed by the supply chain actor. Therefore it is of utmost importance that the geo-referenced plots used as inputs to this API call are as accurate as possible.

3. The thumbnail shows changes in and around the plot, but the reported values in the response ONLY report changes WITHIN the plot. The change data surrounding the plot itself is shown in the thumbnail for reference, and to highlight potential risks around the plots themselves. For a more comprehensive statistical comparison to a reference area (supply shed, watershed, administrative unit), the Batch API should be used.

4. The predictions derived from GEDI L2A footprints are only as accurate as the footprints themselves. The footprints' sources of uncertainty come from inaccuracies in the digital elevation model used, positional inaccuracies of the footprints' georeferencing, steepness of slope, etc. While we attempt to filter out low accuracy footprints, the models may still be trained on data that over- or under-estimates canopy height, which is why an independent validation using field-collected data is necessary to provide canopy height and associated biodiversity proxy information with adequate levels of confidence.

Parameters and Headers

A request to /biodiversity/ uses standard query parameters. Parameters that are hidden from the public OpenAPI schema are intentionally omitted here.

Parameter	Type	Required	Default	Description
geometry	string (WKT)	Yes	-	Input geometry (WKT).
area	float	No	4	Area in hectares when geometry is a POINT.
start_date	string	No	2017-01-01	Start date (YYYY-MM-DD).
date	string	No	today (UTC)	End date (YYYY-MM-DD).
thumbnail	bool	No	true	Whether to return a thumbnail.
map_tile	bool	No	true	Whether to return XYZ map tile URLs.

A typical example of a payload for the /biodiversity endpoint is the following:

request_data = {
    "geometry": 'POLYGON ((-7.342878 6.499998, -7.342797 6.50002, -7.341987 6.500143, -7.341905 6.500509, -7.342246 6.500702, -7.342434 6.500826, -7.343081 6.501174, -7.343646 6.500615, -7.343789 6.500092, -7.343771 6.500103, -7.343218 6.499953, -7.342933 6.499994, -7.342878 6.499998))',
    "start_date": "2017-01-01",
    "date": '2024-01-22',  # (1)!
    "thumbnail": True, # (2)!
    "map_tile": True # (3)!
}

1. Arbitrary default end date. If not specified, will take today's date
2. Whether you want to return a thumbnail
3. Whether you want dynamic XYZ map tiles to be returned

With the headers being:

headers = {'Authorization': "Bearer <authorization_token>",
           'accept': 'application/json'
}

The Authorization header must be replaced by your user token. Check this page for more information on how to authenticate.

Python

In python, you can submit a request in the following way:

import requests
import json

response = requests.get("https://epoch-sco2-api.com/biodiversity/", 
                        params=request_data, 
                        headers=headers)

json_result = json.loads(response.content)
print(json_result)

Javascript

const axios = require('axios');

axios.get('https://epoch-sco2-api.com/biodiversity/', {
    params: request_data,
    headers: headers,
})
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

Curl

curl -X GET "https://epoch-sco2-api.com/biodiversity/" \
-H "Authorization: Bearer <authorization_token>" \
-H "accept: application/json" \
--data-urlencode "geometry=POLYGON ((-7.342878 6.499998, -7.342797 6.50002, -7.341987 6.500143, -7.341905 6.500509, -7.342246 6.500702, -7.342434 6.500826, -7.343081 6.501174, -7.343646 6.500615, -7.343789 6.500092, -7.343771 6.500103, -7.343218 6.499953, -7.342933 6.499994, -7.342878 6.499998))" \
--data-urlencode "start_date=2017-01-01" \
--data-urlencode "date=2024-01-22" \
--data-urlencode "thumbnail=True" \
--data-urlencode "map_tile=True"

Response

The response looks like this:

response = {
    'annual_chm': { # (1)!
        'chm_m_mean_2017': 4.437673, 
        'chm_m_mean_2018': 6.018069, 
        'chm_m_mean_2019': 4.944337, 
        'chm_m_mean_2020': 4.439938, 
        'chm_m_mean_2021': 3.725569, 
        'chm_m_mean_2022': 3.888708, 
        'chm_m_mean_2023': 4.08119, 
        'chm_m_mean_2024': 4.454038, 
        'chm_m_mean_max': 10.294855, # (2)!
        'chm_m_stdDev_2017': 2.95142, # (3)!
        'chm_m_stdDev_2018': 2.71428, 
        'chm_m_stdDev_2019': 2.508556, 
        'chm_m_stdDev_2020': 2.359394, 
        'chm_m_stdDev_2021': 2.342605, 
        'chm_m_stdDev_2022': 2.919122, 
        'chm_m_stdDev_2023': 3.151483, 
        'chm_m_stdDev_2024': 3.045596, 
        'chm_m_stdDev_max': 3.151483 # (4)!
    }, 
    'diversity_score': 1.574091, # (5)!
    'diversity_uncertainty_sd': 0.10152, # (6)!
    'ingestion_date': '2024-08-09', # (7)!
    'monitoring_end': '2024-08-09', # (8)!
    'monitoring_start': '2017-01-01', # (9)!
    'thumbnail_url': 'https://storage.googleapis.com/sco2api-dump/biodiversity_20170101_5612505883515087_11232128722882334_20170101_20240809.png', # (10)!
    'uuid': '0x24513a81d2189dacb5eff3fe3b8323f38cdb4baa6500c0d42596002c1e12be0b', # (11)!
    'imagery_pre': 'https://earthengine.googleapis.com/v1/projects/epoch-geospatial/maps/6d9106b5cd1b18733533984553c1c541-ecde76c208d538b9553329d19f4d11ea/tiles/{z}/{x}/{y}', # (12)!
    'imagery_post': 'https://earthengine.googleapis.com/v1/projects/epoch-geospatial/maps/a1b2dbff851d4b7fac8c273fa09679c3-d3b142748b47e93439751d429d2efd60/tiles/{z}/{x}/{y}', # (13)!
    'diversity_map': 'https://earthengine.googleapis.com/v1/projects/epoch-geospatial/maps/ed28dafea756867463d797c39176365a-89f3651ecc1df48c45ec4f15669d0ba9/tiles/{z}/{x}/{y}', # (14)!
    'input_plot_area': 11.323003, # (15)!
    'input_plot_geom': 'POLYGON ((-50.415834 -10.035709, -50.416077 -10.03579, -50.416441 -10.035992, -50.416845 -10.036275, -50.417532 -10.0368, -50.417977 -10.037043, -50.418462 -10.037407, -50.419472 -10.038215, -50.419513 -10.038458, -50.419634 -10.038417, -50.419634 -10.038296, -50.419796 -10.038498, -50.419917 -10.038539, -50.42016 -10.039145, -50.420362 -10.040681, -50.420321 -10.040843, -50.42016 -10.040883, -50.420079 -10.040721, -50.419553 -10.040358, -50.419028 -10.040196, -50.418664 -10.039711, -50.418341 -10.039185, -50.418138 -10.038902, -50.417613 -10.038619, -50.416683 -10.038336, -50.415996 -10.038215, -50.415713 -10.037649, -50.415753 -10.035871, -50.415834 -10.035709))' # (16)!
}

1. Mean Canopy height in meter for the provided geometry, for a given year.
2. Mean canopy height potential in ton CO2-equivalent per hectare. This is a theoretical maximum which could be achieved at this location were it covered in mature, natural forest.
3. Canopy height standard deviation in meter for the provided geometry, for a given year.
4. Canopy height potential standard deviation in meter.
5. The Rao's Q diversity score. A value 0.5 is considered of low diversity (typically monocultures and plantation), while a value above 0.5 to 1 is considerate characteristic of a fragmented, biodiverse landscape.
6. Standard deviation for the biodiversity score at plot level
7. Date and timestamp of API call generation
8. End of monitoring period considered
9. Start of monitoring period considered
10. if thumbnail parameter is set to "true", the thumbnail URL generated, showing a before/after situation, alongside with the color-coded detections.
11. a uuid is generated, to ensure unique identification of the plot
12. The XYZ dynamic tile endpoint for an RGB satellite image corresponding to the monitoring_start timestamp
13. The XYZ dynamic tile endpoint for an RGB satellite image corresponding to the monitoring_end timestamp
14. The XYZ dynamic tile endpoint for the Rao's Q diversity score
15. The input plot area size (in hectare)
16. The original polygon geometry in WKT format

Thumbnail Interpretation

The above thumbnail is an example of what the /biodiversity endpoint returns if the thumbnail flag is set to true.

The top image is the situation at the start of the monitoring period, which defaults to 2016-01-01. The middle image is the situation at the end of the monitoring period, which defaults to the day the request is made. The image is always taken from the same time of the year in another year to the extent possible, as it ensures the season in which the images acquired are similar, making the vegetation conditions more comparable and the actual changes more visually appreciable.

The bottom image shows the Rao's Q diversity score generated by the API request. The color ramp stretches from blue to yellow, with the deeper blue being locations with lower canopy height heterogeneity, while the deeper yellow are locations that have gained the most above-ground biomass over the monitoring period. White pixels are intermediate values oscillating around 0.5, indicating medium diversity.