.. sectionauthor:: Eric Jensen <eric.jensen at dri.edu>

Reports
=============

| The Reports endpoints are used to generate PNG and PDF reports that summarize vegetation and climate conditions over a specified time period for user-defined areas of interest. The reports include maps, timeseries, and statistics. The results are returned as JSON with a URL to zip file with the report and data stored in Google Cloud Storage.

| There are three groups of Reports endpoints:

| **/reports/drought** - The Drought Reports provide maps, tables, and timeseries of multi-indicator drought indices (long-term and short-term drought) and underlying data pulled from gridMET Drought.
| **/reports/site_characterization** - The Site Characterization Reports provide maps, tables, and timeseries of fractional vegetation cover, vegetation production, and drought and climate with data pulled from the Rangeland Analysis Platform, gridMET, and gridMET Drought.
| **/reports/vegetation_production** - The Vegetation Production Reports provide maps, tables, and timeseries of vegetation productivity with data pulled from the Rangeland Analysis Platform and gridMET.

| :ref:`RST /reports/drought/coordinates`
| :ref:`RST /reports/drought/feature_collection`
| :ref:`RST /reports/site_characterization/coordinates`
| :ref:`RST /reports/site_characterization/feature_collection`
| :ref:`RST /reports/vegetation_production/coordinates`
| :ref:`RST /reports/vegetation_production/feature_collection`

.. _RST /reports/drought/coordinates:

/reports/drought/coordinates
*************************************
| Generates Climate Engine Drought Report for polygon coordinates.
| Returns: json

Resource url example:

.. code-block::

    /reports/drought/coordinates?coordinates=%5B%5B%5B-115.7326%2C%2039.3643%5D%2C%20%5B-115.7326%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3643%5D%5D%5D&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None

.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM


.. _RST /reports/drought/feature_collection:

/reports/drought/feature_collection
********************************************
| Generates Climate Engine Drought Report for polygon in Google Earth Engine Feature Collection.
| Returns: json

Resource url example:

.. code-block::

    /reports/drought/feature_collection?feature_collection_asset_id=USGS%2FWBD%2F2017%2FHUC12&sub_choices=140300051008&filter_by=huc12&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None
.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - sub_choices
     - no
     - Values of property in feature collection
     -
     - Idaho, Nevada
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM

.. _RST /reports/site_characterization/coordinates:

/reports/site_characterization/coordinates
***********************************
| Generates Climate Engine Site Characterization Report for polygon coordinates.
| Returns: json

Resource url example:

.. code-block::

    site_characterization/coordinates?coordinates=%5B%5B%5B-115.7326%2C%2039.3643%5D%2C%20%5B-115.7326%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3643%5D%5D%5D&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None&batch=True

.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM
   * - batch
     - no
     - Returns the link prior to processing the report and does not send email, if True
     - True
     - True

.. _RST /reports/site_characterization/feature_collection:

/reports/site_characterization/feature_collection
******************************************
| Generates Climate Engine Site Characterization Report for polygon in Google Earth Engine Feature Collection.
| Returns: json

Resource url example:

.. code-block::

    reports/site_characterization/feature_collection?feature_collection_asset_id=USGS%2FWBD%2F2017%2FHUC12&sub_choices=140300051008&filter_by=huc12&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None&batch=True

.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - sub_choices
     - no
     - Values of property in feature collection
     -
     - Idaho, Nevada
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM
   * - batch
     - no
     - Returns the link prior to processing the report and does not send email, if True
     - True
     - True

.. _RST /reports/vegetation_production/coordinates:

/reports/vegetation_production/coordinates
***********************************
| Generates Climate Engine Vegetation Production Report for polygon coordinates.
| Returns: json

Resource url example:

.. code-block::

    vegetation_production/coordinates?coordinates=%5B%5B%5B-115.7326%2C%2039.3643%5D%2C%20%5B-115.7326%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3637%5D%2C%20%5B-115.7320%2C%2039.3643%5D%5D%5D&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None&batch=True

.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM
   * - batch
     - no
     - Returns the link prior to processing the report and does not send email, if True
     - True
     - True

.. _RST /reports/vegetation_production/feature_collection:

/reports/vegetation_production/feature_collection
******************************************
| Generates Climate Engine Vegetation Production Report for polygon in Google Earth Engine Feature Collection.
| Returns: json

Resource url example:

.. code-block::

    reports/vegetation_production/feature_collection?feature_collection_asset_id=USGS%2FWBD%2F2017%2FHUC12&sub_choices=140300051008&filter_by=huc12&simplify_geometry=None&user_email=eric.jensen%40dri.edu&site_name=example_site&mask_landcover=False&mask_ownership=None&batch=True

.. 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 <https://developers.google.com/earth-engine/apidocs/ee-feature-simplify>`_
     - None
     - 100
   * - sub_choices
     - no
     - Values of property in feature collection
     -
     - Idaho, Nevada
   * - user_email
     - yes
     - Email address to send result to
     -
     - user@example.com
   * - site_name
     - yes
     - Name of site to appear in report
     - example_site
     - Example site
   * - site_type
     - no
     - Optional description of type of site to appear in report
     -
     - Example site type
   * - site_description
     - no
     - Optional description of site to appear in report
     -
     - Example site description
   * - mask_landcover
     - no
     - Apply landcover mask to remove cultivated crops, water, and developed lands.
     - False
     - True
   * - mask_ownership
     - no
     - Apply land ownership mask to using Surface Management Agency (SMA) boundaries. One of ['None', 'BIA', 'BLM', 'DOD', 'FWS', 'NPS', 'USFS']
     - None
     - BLM
   * - batch
     - no
     - Returns the link prior to processing the report and does not send email, if True
     - True
     - True