.. sectionauthor:: Britta Daudert 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). | :ref:`RST /zonal_stats/pixel_count/coordinates` | :ref:`RST /zonal_stats/pixel_count/feature_collection` | :ref:`RST /zonal_stats/pixel_count/timeseries/coordinates` | :ref:`RST /zonal_stats/pixel_count/timeseries/feature_collection` | :ref:`RST /zonal_stats/static_dataset/coordinates` | :ref:`RST /zonal_stats/static_dataset/feature_collection` | :ref:`RST /zonal_stats/temporal_dataset/coordinates` | :ref:`RST /zonal_stats/temporal_dataset/feature_collection` | :ref:`RST /zonal_stats/group_by/coordinates` | :ref:`RST /zonal_stats/group_by/feature_collection` .. _RST /zonal_stats/pixel_count/coordinates: /zonal_stats/pixel_count/coordinates ************************************ | Computes number of pixels in each drought category for polygons. | Returns: json Resource url example: .. code-block:: /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]]] .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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]]] * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/pixel_count/feature_collection: /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: .. code-block:: /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 .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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 * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/pixel_count/timeseries/coordinates: /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: .. code-block:: /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]] .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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]] * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/pixel_count/timeseries/feature_collection: /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: .. code-block:: /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 .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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 * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/static_dataset/coordinates: /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: .. code-block:: 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 .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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]] * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/static_dataset/feature_collection: /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: .. code-block:: 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 .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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 * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/temporal_dataset/coordinates: /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: .. code-block:: /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]]] .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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]] * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/temporal_dataset/feature_collection: /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: .. code-block:: /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 .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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 * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/group_by/coordinates: /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: .. code-block:: zonal_stats/groupby/coordinates? .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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]]] * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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 .. _RST /zonal_stats/group_by/feature_collection: /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: .. code-block:: zonal_stats/group_by/feature_collection? .. list-table:: :widths: 25 5 25 25 25 :header-rows: 1 * - 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 * - simplify_geometry - no - maxError in meters, see `ee.Feature.simplify `_ - None - * - 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