CDA-64: Time Series Endpoint Documentation Updates

docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst

@@ -14,17 +14,19 @@ endpoint documentation.
 .. _def-end:
 
 end
-  End date/time for the time series data to stop.
+  End date/time for the time series data to stop. The format for this field is ISO 8601 extended,
+  with optional offset and timezone, i.e., 'YYYY-MM-dd'T'hh:mm:ss[Z'['VV']']', e.g., '2021-06-10T13:00:00-07:00', '2025-10-25T12:25:00Z'.
 
 .. _def-location-id:
 
 location-id
-  Description pending.
+    https://cwms-database.readthedocs.io/en/latest/naming.html#locations
+    https://cwms-database.readthedocs.io/en/latest/locations.html#overview
 
 .. _def-location-mask:
 
 location-mask
-  Description pending.
+  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: `/cwms-data/regexp`.
 
 .. _def-office:
 
@@ -34,7 +36,7 @@ office
 .. _def-office-mask:
 
 office-mask
-  Description pending.
+  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.: `/cwms-data/regexp`
 
 .. _def-page:
 
@@ -49,17 +51,17 @@ page-size
 .. _def-parameter-id:
 
 parameter-id
-  Description pending.
+  The text representation of the data parameter represented by the desired time series data, describing "what" is measured. Examples include "Flow", "Stage", "Elev", etc.
 
 .. _def-parameter-id-mask:
 
 parameter-id-mask
-  Description pending.
+  A regular expression used to filter the parameter of the queried time series data. See the Regex documentation for more information on usage: `/cwms-data/regexp`.
 
 .. _def-timezone:
 
 timezone
-  Description pending.
+  The timezone to use for retrieved time data. Examples include "UTC", "America/Los_Angeles", etc.
 
 .. _def-unit:
 
@@ -69,4 +71,5 @@ unit
 .. _def-version-date:
 
 version-date
-  Description pending.
+  Common information that is captured in the version of the time series includes: the data source, telemetry method, the quality of the data or the state of the data processing, dates for the range of the data, time stamp if the data is daily, models used to generate the data, an indication of whether the data is observed or derived from observed or forecasted or study data, etc.
+  Segmenting the version is an attempt to provide some structure for the information that is typically captured in this free form text portion of the time-series identifier. Limited to 32 characters.

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

@@ -0,0 +1,37 @@
+TimeSeries — GET /timeSeries/profile/{location-id}/{parameter-id}
+===================================================================
+
+.. csv-table:: Parameters
+    :header: "Parameter", "Description", "Required"
+    :widths: 20, 60, 15
+
+    location-id,":ref:`def-location-id`","Yes"
+    parameter-id,":ref:`def-parameter-id`","Yes"
+    office,":ref:`def-office`",""
+
+
+What it does
+------------
+Retrieve a specific time series profile for a given location and parameter.
+
+"Profile" data allows the storage of several values for each time. It is essentially a marriage of time series data and paired data. It is called "Profile" because its most common use is a time series temperature profile for lakes. For profile data, there is an independent variable (depths) and a set of dependent variables (temperatures at those depths over time.) The independent variable (depths) describes the dependent variables and is NOT associated with a time. The C part must contain the independent variable name followed by a dash ("-") and then the independent variable name. For lake profile, this would be "/Depth-Temperature/".
+The number of independent variables must be consistent for the entire data set; for example, if you have 10 depth readings, you must have 10 depth readings for the entire data set (although some may be marked as missing). You must have a independent variable set, even if not used. If you wanted to store multiple time series values, you would still need to have a independent variable array, although it may contain all zeros.
+Profile data may have quality and notes, as other time series conventions. Profile data may be regular-interval or irregular-interval; minute (default) granularity or second granularity.
+
+When to use
+-----------
+- You wish to retrieve a specific time series profile and already know the location and parameter.
+
+
+Examples
+--------
+- Fetch a profile for a location and parameter:
+
+.. code-block::
+
+     GET /timeseries/profile/LOC123/Flow?office=HQ
+
+
+See the consolidated API documentation: :doc:`/api-references`.
+
+.. include:: /_includes/feedback_button.rst

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

@@ -0,0 +1,48 @@
+TimeSeries — GET /timeSeries/profile-instance/{location-id}/{parameter-id}/{version}
+======================================================================================
+
+What it does
+------------
+Fetch a specific versioned profile instance for a location and parameter.
+
+When to use
+-----------
+- You wish to retrieve a specific instance of a time series profile and know the version, parameter, and location.
+
+
+.. csv-table:: /timeseries/profile-instance{location-id}/{parameter-id}/{version} Endpoint Parameters
+    :header: "Parameter", "Description", "Required"
+    :widths: 20, 60, 15
+
+    end, ":ref:`def-end`", "Yes"
+    end-time-inclusive,"Whether the resulting data set should include data occurring at the moment of the end of the time window. Acceptable values are 'true' or 'false'.",""
+    location-id,":ref:`def-location-id`","Yes"
+    max-version,"Whether to use the most recent version date in the response. Only applies to time series that utilize dates in the version field. Acceptable values are 'true' or 'false'.",""
+    next,"Whether to include the next time window of the time series profile instance.",""
+    office,":ref:`def-office`","Yes"
+    page,":ref:`def-page`",""
+    page-size,":ref:`def-page-size`",""
+    parameter-id,":ref:`def-parameter-id`","Yes"
+    previous,"Whether to include the previous time window of the time series profile instance. Acceptable values are 'true' or 'false'.",""
+    start,"Specifies the date and time for the start of the time window for data to be included in the response.
+            The format for this field is ISO 8601 extended, with optional offset and timezone,
+            i.e., 'YYYY-MM-dd'T'hh:mm:ss[Z'['VV']']', e.g., '2021-06-10T13:00:00-07:00', '2025-10-25T12:25:00Z'.","Yes"
+    start-time-inclusive,"Whether the resulting data set should include data occurring at the moment of the beginning of the time window. Acceptable values are 'true' or 'false'.",""
+    timezone,":ref:`def-timezone`",""
+    unit,"(Deprecated, prefer 'units') 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.","Yes"
+    version,"https://cwms-database.readthedocs.io/en/latest/naming.html#versions","Yes"
+    version-date,":ref:`def-version-date`",""
+
+Examples
+--------
+- Fetch a specific instance version:
+
+.. code-block:: sql
+
+     GET /timeseries/profile-instance/LOC123/Flow/2?office=HQ
+
+
+See the consolidated API documentation: :doc:`/api-references`.
+
+.. include:: /_includes/feedback_button.rst

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

@@ -5,6 +5,20 @@ What it does
 ------------
 Enumerate profile instances (actual profile datasets) and their versions. Use this to discover which instances exist before fetching a specific one.
 
+A profile instance is data recorded by a single cycle of the sensor as it
+sweeps through its range of the key parameter, including the timestamps of each reading. The
+profile instance data stored in the CWMS database will be a subset of the data recorded if the
+recorded data include parameters that aren’t included in the profile definition.
+
+Profile instances are keyed to location, key parameter, version identifier, first recorded time, and version date.
+This means that:
+- Multiple first recorded times can exist for a single location, key parameter, version
+identifier, and version date combination.
+- Multiple version identifiers can exist for a single location, key parameter, first recorded
+time, and version date combination.
+- Multiple version dates can exist for a single location, key parameter, version identifier,
+and first recorded time combination
+
 When to use
 -----------
 - Browse available instances by location/parameter
@@ -15,7 +29,7 @@ When to use
     :header: "Parameter", "Description", "Required"
     :widths: 20, 60, 15
 
-    version-mask,"",""
+    version-mask,"A regular expression used to filter the version field for time series retrieval. See the Regex documentation for more information on usage.",""
     office-mask,":ref:`def-office-mask`",""
     location-mask,":ref:`def-location-mask`",""
     parameter-id-mask,":ref:`def-parameter-id-mask`",""

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

@@ -5,6 +5,8 @@ What it does
 ------------
 Retrieve parser information associated with a specific profile identified by location and parameter.
 
+Profile parsers can be defined to enable storage of profile instance data directly from text output from data loggers.
+
 When to use
 -----------
 - You need the parser used for a specific profile to understand how values are interpreted
@@ -14,9 +16,9 @@ When to use
     :header: "Parameter", "Description", "Required"
     :widths: 20, 60, 15
 
-    location-id,":ref:`def-location-id`",""
-    office,":ref:`def-office`",""
-    parameter-id,":ref:`def-parameter-id`",""
+    location-id,":ref:`def-location-id`","Yes"
+    office,":ref:`def-office`","Yes"
+    parameter-id,":ref:`def-parameter-id`","Yes"
 
 Examples
 --------

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

@@ -5,9 +5,17 @@ What it does
 ------------
 List or inspect available profile parsers (the logic that interprets profile data formats).
 
+Profile parsers hold information about how to parse text output from data
+loggers. Although parameter values for profile instance data are stored in CWMS time series,
+the profile data are not delivered in the most standard way for CWMS time series: GOES
+transmissions that decoded by third-party software and either stored directly to the database or
+encoded as SHEF to be processed by CWMS data stream processes. In addition, profiles consist
+of identifiable instances instead of a continuous time series. Profile parsers allow storing of
+profile instances by providing the instance text as exported from a data logger.
+
 When to use
 -----------
-- Discover parser options before requesting a specific profile parser by IDs
+- Discover available existing parsers before requesting a specific profile parser by ID
 
 
 .. csv-table:: /timeseries/profile Endpoint Parameters

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

@@ -3,11 +3,22 @@ TimeSeries — GET /timeSeries/profile
 
 What it does
 ------------
-List or discover available time series profiles. Use this to see what profiles exist before requesting a specific profile by IDs.
+List or discover available time series profiles. Use this to see what profiles exist before requesting a specific profile by ID.
+
+CWMS database time series profiles are collections of time stamped values for a set of parameters that
+are associated with a specific location and key parameter. The proximate purpose is to facilitate the
+storage of depth-keyed profiles for water quality parameters in reservoirs, but they may be useful for
+storing other hydrometeorological profile information such as height-keyed meteorological profiles. The
+time stamped values are stored as normal CWMS time series. The CWMS time series for a specific
+location and parameter will hold values for all profile instances <./timeSeries-profile-instance> for that location/key
+parameter/version identifier combination.
+
+Profile definitions are keyed to the combination of location and key parameter. That is, only one
+profile definition may exist for each location, key parameter combination.
 
 When to use
 -----------
-- Inventory the profiles available for your office
+- Catalog the profiles available for your office
 - Filter by location or parameter to narrow results
 
 

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

@@ -4,6 +4,7 @@ TimeSeries — GET /timeSeries/recent
 What it does
 ------------
 Return the most recent value(s) from one or more time series without downloading a historical range.
+Retrieves time series data between 28 days prior to and 14 days after the current date.
 
 When to use
 -----------
@@ -15,9 +16,9 @@ When to use
     :header: "Parameter", "Description", "Required"
     :widths: 20, 60, 15
 
-    category-id,"",""
-    group-id,"",""
-    ts-ids,"",""
+    category-id," The text identifier for the time series category defined in the CWMS database for a specific time series.",""
+    group-id,"The text identifier of the time series group defined in the CWMS database for a specific time series.",""
+    ts-ids,"A comma separated list of timeseries identifiers to be included in the response. Example: 'Location.Elev.Inst.0.1Day.lrgs,Location2.Elev.Inst.0.12Hour.lrgs'.",""
     unit-system,"SI or EN or other",""
     office,":ref:`def-office`",""
 

docs/source/endpoints/timeSeries_endpoints/timeSeries.rst

@@ -19,19 +19,22 @@ When to use
     :header: "Parameter", "Description", "Required"
     :widths: 20, 60, 15
 
-    begin, "also start. need to verify and add to shared def.", ""
-    datum, "", ""
+    begin, "Specifies the date and time for the start of the time window for data to be included in the response.
+            The format for this field is ISO 8601 extended, with optional offset and timezone,
+            i.e., 'YYYY-MM-dd'T'hh:mm:ss[Z'['VV']']', e.g., '2021-06-10T13:00:00-07:00', '2025-10-25T12:25:00Z'.", ""
+    datum, "The standardized reference system used for either vertical or horizontal measurements.
+            Examples include "NAVD88", "NGVD29", "LOCAL", etc.", ""
     end, ":ref:`def-end`", ""
-    format, "", ""
-    include-entry-date, "", ""
-    name(required), "", "Yes"
-    office, "see :ref:`def-office`", ""
+    format, "The desired response format. Usage differs between endpoints. See the Legacy Format Responses documentation page for more information.", ""
+    include-entry-date, "Whether to include in the response for a data retrieval the timestamps at which each data point was entered into the CWMS database. Acceptable values are 'true' or 'false'.", ""
+    name(required), "The text representation of the unique time series identifier.", "Yes"
+    office, "see :ref:`def-office`", "Format Dependent"
     page, ":ref:`def-page`", ""
     page-size, ":ref:`def-page-size`", ""
     timezone, ":ref:`def-timezone`", ""
-    trim, "", ""
-    unit, "deprecated, prefer units", ""
-    units, "SI or EN or other. Need to verify", ""
+    trim, "Specifies whether to trim missing values from the beginning and end of the retrieved values. Acceptable values are 'true' or 'false'.", ""
+    unit, ":ref:`def-unit`", ""
+    units, "https://cwms-database.readthedocs.io/en/latest/naming.html#units", ""
     version-date, ":ref:`def-version-date`", ""
 
 
@@ -42,7 +45,7 @@ Examples
 
 .. code-block:: sql
 
-     GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=now-24H&unit=m3/s
+     GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&unit=m3/s
 
 
 See the consolidated API documentation: :doc:`/api-references`.