diff --git a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst b/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst index 9e70ac65b..53ed9bf16 100644 --- a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst +++ b/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. \ No newline at end of file + 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. \ No newline at end of file diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst new file mode 100644 index 000000000..005b6bc87 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byIDs.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byIDs.rst deleted file mode 100644 index 453534111..000000000 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byIDs.rst +++ /dev/null @@ -1,33 +0,0 @@ -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`","" - parameter-id,":ref:`def-parameter-id`","" - office,":ref:`def-office`","" - - -What it does ------------- -Retrieve a specific time series profile for a given location and parameter. - -When to use ------------ -- You know the location and parameter and want the profile details - - -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 \ No newline at end of file diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst new file mode 100644 index 000000000..ae58fbe22 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byIDs.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byIDs.rst deleted file mode 100644 index d8658fc41..000000000 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byIDs.rst +++ /dev/null @@ -1,45 +0,0 @@ -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 know the exact version you need to retrieve - - -.. csv-table:: /timeseries/profile-instance{location-id}/{parameter-id}/{version} Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 - - end, ":ref:`def-end`", "" - end-time-inclusive,"","" - location-id,":ref:`def-location-id`","" - max-version,"","" - next,"","" - office,":ref:`def-office`","" - page,":ref:`def-page`","" - page-size,":ref:`def-page-size`","" - parameter-id,":ref:`def-parameter-id`","" - previous,"","" - start,"also begin. need to verify if duplicate def","" - start-time-inclusive,"","" - timezone,":ref:`def-timezone`","" - unit,"deprecated, prefer units/unit-system. need to verify","" - version,"","" - 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 \ No newline at end of file diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst index 58a87a44b..7f8be5b91 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst +++ b/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`","" diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byIDs.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst similarity index 76% rename from docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byIDs.rst rename to docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst index d9eee5556..abb1a73c9 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byIDs.rst +++ b/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 -------- diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst index eaab6a423..61c49bd79 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst +++ b/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 diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst index 887154f84..2059ed350 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/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 diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst index 7231b7b2d..22cfd998b 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst +++ b/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`","" diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index a6bce8a97..89961fb4b 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/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`. diff --git a/docs/source/parameters/timeSeries_params/allTSParameters.rst b/docs/source/parameters/timeSeries_params/allTSParameters.rst index d7df4959f..1a134cd63 100644 --- a/docs/source/parameters/timeSeries_params/allTSParameters.rst +++ b/docs/source/parameters/timeSeries_params/allTSParameters.rst @@ -7,41 +7,77 @@ This page serves as a reference for all parameters used across the TimeSeries en building the documentation and then be removed later. - 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'. - category-id + - The text identifier for the time series category defined in the CWMS database for a specific time series. - datum + - The standardized reference system used for either vertical or horizontal measurements. + Examples include "NAVD88", "NGVD29", "LOCAL", etc. - end + - Specifies the date and time for the end 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'. - 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'. - format + - The desired response format. Usage differs between endpoints. See the Legacy Format Responses documentation page for more information. - group-id + - The text identifier of the time series group defined in the CWMS database for a specific time series. - 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'. - location-id: - https://cwms-database.readthedocs.io/en/latest/naming.html#locations - https://cwms-database.readthedocs.io/en/latest/locations.html#overview - location-mask + - A regular expression used to filter on the text identifier for the location assigned to a time series. See the Regex documentation page for more information on usage: `/cwms-data/regexp`. - 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'. - name + - The text representation of the unique time series identifier. - next + - Whether to include the next time window of the time series profile instance. - office: - https://cwms-database.readthedocs.io/en/latest/naming.html#offices - 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: `/cwms-data/regexp`. - page + - Unique text page token for paginated endpoints. Use with next/previous links to continue a result set that is larger than the defined page size. - page-size + - A numerical value to define the maximum number of results included in a single page. A default value is defined if not provided. Example: '25'. - parameter-id + - The text representation of the data parameter represented by the desired time series data, describing "what" is measured. Examples include "Flow", "Stage", "Elev", etc. - 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: `/cwms-data/regexp`. - 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'. - 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 + - The timezone to use for retrieved time data. Examples include "UTC", "America/Los_Angeles", etc. - trim + - Specifies whether to trim missing values from the beginning and end of the retrieved values. Acceptable values are 'true' or 'false'. - 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 + - (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. - unit-system + - The unit system to convert the response data into. Available unit systems are 'SI' or 'EN'. - units: - https://cwms-database.readthedocs.io/en/latest/naming.html#units - version: - https://cwms-database.readthedocs.io/en/latest/naming.html#versions - version-date + - 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. - version-mask + - A regular expression used to filter the version field for time series retrieval. See the Regex documentation for more information on usage: `/cwms-data/regexp`. Reference values for shared parameters across TimeSeries endpoints for ease of access: