CDA-64: Updates to TimeSeries documentation examples #1543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

rma-rripken merged 12 commits into USACE:develop from zack-rma:docs/ts-docs-update

Feb 3, 2026

docs/source/data/timeseries.rst

-Original file line number
+Diff line change
@@ -1,7 +1,32 @@
+    .. _timeSeries_basics:
     TimeSeries
     ===========
-    This page is coming soon if necessary or may be replaced by :ref:`timeseries-basics`
+    - What is a TimeSeries?
+        `CWMS database - Time Series Definition <https://cwms-database.readthedocs.io/en/latest/naming.html#time-series>`_
+      - A TimeSeries is a sequence of timestamped values measured or computed at a location for a specific
+        parameter (e.g., stage, flow). Each series may be recorded at a given interval (e.g., 15-min) and type
+        (e.g., observed, computed). Some series also have versions.
+    - Data structure overview
+      - Core Components: Location, Parameter, Type, Interval, Duration, Version
+        `CWMS database - Component Definitions <https://cwms-database.readthedocs.io/en/latest/naming.html#>`_
+    - Typical use cases
+      - View most recent observation values
+      - Retrieve a historical range to chart or analyze
+      - Access a specific profile at a location/parameter
+    The time series endpoints allow you to retrieve and manage time series data stored in the CWMS database.
+    See the individual endpoint documentation for details on each available operation:
-    Please check back later for updates and new content.
+    - :ref:`timeSeries-endpoints`

docs/source/endpoints/timeSeries_endpoints/index.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -16,8 +16,9 @@ Browse Time Series GET Endpoints: @@
     .. toctree::
         :maxdepth: 1
-        TimeSeries Basic Information <./timeseries_basics.rst>
+        TimeSeries Basic Information <../../data/timeseries.rst>
         Common Parameter Definitions <./shared_definitions.rst>
+        Common Reasons for Parameter Usage <./shared_when_to_use.rst>
         /timeseries <timeSeries>
         /timeseries/recent <timeSeries-recent>
         /timeseries/profile <timeSeries-profile>
@@ Expand Down @@

docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -63,12 +63,13 @@ office-mask
  
    .. _def-page:

    page

      Page token for paginated endpoints. Use with next/previous links to continue a result set.

      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).

      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:

    @@ -94,7 +95,7 @@ parameter-id-mask
  
    .. _def-start:

    start (also referred to as begin)

    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.

docs/source/endpoints/timeSeries_endpoints/shared_when_to_use.rst

-Original file line number
+Diff line change
@@ -0,0 +1,63 @@
+    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_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`.

docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -38,20 +38,50 @@ When to use
  
    .. csv-table:: GET /timeseries/profile/{location-id}/{parameter-id} - Endpoint Parameters

        :header: "Parameter", "Description", "Required"

        :widths: 20, 60, 15

        :header: "Parameter", "Description", "Required", "When to Use"

        :widths: 30, 40, 20, 65

        location-id,":ref:`def-location-id`","Yes"

        parameter-id,":ref:`def-parameter-id`","Yes"

        office,":ref:`def-office`",""

        location-id,":ref:`def-location-id`","Yes", ":ref:`when_location_id`"

        parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`"

        office,":ref:`def-office`","", ":ref:`when_office`"

    Examples

    --------

    - Fetch a profile for a location and parameter:

    .. code-block::

    1. | The user wants to retrieve the temperature profile at various depths:

       | (**parameter-id**) :code:`Depth-Temperature`

       |

       | for the RIVER-STATION1 location:

       | (**location-id**) :code:`RIVER-STATION1`

       |

       | but is unsure of which office to use. Query includes required path parameters, `location-id` and `parameter-id`.

       .. code-block:: bash

           GET /timeseries/profile/[location-id]/[parameter-id]

       .. code-block:: bash

           GET /timeseries/profile/RIVER-STATION1/Depth-Temperature

    2. The user reviews the results from the previous example query and decides to to narrow the search to the `HQ` office.

       Query remains the same:

       | (**parameter-id**) :code:`Depth-Temperature`

       |

       | (**location-id**) :code:`RIVER-STATION1`

       |

       | but adds the optional query parameter, `office`:

       | (**office**) :code:`HQ`

       .. code-block:: urlencoded

           GET /timeseries/profile/[location-id]/[parameter-id]?office=[office]

       .. code-block:: urlencoded

           GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ

        GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ

    See the consolidated API documentation: :doc:`/api-references`.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CDA-64: Updates to TimeSeries documentation examples #1543

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!