CDA-64: Updates to TimeSeries documentation examples

docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst

@@ -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:
 

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

@@ -38,21 +38,29 @@ 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", "To identify the specific location name associated with \
+    the desired profile, e.g. `STATION1`."
+    parameter-id,":ref:`def-parameter-id`","Yes", "To identify the specific parameter combination \
+    associated with the desired profile, e.g. `Flow-Evap`."
+    office,":ref:`def-office`","", "To limit results to a specific office, such as `SRL`."
 
 Examples
 --------
-- Fetch a profile for a location and parameter:
+- Retrieve a profile for the `LOC123` location and `Depth-Temperature` parameter for the `HQ` office:
 
-.. code-block::
+.. code-block:: urlencoded
 
     GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ
 
+- Retrieve a profile for the `RIVER-STATION1` location and `Depth-Temperature` parameter:
+
+.. code-block::
+
+    GET /timeseries/profile/RIVER-STATION1/Depth-Temperature
+
 See the consolidated API documentation: :doc:`/api-references`.
 
 .. include:: /_includes/feedback_button.rst

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

@@ -13,34 +13,89 @@ When to use
 
 
 .. csv-table:: GET /timeseries/profile-instance{location-id}/{parameter-id}/{version} - Endpoint Parameters
-    :header: "Parameter", "Description", "Required"
-    :widths: 20, 60, 15
-
-    location-id,":ref:`def-location-id`","Yes"
-    parameter-id,":ref:`def-parameter-id`","Yes"
-    version,"`CWMS database - version <https://cwms-database.readthedocs.io/en/latest/naming.html#versions>`_","Yes"
-    office,":ref:`def-office`","Yes"
-    timezone,":ref:`def-timezone`",""
-    version-date,":ref:`def-version-date`",""
-    unit,":ref:`def-unit`","Yes"
-    start-time-inclusive,"Resulting data includes data from the exact start time of the time window (true/false).",""
-    end-time-inclusive,"Resulting data includes data from the exact end of the time window (true/false).",""
-    previous,"Include the previous time window of the time series profile instance (true/false).",""
-    next,"Include the next time window of the time series profile instance (true/false).",""
-    max-version,"Use the most recent version date (true/false). Only for time series utilizing dates in the version.",""
-    start,":ref:`def-start`","Yes"
-    end, ":ref:`def-end`", "Yes"
-    page,":ref:`def-page`",""
-    page-size,":ref:`def-page-size`",""
+    :header: "Parameter", "Description", "Required", "When to Use"
+    :widths: 30, 50, 20, 60
+
+    location-id,":ref:`def-location-id`","Yes", "To specify the name of the location associated with \
+    the profile instance."
+    parameter-id,":ref:`def-parameter-id`","Yes", "To specify the parameter relationship described \
+    by the desired profile instance."
+    version,"`CWMS database - version <https://cwms-database.readthedocs.io/en/latest/naming.html#versions>`_
+    This is a text value that is independent of the version date.","Yes", "To specify the desired version of the \
+    profile instance provided when storing the instance."
+    office,":ref:`def-office`","Yes", "To specify the office associated with the profile instance."
+    timezone,":ref:`def-timezone`","", "Use to convert the resulting data into a specific timezone, such as \
+    `America/Los_Angeles`."
+    version-date,":ref:`def-version-date`","", "To specify a desired version date associated with the profile \
+    instance. Not including this parameter will result in the response containing the instance with the most recent \
+    version date"
+    unit,":ref:`def-unit`
+    Units must be compatible with desired instance data. For this endpoint, they are comma separated for the two \
+    associated parameters, e.g. `m,F` for the `Depth-Temperature` parameter","Yes", "To specify the \
+    desired units for the instance response."
+    start-time-inclusive,"Resulting data includes data from the exact start time of the time window (true/false).","\
+    ", "To choose whether data points on the configured start-time parameter will be included in the response, \
+    such as for the purpose of calculating averages for a time window."
+    end-time-inclusive,"Resulting data includes data from the exact end of the time window (true/false).","", "To \
+    choose whether data points on the configured end-time parameter will be included in the response, such as for the \
+    purpose of calculating averages for a time window."
+    previous,"Include the previous time window of the time series profile instance (true/false).","", "To include data \
+    starting at the closest timestamp before the specified `start` date and time."
+    next,"Include the next time window of the time series profile instance (true/false).","", "To include data up to \
+    the closest timestamp after the specified `end` parameter date and time."
+    max-version,"Use the most recent version date (true/false). Only for time series utilizing dates in the version.","\
+    ", "To retrieve the instance with the latest version date (true), or to use in combination with a specific \
+    version date (false) by providing a date using the version-date parameter."
+    start,":ref:`def-start`","Yes", "To define the beginning of the time window for the desired results."
+    end, ":ref:`def-end`", "Yes", "To define the end of the time window for the desired results."
+    page,":ref:`def-page`","", "To specify a page of the results for queries that return more results that can \
+    fit in one page."
+    page-size,":ref:`def-page-size`","", "To limit the number of results provided in a single response, \
+    for the purpose of quicker or more manageable responses."
 
 
 Examples
 --------
-- Fetch a specific instance version:
+- Fetch the most recent instance for the `LOC123` location, `Depth-Temperature` parameter, units of meters \
+  (m) and Fahrenheit (F), `CWMS` version, and `HQ` office, with a time window of \
+  `2025-10-01T06:00:00Z` to `2026-01-21T18:00:00Z`:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&unit=m,F
+
+- Fetch a specific instance version for the `LOC123` location, `Depth-Temperature` parameter, units of meters \
+  (m) and Fahrenheit (F), `CWMS` version, and `HQ` office, with a version date of \
+  `2026-01-01T12:00:00Z` and a time window of `2025-10-01T06:00:00Z` to `2026-01-21T18:00:00Z`:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&unit=m,F&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&version-date=2026-01-01T12:00:00Z&max-version=False
+
+- Fetch the most recent instance for the `LOC123` location, `Depth-Temperature` parameter, units of meters \
+  (m) and Fahrenheit (F), `CWMS` version, and `HQ` office, with the latest version date and a time window of \
+  `2025-10-01T06:00:00Z` to `2026-01-21T18:00:00Z`:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&unit=m,F&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&max-version=True
+
+- Fetch the most recent instance for the `LOC123` location, `Depth-Temperature` parameter, units of meters \
+  (m) and Fahrenheit (F), timezone of `America/Los_Angeles`, `CWMS` version, and `HQ` office, with an inclusive \
+  time window of `2025-10-01T06:00:00Z` to `2026-01-21T18:00:00Z` and a result size of 15:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&unit=m,F&page-size=15&timezone=America/Los_Angeles&start-time-inclusive=True&end-time-inclusive=True
+
+- Fetch the most recent instance for the `LOC123` location, `Depth-Temperature` parameter, units of meters \
+  (m) and Fahrenheit (F), timezone of `UTC`, `CWMS` version, and `HQ` office, with a \
+  time window of `2025-10-01T06:00:00Z` to `2026-01-21T17:00:00Z` including the single time step of data after the \
+  end date and a result size of 15:
 
-.. code-block:: sql
+.. code-block:: urlencoded
 
-     GET /timeseries/profile-instance/LOC123/Flow/2?office=HQ
+     GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-21T17:00:00Z&unit=m,F&page-size=15&timezone=UTC&next=True
 
 
 See the consolidated API documentation: :doc:`/api-references`.

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

@@ -28,14 +28,18 @@ When to use
 - Find the latest or a specific version of an instance
 
 
-.. csv-table:: GET /timeseries/profile-instanceEndpoint Parameters
-    :header: "Parameter", "Description", "Required"
-    :widths: 20, 60, 15
-
-    version-mask,"A regular expression used to filter the version field for time series retrieval.",""
-    office-mask,":ref:`def-office-mask`",""
-    location-mask,":ref:`def-location-mask`",""
-    parameter-id-mask,":ref:`def-parameter-id-mask`",""
+.. csv-table:: GET /timeseries/profile-instance - Endpoint Parameters
+    :header: "Parameter", "Description", "Required", "When to Use"
+    :widths: 30, 50, 20, 60
+
+    version-mask,"A regular expression used to filter the version field for time series retrieval.","", "To \
+    limit results to a specific version, such as `CWMS`."
+    office-mask,":ref:`def-office-mask`","", "To limit results to a specific office or pattern, such as `LRL` or \
+    `MV*`."
+    location-mask,":ref:`def-location-mask`","", "To limit results to a specific location or pattern, such as \
+    `RIVER2` or `STATION*`."
+    parameter-id-mask,":ref:`def-parameter-id-mask`","", "To limit results to a specific parameter or pattern \
+    such as `Depth-Temperature` or `Depth*`."
 
 .. note::
         Detailed documentation for Regex usage in CDA is currently in development and will be available at
@@ -44,11 +48,23 @@ When to use
 
 Examples
 --------
-- List instances for a parameter at locations starting with ABC:
+- List all available instances
+
+.. code-block::
+
+    GET /timeseries/profile-instance
+
+- List instances for all offices starting with `MV`
+
+.. code-block:: urlencoded
+
+    GET /timeseries/profile-instance?office-mask=MV*
+
+- List instances for a parameter starting with `Flow` at locations starting with `ABC` for the `HQ` office:
 
-.. code-block:: sql
+.. code-block:: urlencoded
 
-     GET /timeseries/profile-instance?location-mask=ABC*&parameter-id-mask=Flow*&office=HQ
+     GET /timeseries/profile-instance?location-mask=ABC*&parameter-id-mask=Flow*&office-mask=HQ
 
 
 See the consolidated API documentation: :doc:`/api-references`.

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

@@ -15,20 +15,22 @@ When to use
 
 
 .. csv-table:: GET /timeseries/profile-parser{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, 60
 
-    location-id,":ref:`def-location-id`","Yes"
-    office,":ref:`def-office`","Yes"
-    parameter-id,":ref:`def-parameter-id`","Yes"
+    location-id,":ref:`def-location-id`","Yes", "To specify the location name associated with the desired profile \
+    parser."
+    office,":ref:`def-office`","Yes", "To specify the office associated with the desired parser, e.g. `SPK`."
+    parameter-id,":ref:`def-parameter-id`","Yes", "To specify the parameter described by the profile parser, e.g. \
+    `Depth-Temperature`."
 
 Examples
 --------
-- Get the parser for a specific profile:
+- Get the parser for a specific profile with the office `LRL`, location name `STREAM12`, and parameter `Flow-Evap`:
 
-.. code-block:: sql
+.. code-block:: urlencoded
 
-     GET /timeseries/profile-parser/LOC123/Flow?office=HQ
+     GET /timeseries/profile-parser/STREAM12/Flow-Evap?office=LRL
 
 
 See the consolidated API documentation: :doc:`/api-references`.

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

@@ -20,21 +20,35 @@ When to use
 
 
 .. csv-table:: GET /timeseries/profile - Endpoint Parameters
-    :header: "Parameter", "Description", "Required"
-    :widths: 20, 60, 15
+    :header: "Parameter", "Description", "Required", "When to Use"
+    :widths: 30, 40, 20, 60
 
-    office-mask,":ref:`def-office-mask`",""
-    location-mask,":ref:`def-location-mask`",""
-    parameter-id-mask,":ref:`def-parameter-id-mask`",""
+    office-mask,":ref:`def-office-mask`","", "To limit results to a specific office or pattern, such as `LRL` or `MV*`."
+    location-mask,":ref:`def-location-mask`","", "To limit results to a specific location or pattern, such as `BASIN1`\
+    or `STATION*`."
+    parameter-id-mask,":ref:`def-parameter-id-mask`","", "To limit results to a specific parameter or pattern, such \
+    as `Depth-Temperature` or `*-Temperature`."
 
 
 Examples
 --------
-- List available parsers for your office:
+- List all available parsers:
 
-.. code-block:: sql
+.. code-block::
 
-     GET /timeseries/profile-parser?office=HQ
+     GET /timeseries/profile-parser
+
+- List available parsers for the `HQ` office:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-parser?office-mask=HQ
+
+- List available parsers with the `Area-Evap` parameter for locations ending with `BASIN`:
+
+.. code-block:: urlencoded
+
+     GET /timeseries/profile-parser?parameter-id-mask=Area-Evap&location-mask=*BASIN
 
 
 See the consolidated API documentation: :doc:`/api-references`.

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

@@ -27,24 +27,48 @@ When to use
 
 
 .. csv-table:: GET /timeseries/profile - Endpoint Parameters
-    :header: "Parameter", "Description", "Required"
-    :widths: 20, 60, 15
+    :header: "Parameter", "Description", "Required", "When to Use"
+    :widths: 30, 40, 20, 65
 
-    location-mask,":ref:`def-location-mask`",""
-    office-mask,":ref:`def-office-mask`",""
-    page,":ref:`def-page`",""
-    page-size,":ref:`def-page-size`",""
-    parameter-id-mask,":ref:`def-parameter-id-mask`",""
+    location-mask,":ref:`def-location-mask`","", "To limit results to a specific location or pattern, \
+    for example limiting results to locations containing `River`."
+    office-mask,":ref:`def-office-mask`","", "To limit results to a specific office, such as `SPK`, or to offices \
+    starting with `S` using `S*`."
+    page,":ref:`def-page`","", "To reach a specific page in the set of results to get results beyond the previous \
+    page"
+    page-size,":ref:`def-page-size`","", "To set the limit of results in one response, 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."
+    parameter-id-mask,":ref:`def-parameter-id-mask`","", "To limit results to a specific parameter or pattern, \
+    such as limiting results to those associated with `Elev`"
 
 
 Examples
 --------
-- List profiles for locations starting with ABC:
+- List profiles at the `HQ` office for locations starting with `ABC`:
 
-.. code-block:: sql
+.. code-block:: urlencoded
 
      GET /timeseries/profile?location-mask=ABC*&office=HQ
 
+- List profiles for offices starting with `S` for the elevation parameter:
+
+.. code-block:: urlencoded
+
+    GET /timeseries/profile?office-mask=S*&parameter-id-mask=Elev
+
+- List profiles at the `SPK` office with 100 results per page
+
+.. code-block:: urlencoded
+
+    GET /timeseries/profile?office-mask=SPK&page-size=100
+
+- List the following page of profiles for the above query for a next-page value of `t!qqoLun283` provided in the \
+  previous response
+
+.. code-block:: urlencoded
+
+    GET /timeseries/profile?office-mask=SPK&page-size=100&page=t!qqoLun283
+
 
 See the consolidated API documentation: :doc:`/api-references`.