diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 9249e6fe36..e608dbc782 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -20,6 +20,8 @@ - Rohaan S. Sandhu (rohaan@rmanet.com) - - Copyright 2025 Resource Management Associates - Kayla J. Arritola (kayla@rmanet.com) +- Copyright 2026 Resource Management Associates +- Deziree L. Seidner (deziree@rmanet.com) - _Add the copyright date, your name, and email address here. (PLEASE KEEP THIS LINE)_ ## Note for U.S. Federal Employees diff --git a/docs/source/data/ratings.rst b/docs/source/data/ratings.rst new file mode 100644 index 0000000000..312ff48b54 --- /dev/null +++ b/docs/source/data/ratings.rst @@ -0,0 +1,45 @@ +.. _ratings_basics: + +Ratings +=========== + +- What is a Rating? + + - A Rating is a mathematical relationship between one or several independent parameter(s) and a dependent parameter. + The Rating can be used to determine the value of the dependent parameter associated with a single or a set of independent parameters. + +- Data structure overview + + - Core Components: Rating Specification, Effective Date + +- What is a Rating Template? + + `CWMS database - Rating Templates Definition `_ + + - A Rating template is a general association and prioritization of independent and dependent parameters that can be + used by multiple rating specifications. + +- Data structure overview + + - Core Components: Parameters (Independent and Dependent), Version + +- What is a Rating Specification? + + `CWMS database - Rating Specifications Definition `_ + + - A Rating Specification iis a Rating Template applied to a specific location. + +- Data structure overview + + - Core Components: Location, Rating Template + +- Typical use cases + + - Access a specific rating for a given location and effective date + + +The ratings endpoints allow you to retrieve and manage rating data stored in the CWMS database. +See the individual endpoint documentation for details on each available operation: + +- :ref:`ratings-endpoints` + diff --git a/docs/source/endpoints/ratings_endpoints/index.rst b/docs/source/endpoints/ratings_endpoints/index.rst new file mode 100644 index 0000000000..42f803f854 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/index.rst @@ -0,0 +1,30 @@ +.. _ratings-endpoints: + +Ratings Endpoints +======================= + +.. note:: + + This documentation is a work in progress. This section currently includes the below Ratings endpoints and focuses + on the GET methods and their parameters. + + POST, PATCH, and DELETE methods and their specific parameters are coming soon. + + +Browse Ratings GET Endpoints: + +.. toctree:: + :maxdepth: 1 + + Ratings Basic Information <../../data/ratings.rst> + Common Parameter Definitions <./shared_definitions.rst> + Common Reasons for Parameter Usage <./shared_when_to_use.rst> + /ratings + /ratings/effective-dates + /ratings/metadata + /ratings/{rating-id}/ + /ratings/{rating-id}/latest + /ratings/spec + /ratings/spec/{rating-id} + /ratings/template + /ratings/template/{template-id} diff --git a/docs/source/endpoints/ratings_endpoints/ratings-effective_dates.rst b/docs/source/endpoints/ratings_endpoints/ratings-effective_dates.rst new file mode 100644 index 0000000000..1b9a7ac589 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-effective_dates.rst @@ -0,0 +1,41 @@ +Ratings — GET /ratings/effective-dates +========================================= + +What it does +------------ +Returns the effective dates and times for a given rating specification ID and office ID. Time window can be set to filter the effective dates retrieved. + + +When to use +----------- +- Retrieving available effective dates for a rating + + +.. csv-table:: GET /ratings/effective-dates - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + begin, ":ref:`def-start`", "", ":ref:`when_start`" + end, ":ref:`def-end`", "", ":ref:`when_end`" + office-mask, ":ref:`def-office`","", ":ref:`when_office`" + rating-id-mask, ":ref:`def-rating-id-mask`", "", ":ref:`when_rating_id_mask`" + timezone, ":ref:`def-timezone`", "", "To retrieve data points in a timezone that works best with \ + your use case, such as your local timezone." + + +Examples +-------- +1. | The user wants to retrieve the effective dates for the rating specification ID of + | `KEYS.Elev;Area.Linear.Production` from the office of `SWT`: + | (**office-mask**) :code:`SWT` + | + | (**rating-id-mask**) :code:`KEYS.Elev;Area.Linear.Production` + + .. code-block:: urlencoded + + GET /ratings/effective-dates?office-mask=SWT&rating-id-mask=KEYS.Elev%3BArea.Linear.Production + + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-metadata.rst b/docs/source/endpoints/ratings_endpoints/ratings-metadata.rst new file mode 100644 index 0000000000..63c39edece --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-metadata.rst @@ -0,0 +1,41 @@ +Ratings — GET /ratings/metadata +=================================== + +What it does +------------ +Returns the information that describes the rating and provides the context needed to identify, manage, and correctly \ +apply a rating. + +When to use +----------- +- Needing information about the rating without retrieving all of the rating's computational data + + +.. csv-table:: GET /ratings/recent - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + end, ":ref:`def-end`", "", ":ref:`when_end`" + page, ":ref:`def-page`", "", ":ref:`when_page`" + page-size, ":ref:`def-page-size", "", ":ref:`when_page_size`" + start, ":ref:`def-start`", "", ":ref:`when_start`" + rating-id-mask, ":ref:`def-rating-id-mask`", "", ":ref:`when_rating_id_mask`" + office, ":ref:`def-office`","", ":ref:`when_office`" + + +Examples +-------- +1. | The user wants to retrieve the metadata for the rating specification ID of + | `KEYS.Elev;Area.Linear.Production` from the office of `SWT`: + | (**office-mask**) :code:`SWT` + | + | (**rating-id-mask**) :code:`KEYS.Elev;Area.Linear.Production` + + .. code-block:: urlencoded + + GET /ratings/metadata?office=SWT&rating-id-mask=KEYS.Elev%3BArea.Linear.Production + + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-ratingID-latest.rst b/docs/source/endpoints/ratings_endpoints/ratings-ratingID-latest.rst new file mode 100644 index 0000000000..60aa3502f2 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-ratingID-latest.rst @@ -0,0 +1,36 @@ +TimeSeries — GET /ratings/{rating-id}/latest +=================================== + +What it does +------------ +Returns the rating data of the latest available effective date for a given rating ID. + +When to use +----------- +- Retrieving the rating data for the latest available effective date + + +.. csv-table:: GET /ratings/{rating-id}/latest - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + office, ":ref:`def-office`","Yes", ":ref:`when_office`" + rating-id, ":ref:`def-rating-id", "Yes", ":ref:`when-rating-id`" + + +Examples +-------- +1. | The user wants to retrieve the all available rating data for all effective dates of the rating ID + | `KEYS.Elev;Area.Linear.Production`: + | (**rating-id**) :code:`KEYS.Elev;Area.Linear.Production` + | + | (**office**) :code:`SWT` + + .. code-block:: urlencoded + + GET /ratings/KEYS.Elev%3BArea.Linear.Production/latest?office=SWT + + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-ratingID.rst b/docs/source/endpoints/ratings_endpoints/ratings-ratingID.rst new file mode 100644 index 0000000000..6fe6a98d8d --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-ratingID.rst @@ -0,0 +1,57 @@ +Ratings — GET /ratings/{rating-id} +=================================== + +What it does +------------ +Returns the rating data for a provided rating ID for a given office. + +This can be filtered for the rating data for an effective date between a given time window. + + +When to use +----------- +- Retrieving rating data for all available effective dates +- Retrieving rating data for specific effective dates + + +.. csv-table:: GET /ratings/{rating-id} - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + begin, ":ref:`def-start`", "", ":ref:`when_start`" + end, ":ref:`def-end`", "", ":ref:`when_end`" + method, ":ref:`def-method`", "", ":ref:`when_method`" + office, ":ref:`def-office`","Yes", ":ref:`when_office`" + rating-id, ":ref:`def-rating-id", "Yes", ":ref:`when-rating-id`" + timezone, ":ref:`def-timezone`", "", "To retrieve data points in a timezone that works best with \ + your use case, such as your local timezone." + + +Examples +-------- +1. | The user wants to retrieve the all available rating data for all effective dates of the rating ID + | `KEYS.Elev;Area.Linear.Production`: + | (**rating-id**) :code:`KEYS.Elev;Area.Linear.Production` + | + | (**office**) :code:`SWT` + + .. code-block:: urlencoded + + GET /ratings/KEYS.Elev%3BArea.Linear.Production?office=SWT + +2. | The user wants to retrieve the rating data for effective dates after 2020 for the rating ID + | `KEYS.Elev;Area.Linear.Production`: + | (**rating-id**) :code:`KEYS.Elev;Area.Linear.Production` + | + | (**office**) :code:`SWT` + | + | (**begin**) :code:`2020-01-01T05:00:00Z` + + .. code-block:: urlencoded + + GET /ratings/KEYS.Elev%3BArea.Linear.Production?office=SWT&begin=2020-01-01T05%3A00%3A00Z + + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-spec-ratingID.rst b/docs/source/endpoints/ratings_endpoints/ratings-spec-ratingID.rst new file mode 100644 index 0000000000..485a657fb0 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-spec-ratingID.rst @@ -0,0 +1,65 @@ +TimeSeries — GET /timeseries/recent +=================================== + +What it does +------------ +Returns the most recent value(s) from one or more time series without downloading a historical range. + +Retrieves time series data from 28 days before to 14 days after the current date. + +When to use +----------- +- Dashboards needing the latest readings +- Health checks and alerts for current conditions + + +.. csv-table:: GET /timeseries/recent - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + category-id, "The text identifier for the time series category defined in the CWMS database for a specific time \ + series.","", "To limit results to a specific assigned time series category." + group-id, "The text identifier of the time series group defined in the CWMS database for a specific time series.","\ + Only if ts-ids are NOT provided", "To limit results to a specific assigned time series group." + ts-ids, "`CWMS database - time series `_","\ + Only if group-id is NOT provided", "To get the recent data for the specified time series." + unit-system, "SI or EN, default: EN","", "To convert response data to a particular unit system." + office, ":ref:`def-office`","", ":ref:`when_office`" + + +Examples +-------- +1. | The user wants to retrieve the recent time series data for the specified time series IDs of + | `STATION1.Flow.Inst.15Minutes.0.CWMS` and `STATION2.Stage.Inst.15Minutes.0.CWMS`: + | (**ts-ids**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS` + | + | and they want the data to be in the Imperial unit system: + | (**unit-system**) :code:`EN` + + .. code-block:: urlencoded + + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN + +2. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-id=CALC3 + +3. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + | + | and in the `COMPUTE` time series category: + | (**category-id**) :code:`COMPUTE` + | + | for the `HQ` office: + | (**office**) :code:`HQ` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-spec.rst b/docs/source/endpoints/ratings_endpoints/ratings-spec.rst new file mode 100644 index 0000000000..485a657fb0 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-spec.rst @@ -0,0 +1,65 @@ +TimeSeries — GET /timeseries/recent +=================================== + +What it does +------------ +Returns the most recent value(s) from one or more time series without downloading a historical range. + +Retrieves time series data from 28 days before to 14 days after the current date. + +When to use +----------- +- Dashboards needing the latest readings +- Health checks and alerts for current conditions + + +.. csv-table:: GET /timeseries/recent - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + category-id, "The text identifier for the time series category defined in the CWMS database for a specific time \ + series.","", "To limit results to a specific assigned time series category." + group-id, "The text identifier of the time series group defined in the CWMS database for a specific time series.","\ + Only if ts-ids are NOT provided", "To limit results to a specific assigned time series group." + ts-ids, "`CWMS database - time series `_","\ + Only if group-id is NOT provided", "To get the recent data for the specified time series." + unit-system, "SI or EN, default: EN","", "To convert response data to a particular unit system." + office, ":ref:`def-office`","", ":ref:`when_office`" + + +Examples +-------- +1. | The user wants to retrieve the recent time series data for the specified time series IDs of + | `STATION1.Flow.Inst.15Minutes.0.CWMS` and `STATION2.Stage.Inst.15Minutes.0.CWMS`: + | (**ts-ids**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS` + | + | and they want the data to be in the Imperial unit system: + | (**unit-system**) :code:`EN` + + .. code-block:: urlencoded + + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN + +2. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-id=CALC3 + +3. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + | + | and in the `COMPUTE` time series category: + | (**category-id**) :code:`COMPUTE` + | + | for the `HQ` office: + | (**office**) :code:`HQ` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-template-templateID.rst b/docs/source/endpoints/ratings_endpoints/ratings-template-templateID.rst new file mode 100644 index 0000000000..485a657fb0 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-template-templateID.rst @@ -0,0 +1,65 @@ +TimeSeries — GET /timeseries/recent +=================================== + +What it does +------------ +Returns the most recent value(s) from one or more time series without downloading a historical range. + +Retrieves time series data from 28 days before to 14 days after the current date. + +When to use +----------- +- Dashboards needing the latest readings +- Health checks and alerts for current conditions + + +.. csv-table:: GET /timeseries/recent - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + category-id, "The text identifier for the time series category defined in the CWMS database for a specific time \ + series.","", "To limit results to a specific assigned time series category." + group-id, "The text identifier of the time series group defined in the CWMS database for a specific time series.","\ + Only if ts-ids are NOT provided", "To limit results to a specific assigned time series group." + ts-ids, "`CWMS database - time series `_","\ + Only if group-id is NOT provided", "To get the recent data for the specified time series." + unit-system, "SI or EN, default: EN","", "To convert response data to a particular unit system." + office, ":ref:`def-office`","", ":ref:`when_office`" + + +Examples +-------- +1. | The user wants to retrieve the recent time series data for the specified time series IDs of + | `STATION1.Flow.Inst.15Minutes.0.CWMS` and `STATION2.Stage.Inst.15Minutes.0.CWMS`: + | (**ts-ids**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS` + | + | and they want the data to be in the Imperial unit system: + | (**unit-system**) :code:`EN` + + .. code-block:: urlencoded + + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN + +2. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-id=CALC3 + +3. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + | + | and in the `COMPUTE` time series category: + | (**category-id**) :code:`COMPUTE` + | + | for the `HQ` office: + | (**office**) :code:`HQ` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings-template.rst b/docs/source/endpoints/ratings_endpoints/ratings-template.rst new file mode 100644 index 0000000000..485a657fb0 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings-template.rst @@ -0,0 +1,65 @@ +TimeSeries — GET /timeseries/recent +=================================== + +What it does +------------ +Returns the most recent value(s) from one or more time series without downloading a historical range. + +Retrieves time series data from 28 days before to 14 days after the current date. + +When to use +----------- +- Dashboards needing the latest readings +- Health checks and alerts for current conditions + + +.. csv-table:: GET /timeseries/recent - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 25, 55 + + category-id, "The text identifier for the time series category defined in the CWMS database for a specific time \ + series.","", "To limit results to a specific assigned time series category." + group-id, "The text identifier of the time series group defined in the CWMS database for a specific time series.","\ + Only if ts-ids are NOT provided", "To limit results to a specific assigned time series group." + ts-ids, "`CWMS database - time series `_","\ + Only if group-id is NOT provided", "To get the recent data for the specified time series." + unit-system, "SI or EN, default: EN","", "To convert response data to a particular unit system." + office, ":ref:`def-office`","", ":ref:`when_office`" + + +Examples +-------- +1. | The user wants to retrieve the recent time series data for the specified time series IDs of + | `STATION1.Flow.Inst.15Minutes.0.CWMS` and `STATION2.Stage.Inst.15Minutes.0.CWMS`: + | (**ts-ids**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS` + | + | and they want the data to be in the Imperial unit system: + | (**unit-system**) :code:`EN` + + .. code-block:: urlencoded + + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN + +2. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-id=CALC3 + +3. | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: + | (**group-id**) :code:`CALC3` + | + | and in the `COMPUTE` time series category: + | (**category-id**) :code:`COMPUTE` + | + | for the `HQ` office: + | (**office**) :code:`HQ` + + .. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst \ No newline at end of file diff --git a/docs/source/endpoints/ratings_endpoints/ratings.rst b/docs/source/endpoints/ratings_endpoints/ratings.rst new file mode 100644 index 0000000000..a8edf4563a --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/ratings.rst @@ -0,0 +1,59 @@ +.. _timeSeries_endpoint: + +TimeSeries — GET /ratings +============================== + + +What it does +------------ + +Retrieve rating data for a location and effective date. The time window may be adjusted to retrieve ratings for previous effective dates. + +When to use +----------- + +- View rating data for a given location +- Export rating data for a given location + + +.. csv-table:: GET /ratings - Endpoint Parameters + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 20, 60 + + at, ":ref:`def-start`", "", ":ref:`when_start`" + datum, "The standardized reference system used for either vertical measurements. \ + Examples: NAVD88, NGVD29, LOCAL, etc.", "", "To retrieve measurements in a specified system." + end, ":ref:`def-end`", "", ":ref:`when_end`" + format, "The desired response format. Usage differs between endpoints. See note below.", "", "Use this \ + to force the format provided in the response." + name, "Location ID to retrieve the rating data for.", "", "To \ + differentiate the specific rating data you desire to retrieve." + office, ":ref:`def-office`", "", ":ref:`when_office`" + timezone, ":ref:`def-timezone`", "", "To retrieve data points in a timezone that works best with \ + your use case, such as your local timezone." + unit, ":ref:`def-unit`", "", "" + + +.. note:: + Detailed documentation for Legacy Format Responses for the `format` parameter in CDA is currently + in development and will be available at https://cwms-data.usace.army.mil/cwms-data/legacy-format + in a future release. + +Examples +---------- + +1. | The user wants to retrieve available rating data for `KEYS`: + | (**name**) :code:`KEYS` + | + | (**office**) :code:`SWT` + | + | (**unit**) :code:`SI`. + + .. code-block:: urlencoded + + GET /ratings?name=KEYS&office=SWT&unit=SI + + +See the consolidated API documentation: :doc:`/api-references`. + +.. include:: /_includes/feedback_button.rst diff --git a/docs/source/endpoints/ratings_endpoints/shared_definitions.rst b/docs/source/endpoints/ratings_endpoints/shared_definitions.rst new file mode 100644 index 0000000000..cce1e3e780 --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/shared_definitions.rst @@ -0,0 +1,152 @@ +Shared ratings endpoint parameters +====================================== + +.. _shared-defs: + +Shared parameter definitions +---------------------------- + +This section lists and describes common parameters that are used by multiple Ratings endpoints. +If the parameter is only used by a single endpoint, please refer to that endpoint's documentation for details. +If a shared parameter has endpoint-specific behavior or constraints, those details will be noted in the individual +endpoint documentation. + +.. _def-end: + +end + The date and time marking the end of the time window for data included in the response. + The format for this field is ISO 8601 extended with optional offset and timezone. + + .. code-block:: sql + + Example: + YYYY-MM-ddThh:mm:ss[Z[VV]] + 2021-06-10T13:00:00-07:00 OR 2025-10-25T12:25:00Z + + .. note:: + Detailed documentation for Timestamps usage in CDA is currently in development and will be available at + https://cwms-data.usace.army.mil/cwms-data/timestamps in a future release. + + +.. _def-location-id: + +location-id + `CWMS database - Location Naming `_ + `CWMS database - Location Definition `_ + +.. _def-location-mask: + +location-mask + A regular expression used to filter the location name associated with the queried time series data. See the Regex + documentation page for more information on usage: + + .. note:: + Detailed documentation for Regex usage in CDA is currently in development and will be available at + https://cwms-data.usace.army.mil/cwms-data/regexp in a future release. + +.. _def-method: + +method + The retrieval method used. If no method is provided, the EAGER method will be used. + +.. _def-office: + +office + The organizational context used to scope data access and defaults. Some endpoints infer a default office; + you can also specify it explicitly. + +.. _def-office-mask: + +office-mask + A regular expression used to filter the office identifier associated with the queried time series data. + See the Regex documentation page for more information on usage: + + .. note:: + Detailed documentation for Regex usage in CDA is currently in development and will be available at + https://cwms-data.usace.army.mil/cwms-data/regexp in a future release. + +.. _def-page: + +page + Page token for paginated endpoints. Value to use is provided by the `next-page` entry of a qualifying query response. + +.. _def-page-size: + +page-size + Maximum number of items per page (server may enforce an upper bound). Further results must be accessed using the \ + `next-page` value provided in the response of queries that return more results than will fit on one page. + +.. _def-parameter-id: + +parameter-id + A text identifier specifying the type of data measured by the time series, such as "Flow", "Stage", "Elev", etc. + + .. note:: + This link will take you to the Parameter Types definition. Scroll up one section to see the Parameter Definition. + `CWMS database - parameter types `_ + + As soon as this link is repaired, we will replace the above link with the correct one: + `CWMS database - parameters `_ + +.. _def-parameter-id-mask: + +parameter-id-mask + A regular expression used to filter the parameter of the queried time series data. + See the Regex documentation for more information on usage: + + .. note:: + Detailed documentation for Regex usage in CDA is currently in development and will be available at + https://cwms-data.usace.army.mil/cwms-data/regexp in a future release. + +.. _def-rating-id: + +rating-id + A regular expression used to filter the rating specification IDs to be included in the response. + + .. note:: + Documentation for Rating Specifications is available at + `CWMS database - rating specification `_. + +.. _def-rating-id-mask: + +rating-id-mask + A regular expression used to filter the rating specification IDs to be included in the response. + + .. note:: + Documentation for Rating Specifications is available at + `CWMS database - rating specification `_. + +.. _def-start: + +start/begin + The date and time marking the beginning of the time window for data included in the response. + The format for this field is ISO 8601 extended with optional offset and timezone. + + .. code-block:: sql + + Example: + YYYY-MM-ddThh:mm:ss[Z[VV]] + 2021-06-10T13:00:00-07:00 OR 2025-10-25T12:25:00Z + + .. note:: + Detailed documentation for Timestamps usage in CDA is currently in development and will be available at + https://cwms-data.usace.army.mil/cwms-data/timestamps in a future release. + +.. _def-timezone: + +timezone + The timezone to use for retrieved time data, such as "UTC", "America/Los_Angeles", etc. + +.. _def-unit: + +unit `(Deprecated, prefer units or unit-system)` + The unit system or specific unit to convert the response data into. Available unit systems are SI or EN. + Examples of other units are m, ft, m3, etc. + For reference: `CWMS database - units `_ + +.. _def-version-date: + +version-date + A date associated with a time series to make identification of the most recent data possible. + Often uses the forecast date. + diff --git a/docs/source/endpoints/ratings_endpoints/shared_when_to_use.rst b/docs/source/endpoints/ratings_endpoints/shared_when_to_use.rst new file mode 100644 index 0000000000..775d6b730a --- /dev/null +++ b/docs/source/endpoints/ratings_endpoints/shared_when_to_use.rst @@ -0,0 +1,78 @@ +Shared Time Series Examples of When to Use +============================================ + +.. _when_start: + +start/begin + To limit the results to be after a specified date and time. + +.. _when_end: + +end + To limit the results to be before a specified date and time. + +.. _when_office: + +office + To limit your results to a specific office if there \ + are multiple time series with the same identifier across multiple offices, for example with a daily forecast that \ + more than one office may generate. This can also help improve query response time for large datasets. + +.. _when_location_id: + +location-id + To specify the location for which you want to retrieve time series or profile data, \ + such as a specific river gauge or reservoir. + +.. _when_method: + +method + To specify the retrieval method used for ratings. + +.. _when_parameter_id: + +parameter-id + To identify the specific parameter combination \ + associated with the desired profile or profile parser, e.g. `Flow-Evap`. + +.. _when_page: + +page + To reach a specific page in the set of results to get results that were not able to fit in the previous page. + +.. _when_page_size: + +page_size + To specify the number of results you wish to receive \ + from a single query, such as for the purpose of \ + receiving a small set of results out of many, e.g. using `50` to get 50 out of 5000 total results.\ + Further results may be available on a subsequent page of the same length. + +.. _when_office_mask: + +office-mask + To limit results to a specific office, such as `SPK`, or to offices \ + starting with `S` using `S*`. + +.. _when_location_mask: + +location-mask + To limit results to a specific location or pattern, \ + for example limiting results to locations containing `River` using `*River*`. + +.. _when_parameter_id_mask: + +parameter-id-mask + To limit results to a specific parameter or pattern, \ + for example limiting results to parameters starting with `Flow` using `Flow*`. \ + For multiple parameters, a mask may look like `Depth-Temperature` or `*-Temperature`. + +.. _when_rating_id: + +rating-id + To limit results to a specific rating ID or pattern. + +.. _when_rating_id_mask: + +rating-id-mask + To limit results to a specific rating ID or pattern. \ No newline at end of file