Updating Ratings in ReadTheDocs

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

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 <https://cwms-database.readthedocs.io/en/latest/naming.html#rating-templates>`_
+
+  - 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 <https://cwms-database.readthedocs.io/en/latest/naming.html#rating-specifications>`_
+
+  - 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`
+

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 <timeSeries>
+    /ratings/effective-dates <ratings-effective_dates>
+    /ratings/metadata <ratings-metadata>
+    /ratings/{rating-id}/ <ratings-ratingID>
+    /ratings/{rating-id}/latest <ratings-ratingID-latest>
+    /ratings/spec <ratings-spec>
+    /ratings/spec/{rating-id} <ratings-spec-ratingID>
+    /ratings/template <ratings-template>
+    /ratings/template/{template-id} <ratings-template-templateID>

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

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

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

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

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 <https://cwms-database.readthedocs.io/en/latest/naming.html#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