Whenever users are searching for imagery via API, it makes sense to include a filter for cloud cover. There are several metadata fields that can be used for this task. Please find an overview down below.
This article is based on the following documentation:
The standard metadata field is 'cloud_cover'. 'cloud_cover' only takes the amount of clouds into account, which means light or heavy haze, shadow and snow will not be counted towards this ratio. 'cloud_cover' is not based on udm2 cloud masks, but udm cloud masks.
There are more cloud related metadata fields users can use to filter data. The ones below are all based on udm2 cloud masks.
'cloud_percent' is defined by: Percent of cloud values in dataset. Cloud values represent scene content areas (non-blackfilled) that contain opaque clouds which prevent reliable interpretation of the land cover content.
This means, 'cloud_percent' also takes into account the amount of haze, snow and cloud shadow that can be present in a product.
It is basically the opposite of the metadata field 'clear_percent', which is defined as: Percent of clear values in a dataset. Clear values represents scene content areas (non-blackfilled) that are deemed to be not impacted by cloud, haze, shadow and/or snow.
There are also specific fields for haze, 'heavy_haze_percent' and 'light_haze_percent', as well as a field for cloud shadow, 'shadow_percent' and a metadata field for snow and ice, 'snow_ice_percent'.
So if users would like to avoid haze, cloud shadow or snow and ice in the imagery they order, they can use 'cloud_percent' instead of 'cloud_cover' for filtering data.