Zonal Statistics

The Zonal Statistics endpoints are used to generate statistics for Climate Engine datasets over different geometries.
There are four groups of Zonal Statistics endpoints:
/zonal_stats/pixel_count - The pixel count endpoints produce statistics and time series statistics on the number of pixels in each drought category for polygons or an Earth Engine FeatureCollection.
/zonal_stats/dynamic_dataset - The dynamic_dataset endpoints computes temporal statistics which are reduced over specified geometric features.
/zonal_stats/static_dataset - The static_dataset endpoints return values for static datasets (no time dependence) over different specified geometries.
/zonal_stats/group_by - The group by endpoints generate summaries (mean, sum, etc.) for user defined categories within the user defined polygon(s).
NOTES:
- Static datasets are “WRC”, “EH”, “CDOUTLOOOK”, “USDOUTLOOK”
- The /zonal_stats/pixel_count/timeseries endpoints are restricted to one feature (i.e. one polygon, custom asset, or Climate Engine asset).
/zonal_stats/pixel_count/coordinates
/zonal_stats/pixel_count/feature_collection
/zonal_stats/pixel_count/timeseries/coordinates
/zonal_stats/pixel_count/timeseries/feature_collection
/zonal_stats/static_dataset/coordinates
/zonal_stats/static_dataset/feature_collection
/zonal_stats/temporal_dataset/coordinates
/zonal_stats/temporal_dataset/feature_collection
/zonal_stats/group_by/coordinates
/zonal_stats/group_by/feature_collection

/zonal_stats/pixel_count/coordinates

Computes number of pixels in each drought category for polygons.
Returns: json

Resource url example:

/zonal_stats/pixel_count/coordinates?dataset=GRIDMET_DROUGHT&variable=spi180d&bins=[0,40,80,120,160,200,240,280,320,360,400]&end_date=2000-12-30&coordinates=[[[-121.61,38.78], [-121.52,38.78],[-121.52,38.83],[-121.61,38.83],[-121.61,38.78]]]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

coordinates

yes

list of lon, lat pairs of polygon vertices, see https://support.climateengine.org/article/152-formatting-coordinates-for-api-requests

[[[-121.61, 38.78], [-121.52, 38.78],[-121.52, 38.83],[-121.61, 38.83],[-121.61, 38.78]]]

buffer

no

List of integer buffers (meters) to be applied to each geometry

[400]

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

bins

no

Bins for the pixel count, currently limited to 10 values

-2, -1.5, -1.2, -0.7, -0.5, 0.5, 0.7, 1.2, 1.5, 2

end_date

yes

2019-12-31

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/pixel_count/feature_collection

Computes number of pixels in each drought category for the features of an Earth Engine FeatureCollection.
Permissions on custom asset must be such that it is readable by anyone.
Returns: json

Resource url example:

/zonal_stats/pixel_count/feature_collection?dataset=GRIDMET_DROUGHT&variable=spei2y&bins=[0,40,80,120,160,200,240,280,320,360,400]&end_date=2000-12-30&feature_collection_asset_id=USGS/WBD/2017/HUC08&sub_choices=["Animas"]&filter_by=name

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

feature_collection_asset_id

yes

EE FeatureCollection asset id, must have “Anyone can read” permissions

projects/climate-engine/featureCollections/shp_simplified/ClimateEngine_US_States

filter_by

no

Key name of property in feature collection (GIS users: this is the attribute name)

Name

sub_choices

no

Values of property in feature collection

Idaho, Nevada

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

bins

no

Bins for the pixel count, currently limited to 10 values

-2, -1.5, -1.2, -0.7, -0.5, 0.5, 0.7, 1.2, 1.5, 2

end_date

yes

2019-12-31

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/pixel_count/timeseries/coordinates

Computes timeseries of a number of pixels in each drought category for polygons.
Note: endpoint will only process one polygon at a time.
Returns: json

Resource url example:

/zonal_stats/pixel_count/timeseries/polygon?dataset=GRIDMET_DROUGHT&variable=spi180d&bins=[0,40,80,120,160,200,240,280,320,360,400]&start_date=2019-06-01&end_date=2000-12-30&coordinates=[[-121.61,38.78], [-121.52,38.78],[-121.52,38.83],[-121.61,38.83],[-121.61,38.78]]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

coordinates

yes

lon, lat pairs of polygon vertices, see https://support.climateengine.org/article/152-formatting-coordinates-for-api-requests

[[-121.61, 38.78], [-121.52, 38.78],[-121.52, 38.83],[-121.61, 38.83],[-121.61, 38.78]]

buffer

no

Integer buffers (meters) to be applied to geometry

[400]

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

bins

no

Bins for the pixel count, currently limited to 10 values

-2, -1.5, -1.2, -0.7, -0.5, 0.5, 0.7, 1.2, 1.5, 2

start_date

yes

2019-01-01

end_date

yes

2019-12-31

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/pixel_count/timeseries/feature_collection

Computes timeseries of a number of pixels in each drought category for the features of an Earth Engine FeatureCollection.
Permissions on custom asset must be such that it is readable by anyone.
Returns: json

Resource url example:

/zonal_stats/pixel_count/timeseries/feature_collection?dataset=GRIDMET_DROUGHT&variable=spei2y&bins=[0,40,80,120,160,200,240,280,320,360,400]&start_date=2019-06-01&end_date=2000-12-30&feature_collection_asset_id=USGS/WBD/2017/HUC08&sub_choices=["Animas"]&filter_by=name

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

feature_collection_asset_id

yes

EE FeatureCollection asset id, must have “Anyone can read” permissions

projects/climate-engine/featureCollections /shp_simplified/ClimateEngine_US_States

filter_by

yes

Key name of property in feature collection (GIS users: this is the attribute name)

Name

sub_choices

yes

Values of property in feature collection

Idaho, Nevada

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

bins

no

Bins for the pixel count, currently limited to 10 values

-2, -1.5, -1.2, -0.7, -0.5, 0.5, 0.7, 1.2, 1.5, 2

start_date

yes

2019-01-01

end_date

yes

2019-12-31

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/static_dataset/coordinates

Returns static values for provided points or polygons.
The values are reduced over the pixels lying within each polygon using the area_reducer parameter.
Returns: json

Resource url example:

zonal_stats/static_dataset/coordinates?dataset=WRC&variable=FLEP8&coordinates=%5B%5B%5B-160.56%2C61.25%5D%2C%20%5B-159.85%2C61.25%5D%2C%5B-159.85%2C61.46%5D%2C%20%5B-160.56%2C61.46%5D%2C%20%5B-160.56%2C61.25%5D%5D%5D&area_reducer=mean

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

coordinates

yes

lon, lat pairs of points or polygon vertices, see https://support.climateengine.org/article/152-formatting-coordinates-for-api-requests

[[-121.61, 38.78], [-121.52, 38.78],[-121.52, 38.83],[-121.61, 38.83],[-121.61, 38.78]]

buffer

no

Buffer (in meters) to apply to each geometry

[400]

area_reducer

yes

Statistic over region

mean

mean, median, min, max, stdev, count, count_un, skew, kurtosis, percentile_5, percentile_10, percentile_25, percentile_75, percentile_90, percentile_95

dataset

yes

WRC

variable

yes

FLEP8

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/static_dataset/feature_collection

Returns static values for the features of an Earth Engine FeatureCollection.
Valid (time-independent) datasets: WRC, EH, CDOUTLOOOK, USDOUTLOOK.
The values are reduced over the pixels lying within each feature using the area_reducer parameter.
Permissions on custom asset must be such that it is readable by anyone.
Returns: json

Resource url example:

zonal_stats/static_dataset/feature_collection?dataset=WRC&variable=BP&feature_collection_asset_id=projects%2Fclimate-engine%2FfeatureCollections%2Fshp_orig%2FClimateEngine_US_Climate_Divisions_plus_AK&sub_choices=%5B%22NY%20-%20YATES%22%5D&filter_by=Name&area_reducer=mean

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

feature_collection_asset_id

yes

EE FeatureCollection asset id, must have “Anyone can read” permissions

projects/climate-engine/featureCollections/shp_orig/ClimateEngine_US_Climate_Divisions_plus_AK

sub_choices

no

Select features, if not specified all feature data will be returned

[“NY - YATES”]

filter_by

no

Name

buffer

no

Buffer (in meters) to be applied to each geometry

[400]

area_reducer

yes

Statistic over region

mean

mean, median, min, max, stdev, count, count_un, skew, kurtosis, percentile_5, percentile_10, percentile_25, percentile_75, percentile_90, percentile_95

dataset

yes

WRC

variable

yes

BP

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/temporal_dataset/coordinates

Computes temporal statistics for polygons.
The values are averaged over the pixels lying within each polygon.
Permissions on custom asset must be such that it is readable by anyone.
Returns: json

Resource url example:

/zonal_stats/temporal_dataset/coordinates?dataset=PRISM&variable=tmin&temporal_statistic=min&start_date=2014-01-01&end_date=2014-01-31&coordinates=[[[-121.61,38.78], [-121.52,38.78],[-121.52,38.83],[-121.61,38.83],[-121.61,38.78]]]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

coordinates

yes

lon, lat pairs of polygon vertices, see https://support.climateengine.org/article/152-formatting-coordinates-for-api-requests

[[-121.61, 38.78], [-121.52, 38.78],[-121.52, 38.83],[-121.61, 38.83],[-121.61, 38.78]]

buffer

no

List of integer buffers (meters) to be applied to each geometry

[400]

area_reducer

yes

Statistic over region

mean

mean, median, min, max, stdev, count, count_un, skew, kurtosis, percentile_5, percentile_10, percentile_25, percentile_75, percentile_90, percentile_95

dataset

yes

GRIDMET

variable

yes

tmmx

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

start_date

yes

2019-01-01

end_date

yes

2019-12-31

temporal_statistic

yes

mean, median, max, min, total

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/temporal_dataset/feature_collection

Computes temporal statistics for the features of an Earth Engine FeatureCollection.
The values are averaged over the pixels lying within each feature.
Permissions on custom asset must be such that it is readable by anyone.
Returns: json

Resource url example:

/zonal_stats/temporal_dataset/feature_collection?dataset=LANDSAT_TOA&variable=EVI&temporal_statistic=mean&start_date=2014-07-01&end_date=2014-08-31&feature_collection_asset_id=USGS/WBD/2017/HUC08&sub_choices=["Animas"]&filter_by=name

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

feature_collection_asset_id

yes

EE FeatureCollection asset id, must have “Anyone can read” permissions

projects/climate-engine/featureCollections/shp_simplified/ClimateEngine_US_States

filter_by

no

Key name of property in feature collection (GIS users: this is the attribute name)

Name

sub_choices

no

Values of property in feature collection

Idaho, Nevada

area_reducer

yes

Statistic over region

mean

mean, median, min, max, stdev, count, count_un, skew, kurtosis, percentile_5, percentile_10, percentile_25, percentile_75, percentile_90, percentile_95

dataset

yes

GRIDMET

variable

yes

tmmx

mask_image_id

no

Image mask ID

mask_band

no

Mask band

mask_value

no

Image mask value

start_date

yes

2019-01-01

end_date

yes

2019-12-31

temporal_statistic

yes

mean, median, max, min, total

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/group_by/coordinates

Returns summaries (mean, sum, etc.) for user defined categories within the user defined polygons.

To export to google cloud storage bucket, you must give the Climate Engine google service account (climate-engine-pro-gcp@climate-engine-pro.iam.gserviceaccount.com) the Storage Object Creator role in your bucket permissions.

Returns: json

Resource url example:

zonal_stats/groupby/coordinates?

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

coordinates

yes

List of lon,lat pairs of polygon vertices, see https://support.climateengine.org/article/152-formatting-coordinates-for-api-requests

[[[-122.06, 39.16], [-122.06, 37.76], [-120.45, 37.76], [-120.45, 39.16]]]

[[[-126.03,23.89], [-66.45,23.89], [-66.45,49.73], [-126.03,49.73]]]

buffer

no

List of integer buffers (meters) to be applied to each geometry.

[100]

area_reducer

yes

Statistic over region

mean

mean, median, min, max, sum

group_img_id

yes

Earth engine asset or google cloud storage uri that you want to group by

GRIDMET/DROUGHT/20200105

projects/climate-engine/usdm/weekly/20000808_conus

group_band

yes

Band Name in group_img_id

spi1y

spi5y

group_img_type

yes

Continuous or Discrete

continuous

discrete, continuous

summary_img_id

yes

Earth engine asset or google cloud storage uri that you want to summarize using the group_img_id values

CIESIN/GPWv411/GPW_Population_Count/gpw_v4_population_count_rev11_2020_30_sec

CIESIN/GPWv411/GPW_Population_Count/gpw_v4_population_count_rev11_2020_30_sec

summary_band

yes

Image band to use

population_count

population_count

mask_image_id

no

Image mask ID for the Summary Image

mask_band

no

Image mask band for the Summary Image

mask_value

no

Image mask value for the Summary Image

bins

yes

If continuous, bin values for grouped summaries. If discrete, choose values to summarize for.

[-2.5, -2, -1.5, -1, -0.5, 0.5, 1, 1.5, 2, 2.5]

[3,4] or [0] or [-2.5, 0, 2.5]

scale_img

no

Choose what image to base reduce scale.

Defaults to smallest scale image.

group_img_id, summary_img_id

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json

/zonal_stats/group_by/feature_collection

Returns summaries (mean, sum, etc.) for user defined categories within the features of an Earth Engine FeatureCollection.

To export to google cloud storage bucket, you must give the Climate Engine google service account (climate-engine-pro-gcp@climate-engine-pro.iam.gserviceaccount.com) the Storage Object Creator role in your bucket permissions.

Returns: json

Resource url example:

zonal_stats/group_by/feature_collection?

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

feature_collection_asset_id

yes

EE FeatureCollection asset id, must have “Anyone can read” permissions

projects/earthengine-legacy/assets/projects/climate-engine/featureCollections/shp_simplified/ClimateEngine_US_States

projects/earthengine-legacy/assets/projects/climate-engine/featureCollections/shp_simplified/ClimateEngine_US_States

sub_choices

no

List of features to use in analysis. must be strings.

Iowa

filter_by

no

Property name to filter sub-choices.

Name

buffer

no

List of integer buffers (meters) to be applied to each geometry.

[100]

area_reducer

yes

Statistic over region

mean

mean, median, min, max, sum

group_img_id

yes

Earth engine asset or google cloud storage uri that you want to group by

GRIDMET/DROUGHT/20200105

projects/climate-engine/usdm/weekly/20000808_conus

group_band

yes

Band Name in group_img_id

spi1y

spi5y

group_img_type

yes

Continuous or Discrete

continuous

discrete, continuous

summary_img_id

yes

Earth engine asset or google cloud storage uri that you want to summarize using the group_img_id values

CIESIN/GPWv411/GPW_Population_Count/gpw_v4_population_count_rev11_2020_30_sec

CIESIN/GPWv411/GPW_Population_Count/gpw_v4_population_count_rev11_2020_30_sec

summary_band

yes

Image band to use

population_count

population_count

mask_image_id

no

Image mask ID for the Summary Image

mask_band

no

Image mask band for the Summary Image

mask_value

no

Image mask value for the Summary Image

bins

yes

If continuous, bin values for grouped summaries. If discrete, choose values to summarize for.

[-2.5, -2, -1.5, -1, -0.5, 0.5, 1, 1.5, 2, 2.5]

[3,4] or [0] or [-2.5, 0, 2.5]

scale_img

no

Choose what image to base reduce scale.

Defaults to smallest scale image.

group_img_id, summary_img_id

export_path

no

Export CSV results to a Google cloud storage bucket (must have correct permissions)

climate-engine-public/my_csv_file.csv

export_format

no

File format of export

json

csv, json