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 and custom assets.
/zonal_stats/values - The values endpoints computes temporal statistics which are reduced over specified geometric features.
/zonal_stats/value - The value 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:
- The “value” endpoints are restricted to static datasets (such as EH and WRC).
- Additionally, 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/climate_engine_asset

Computes number of pixels in each drought category for the features of a Climate Engine feature collection asset.
For a list of available county assets use /metadata/county_names endpoint.
Returns: json

Resource url example:

/zonal_stats/pixel_count/climate_engine_asset?dataset=GRIDMET_DROUGHT&variable=spi180d&bins=[0,40,80,120,160,200,240,280,320,360,400]&end_date=2000-12-30&region=states&sub_choices=["Nevada"]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

end_date

yes

2019-12-31

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

feature_collection

yes

Feature collection name, see list of available assets

states

sub_choices

no

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

CA, NV

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/custom_asset

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

Resource url example:

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

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

end_date

yes

2019-12-31

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

asset_id

yes

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

‘projects/climate-engine/featureCollections /shp_simplified/ClimateEngine_US_Counties’

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

CA, NV

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/polygons

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

Resource url example:

/zonal_stats/pixel_count/polygons?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

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

end_date

yes

2019-12-31

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

coordinates

yes

list of lon, lat pairs of polygon vertices

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

buffers

no

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

[400]

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/climate_engine_asset

Computes timeseries of a number of pixels in each drought category for the features of a Climate Engine feature collection asset.
For a list of available county assets use /metadata/county_names endpoint.
Returns: json

Resource url example:

/zonal_stats/pixel_count/timeseries/climate_engine_asset?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&region=states&sub_choices=["Nevada"]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

start_date

yes

2019-01-01

end_date

yes

2019-12-31

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

feature_collection

yes

Feature collection name, see list of available assets

states

sub_choices

yes

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

CA, NV

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/custom_asset

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

Resource url example:

/zonal_stats/pixel_count/timeseries/custom_asset?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&asset_id=USGS/WBD/2017/HUC08&sub_choices=["Animas"]&filter_by=name

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

start_date

yes

2019-01-01

end_date

yes

2019-12-31

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

asset_id

yes

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

‘projects/climate-engine/featureCollections /shp_simplified/ClimateEngine_US_Counties’

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

CA, NV

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/polygon

Computes timeseries of a number of pixels in each drought category for polygon.
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

dataset

yes

GRIDMET_DROUGHT

variable

yes

spi180d

start_date

yes

2019-01-01

end_date

yes

2019-12-31

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

coordinates

yes

lon, lat pairs of polygon vertices

[[-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]

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/values/climate_engine_asset

Computes temporal statistics for the features of a Climate Engine feature collection asset.
The values are averaged over the pixels lying within the feature.
For a list of available assets see the Climate Engine Assets section.
Returns: json

Resource url example:

/zonal_stats/values/climate_engine_asset?dataset=GRIDMET&variable=tmmn&temporal_statistic=median&start_date=2014-01-01&end_date=2018-12-30&region=counties&sub_choices=["CA - Mono"]

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET

variable

yes

tmmx

temporal_statistic

yes

mean, median, max, min, total

start_date

yes

2019-01-01

end_date

yes

2019-12-31

feature_collection

yes

Feature collection name, see list of available assets

states

sub_choices

no

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

CA, NV

area_reducer

yes

Statistic over region

mean

mean, median, min, max

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/values/custom_asset

Computes temporal statistics for the features of a custom feature collection asset.
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/values/custom_asset?dataset=LANDSAT_TOA&variable=EVI&temporal_statistic=mean&start_date=2014-07-01&end_date=2014-08-31&asset_id=USGS/WBD/2017/HUC08&sub_choices=["Animas"]&filter_by=name

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

GRIDMET

variable

yes

tmmx

temporal_statistic

yes

mean, median, max, min, total

start_date

yes

2019-01-01

end_date

yes

2019-12-31

asset_id

yes

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

‘projects/climate-engine/featureCollections/shp_simplified/ClimateEngine_US_Counties’

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

CA, NV

area_reducer

yes

Statistic over region

mean

mean, median, min, max

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/values/polygons

Computes temporal statistics for polygons.
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/values/polygons?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

dataset

yes

GRIDMET

variable

yes

tmmx

temporal_statistic

yes

mean, median, max, min, total

start_date

yes

2019-01-01

end_date

yes

2019-12-31

coordinates

yes

lon, lat pairs of polygon vertices

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

buffers

no

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

[400]

area_reducer

yes

Statistic over region

mean

mean, median, min, max

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/value/climate_engine_asset

Returns static values for the features of a Climate Engine feature collection asset.
For a list of available assets see the Climate Engine Assets section.
Returns: json

Resource url example:

zonal_stats/value/climate_engine_asset?dataset=WRC&variable=WHP&region=divisions&sub_choices=%5B%22NY%20-%20YATES%22%5D&area_reducer=mean

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

WRC

variable

yes

WHP

mask_image_id

no

Image mask ID

mask_value

no

Image mask value

region

yes

divisions

feature_collection

yes

Feature collection name, see list of available assets

states

sub_choices

no

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

[“NY - YATES”]

filter_by

no

“Name”

area_reducer

yes

Statistic over region

mean

mean, median, min, max

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/value/custom_asset

Returns static values for the features of a custom asset.
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/value/custom_asset?dataset=WRC&variable=BP&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

dataset

yes

WRC

variable

yes

BP

mask_image_id

no

Image mask ID

mask_value

no

Image mask value

asset_id

yes

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

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/value/points

Returns static values for provided point geometries.
Returns: json

Resource url example:

zonal_stats/value/points?dataset=WRC&variable=CFL&coordinates=%5B%5B-158.9844%2C62.3723%5D%5D&area_reducer=mean

NAME

REQUIRED

DESCRIPTION

DEFAULT

EXAMPLE

dataset

yes

WRC

variable

yes

CFL

mask_image_id

no

Image mask ID

mask_value

no

Image mask value

coordinates

yes

lon, lat pairs of points

[[-158.9844,62.3723]]

buffer

no

Buffer (in meters) to apply to each geometry

[400]

area_reducer

yes

Statistic over region

mean

mean, median, min, max

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/value/polygons

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

Resource url example:

zonal_stats/value/polygons?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

dataset

yes

WRC

variable

yes

FLEP8

mask_image_id

no

Image mask ID

mask_value

no

Image mask value

coordinates

yes

lon, lat pairs of polygon vertices

[[-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

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/polygons

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

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/value/polygons?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

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

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

coordinates

yes

List of lon,lat pairs of polygon vertices

[[[-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]]]

group_band

yes

Image band to use

spi1y

drought

summary_band

yes

Image band to use

population_count

population_count

group_img_type

yes

Continuous or Discrete

continuous

discrete, continuous

area_reducer

yes

Statistic over region

mean

mean, median, min, max, sum

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

buffer

no

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

[100]

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/climate_engine_asset

Returns summaries (mean, sum, etc.) for user defined categories within the user defined eatures of a Climate Engine feature collection asset.

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/value/polygons?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

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

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

region

yes

Type of feature collection.

states

states

sub_choices

no

List of features to use in analysis, must be strings

Arizona

filter_by

no

Attribute to filter feature collection by.

Name

group_band

yes

Image band to use

spi1y

drought

summary_band

yes

Image band to use

population_count

population_count

group_img_type

yes

Continuous or Discrete

continuous

discrete, continuous

area_reducer

yes

Statistic over region

mean

mean, median, min, max, sum

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

buffer

no

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

[100]

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/custom_asset

Returns summaries (mean, sum, etc.) for user defined categories within the user defined features of a custom asset.

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/value/polygons?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

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

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

asset_id

yes

Path to Earth Engine asset.

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

group_band

yes

Image band to use

spi1y

drought

summary_band

yes

Image band to use

population_count

population_count

group_img_type

yes

Continuous or Discrete

continuous

discrete, continuous

area_reducer

yes

Statistic over region

mean

mean, median, min, max, sum

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

buffer

no

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

[100]

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