From 7952f948d7c8b72d3e23c1d82bad4c5c6d3f9c31 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 20 Jan 2026 16:42:13 -0800 Subject: [PATCH 1/6] Initial update to timeSeries.rst documentation --- .../timeSeries_endpoints/timeSeries.rst | 52 ++++++++++++------- 1 file changed, 33 insertions(+), 19 deletions(-) diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index d7f0a0aaa..076ed5607 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -18,24 +18,37 @@ When to use .. csv-table:: GET /timeseries - Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 - - begin, ":ref:`def-start`", "" - datum, "The standardized reference system used for either vertical measurements. - Examples: NAVD88, NGVD29, LOCAL, etc.", "" - end, ":ref:`def-end`", "" - format, "The desired response format. Usage differs between endpoints.", "" - include-entry-date, "Include timestamps for when each data point was added to the CWMS database (true/false).", "" - name(required), "The text representation of the unique time series identifier.", "Yes" - office, "see :ref:`def-office`", "" - page, ":ref:`def-page`", "" - page-size, ":ref:`def-page-size`", "" - timezone, ":ref:`def-timezone`", "" - trim, "Trim missing values from the beginning and end of the retrieved values (true/false).", "" - unit, ":ref:`def-unit`", "" - units, "`CWMS database - units `_", "" - version-date, ":ref:`def-version-date`", "" + :header: "Parameter", "Description", "Required", "Reason for Use" + :widths: 20, 60, 15, 60 + + begin, ":ref:`def-start`", "", "Use this to limit the results to be after a specified date and time." + datum, "The standardized reference system used for either vertical measurements. \ + Examples: NAVD88, NGVD29, LOCAL, etc.", "", "Use this to retrieve measurements in a specified system." + end, ":ref:`def-end`", "", "Use this to limit the results to be before a specified date and time." + format, "The desired response format. Usage differs between endpoints. See the legacy format page (available in a \ + future release) for details: https://cwms-data.usace.army.mil/cwms-data/legacy-format", "", "Use this \ + to force the format provided in the response." + include-entry-date, "Include timestamps for when each data point was added to the CWMS database (true/false).", "\ + ", "Use this to determine when each time series data point was stored." + name(required), "The text representation of the unique time series identifier.", "Yes", "This is required to \ + differentiate the specific time series data you desire to retrieve." + office, "see :ref:`def-office`", "", "Use this 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." + page, ":ref:`def-page`", "", "Use this parameter with the value provided by a previous query to get results that \ + were not able to fit in the previous page of results." + page-size, ":ref:`def-page-size`", "", "Use this to specify the number of results you wish to receive \ + from a single query. Further results may be available on a subsequent page of the same length." + timezone, ":ref:`def-timezone`", "", "Use this to retrieve data points in a timezone that works best with \ + your use case, such as your local timezone." + trim, "Trim missing values from the beginning and end of the retrieved values (true/false).", "", "Use \ + this parameter to leave out missing values to get only the stored values of the time series data set." + unit, ":ref:`def-unit`", "", "You should not use this parameter, and instead use the 'units' parameter below." + units, "`CWMS database - units `_", "", "Use \ + this parameter to convert the retrieved values into a desired unit, such as retrieving elevation data \ + in feet (ft) instead of meters (m)." + version-date, ":ref:`def-version-date`", "", "Use this parameter to limit results to a specific version, \ + such as when multiple versions of a time series exist with different associated forecast dates." .. note:: @@ -45,7 +58,8 @@ When to use Examples ---------- -- Latest 24 hours in metric units: +- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second + starting on October 12, 2025 at 12:35PM. .. code-block:: sql From 52e63c01a5f52b10baed5fea07d5de66b18d5dc8 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 20 Jan 2026 17:14:09 -0800 Subject: [PATCH 2/6] Update to timeSeries-profile.rst documentation --- .../timeSeries-profile.rst | 21 ++++++++++++------- .../timeSeries_endpoints/timeSeries.rst | 2 +- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst index 037eef258..ca5e02d49 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst @@ -27,19 +27,24 @@ When to use .. csv-table:: GET /timeseries/profile - Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 + :header: "Parameter", "Description", "Required", "Reason for Use" + :widths: 20, 60, 15, 60 - 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`","", "Use to limit results to a specific location or pattern, \ + for example limiting results to locations containing `River`." + office-mask,":ref:`def-office-mask`","", "Use to limit results to a specific office, such as `SPK`, or to offices \ + starting with `S` using `S*`." + page,":ref:`def-page`","", "Use to reach a specific page in the set of results to get results beyond the previous \ + page" + page-size,":ref:`def-page-size`","", "Use 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`","", "Use 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 diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index 076ed5607..d3dd83902 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -58,7 +58,7 @@ When to use Examples ---------- -- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second +- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second \ starting on October 12, 2025 at 12:35PM. .. code-block:: sql From d5a8d0016ac5aafb193e8d1b749e4cf542d2b725 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Wed, 21 Jan 2026 12:01:22 -0800 Subject: [PATCH 3/6] Update to time series documentation, some examples still in progress. --- .../shared_definitions.rst | 5 +- .../timeSeries-profile-byID.rst | 22 +++-- .../timeSeries-profile-instance-byID.rst | 69 ++++++++++----- .../timeSeries-profile-instance.rst | 38 ++++++--- .../timeSeries-profile-parser-byID.rst | 18 ++-- .../timeSeries-profile-parser.rst | 30 +++++-- .../timeSeries-profile.rst | 35 ++++++-- .../timeSeries-recent.rst | 36 +++++--- .../timeSeries_endpoints/timeSeries.rst | 84 +++++++++++++------ 9 files changed, 234 insertions(+), 103 deletions(-) diff --git a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst b/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst index 9896a107d..564821d8a 100644 --- a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst +++ b/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: diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst index 7e50ce574..d105c0a2e 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst +++ b/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 \ 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 index b6e3d5228..a79bf763e 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst @@ -13,34 +13,59 @@ 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 `_","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 `_ + 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.","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).","", "" + 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.","\ + ", "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 version for the `LOC123` location, `Flow` parameter, `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/Flow-Evap/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&unit=__ + +- Fetch a specific instance version for the `LOC123` location, `Flow` parameter, `CWMS` version, and `HQ` office, with \ + a version date of `2026-01-01T12:00:00Z`: -.. code-block:: sql +.. code-block:: urlencoded - GET /timeseries/profile-instance/LOC123/Flow/2?office=HQ + GET /timeseries/profile-instance/LOC123/Flow-Evap/CWMS?office=HQ&unit=__&version-date=2026-01-01T12:00:00Z See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst index 6aeb695c8..3879c2f0b 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst +++ b/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*¶meter-id-mask=Flow*&office=HQ + GET /timeseries/profile-instance?location-mask=ABC*¶meter-id-mask=Flow*&office-mask=HQ See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst index 4ceb0a193..91a4792cd 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst +++ b/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`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst index 06cb144b3..0e795ddf9 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst +++ b/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`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst index ca5e02d49..1dada40d8 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst @@ -27,18 +27,18 @@ When to use .. csv-table:: GET /timeseries/profile - Endpoint Parameters - :header: "Parameter", "Description", "Required", "Reason for Use" - :widths: 20, 60, 15, 60 + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 40, 20, 65 - location-mask,":ref:`def-location-mask`","", "Use to limit results to a specific location or pattern, \ + 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`","", "Use to limit results to a specific office, such as `SPK`, or to offices \ + 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`","", "Use to reach a specific page in the set of results to get results beyond the previous \ + 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`","", "Use to set the limit of results in one response, such as for the purpose of \ + 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`","", "Use to limit results to a specific parameter or pattern, \ + 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`" @@ -46,10 +46,29 @@ Examples -------- - 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*¶meter-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`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst index f0371a439..a4da6c02e 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst @@ -14,24 +14,40 @@ When to use .. csv-table:: GET /timeseries/recent - Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 + :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.","" - 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" - ts-ids, "`CWMS database - time series `_","Only if group-id is NOT provided" - unit-system, "SI or EN, default: EN","" - office, ":ref:`def-office`","" + 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 `_","\ + 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`","", "To limit results to a specific office, such as `SPK`, perhaps for the purpose \ + of improving query response time." Examples -------- -- Latest values for a list of series IDs: +- Latest values for a list of series IDs (`STATION1.Flow.Inst.15Minutes.0.CWMS` and \ + `STATION2.Stage.Inst.15Minutes.0.CWMS`) in the Imperial unit system: - .. code-block:: sql +.. code-block:: urlencoded - GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit=ft + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN +- Latest values for time series in the `CALC3` group: + +.. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3 + +- Latest values for time series in the `CALC3` group and in the `COMPUTE` category for the `HQ` office: + +.. code-block:: urlencoded + + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index d3dd83902..22c25dff1 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -18,52 +18,82 @@ When to use .. csv-table:: GET /timeseries - Endpoint Parameters - :header: "Parameter", "Description", "Required", "Reason for Use" - :widths: 20, 60, 15, 60 + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 60, 20, 60 - begin, ":ref:`def-start`", "", "Use this to limit the results to be after a specified date and time." + begin, ":ref:`def-start`", "", "To limit the results to be after a specified date and time." datum, "The standardized reference system used for either vertical measurements. \ - Examples: NAVD88, NGVD29, LOCAL, etc.", "", "Use this to retrieve measurements in a specified system." - end, ":ref:`def-end`", "", "Use this to limit the results to be before a specified date and time." - format, "The desired response format. Usage differs between endpoints. See the legacy format page (available in a \ - future release) for details: https://cwms-data.usace.army.mil/cwms-data/legacy-format", "", "Use this \ + Examples: NAVD88, NGVD29, LOCAL, etc.", "", "To retrieve measurements in a specified system." + end, ":ref:`def-end`", "", "To limit the results to be before a specified date and time." + format, "The desired response format. Usage differs between endpoints. See note below.", "", "Use this \ to force the format provided in the response." include-entry-date, "Include timestamps for when each data point was added to the CWMS database (true/false).", "\ - ", "Use this to determine when each time series data point was stored." - name(required), "The text representation of the unique time series identifier.", "Yes", "This is required to \ + ", "To determine when each time series data point was stored." + name, "The text representation of the unique time series identifier.", "Yes", "To \ differentiate the specific time series data you desire to retrieve." - office, "see :ref:`def-office`", "", "Use this to limit your results to a specific office if there \ + office, "see :ref:`def-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." - page, ":ref:`def-page`", "", "Use this parameter with the value provided by a previous query to get results that \ - were not able to fit in the previous page of results." - page-size, ":ref:`def-page-size`", "", "Use this to specify the number of results you wish to receive \ + page, ":ref:`def-page`", "", "To get results that were not able to fit in the previous page of results." + page-size, ":ref:`def-page-size`", "", "To specify the number of results you wish to receive \ from a single query. Further results may be available on a subsequent page of the same length." - timezone, ":ref:`def-timezone`", "", "Use this to retrieve data points in a timezone that works best with \ + timezone, ":ref:`def-timezone`", "", "To retrieve data points in a timezone that works best with \ your use case, such as your local timezone." - trim, "Trim missing values from the beginning and end of the retrieved values (true/false).", "", "Use \ - this parameter to leave out missing values to get only the stored values of the time series data set." - unit, ":ref:`def-unit`", "", "You should not use this parameter, and instead use the 'units' parameter below." - units, "`CWMS database - units `_", "", "Use \ - this parameter to convert the retrieved values into a desired unit, such as retrieving elevation data \ - in feet (ft) instead of meters (m)." - version-date, ":ref:`def-version-date`", "", "Use this parameter to limit results to a specific version, \ + trim, "Trim missing values from the beginning and end of the retrieved values (true/false).", "", "To leave out \ + missing values to get only the stored values of the time series data set." + unit, ":ref:`def-unit`", "", "Do not use this parameter, instead use the 'units' parameter below." + units, "`CWMS database - units `_", "", "To \ + convert the retrieved values into a desired unit, such as retrieving elevation data in feet (ft) instead \ + of meters (m)." + version-date, ":ref:`def-version-date`", "", "To limit results to a specific version, \ such as when multiple versions of a time series exist with different associated forecast dates." .. note:: - Detailed documentation for Legacy Format Responses in CDA is currently in development and will be - available at https://cwms-data.usace.army.mil/cwms-data/legacy-format in a future release. + Detailed documentation for Legacy Format Responses for the `format` parameter in CDA is currently + in development and will be available at https://cwms-data.usace.army.mil/cwms-data/legacy-format + in a future release. Examples ---------- -- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second \ - starting on October 12, 2025 at 12:35PM. +- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second + starting on October 12, 2025 at 12:35PM. -.. code-block:: sql +.. code-block:: urlencoded - GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&unit=m3/s + GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&units=m3/s + +- Data for the time series by the name `STATION2.Elev.Avg.15Minutes.1Day.CWMS` in feet + using the NAVD88 elevation datum. + +.. code-block:: urlencoded + + GET /timeseries?name=STATION2.Elev.Avg.15Minutes.1Day.CWMS&datum=NAVD88&units=ft + +- Data for the time series by the name `STATION3.Temp.Inst.12Hour.1Month.CWMS` with version data `2025-10-01T12:00:00Z` + and office ID `NWDP`. + +.. code-block:: urlencoded + + GET /timeseries?name=STATION3.Temp.Inst.12Hour.1Month.CWMS&version-date=2025-10-01T12:00:00Z&office=NWDP + +- Data for the time series by the name `STATION4.Area.Total.1Day.1Week.Surface-CWMS` with a page size of 25 in the + `America/Los_Angeles` timezone, including the entry dates of the data points. + +.. + The examples listed below are code block literals and thus cannot be placed on separate lines. + +.. code-block:: urlencoded + + GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True + +- Data for the above time series' next page of results, using the generated next-page value of `rGfes*720SJK` + provided in the response from the previous query. + +.. code-block:: urlencoded + + GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True&page=rGfes*720SJK See the consolidated API documentation: :doc:`/api-references`. From 294f529cf0ea0169f5daf34e9150998781c77f0f Mon Sep 17 00:00:00 2001 From: zack-rma Date: Wed, 21 Jan 2026 15:19:47 -0800 Subject: [PATCH 4/6] Updated the timeSeries-profile-instance-byID.rst documentation for units and previous/next parameters --- .../timeSeries-profile-instance-byID.rst | 48 +++++++++++++++---- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst index a79bf763e..f156b4fd6 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst @@ -30,7 +30,8 @@ When to use 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.","Yes", "To specify the \ + 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, \ @@ -38,8 +39,10 @@ When to use 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).","", "" - next,"Include the next time window of the time series profile instance (true/false).","", "" + 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." @@ -53,19 +56,46 @@ When to use Examples -------- -- Fetch the most recent instance version for the `LOC123` location, `Flow` parameter, `CWMS` version, and `HQ` office, \ - with a time window of `2025-10-01T06:00:00Z` to `2026-01-21T18:00:00Z`: +- 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/Flow-Evap/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-21T18:00:00Z&unit=__ + 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, `Flow` parameter, `CWMS` version, and `HQ` office, with \ - a version date of `2026-01-01T12:00:00Z`: +- 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/Flow-Evap/CWMS?office=HQ&unit=__&version-date=2026-01-01T12:00:00Z + 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:: urlencoded + + 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`. From f346f5003a21d23c61a968f30c52c6bd6e2742a0 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 27 Jan 2026 11:16:51 -0800 Subject: [PATCH 5/6] Moved timeseries basic information. Updated examples for clearer user intention and parameter identification. --- docs/source/data/timeseries.rst | 29 ++- .../endpoints/timeSeries_endpoints/index.rst | 2 +- .../timeSeries-profile-byID.rst | 34 +++- .../timeSeries-profile-instance-byID.rst | 167 +++++++++++++++--- .../timeSeries-profile-instance.rst | 20 ++- .../timeSeries-profile-parser-byID.rst | 9 +- .../timeSeries-profile-parser.rst | 11 +- .../timeSeries-profile.rst | 31 +++- .../timeSeries-recent.rst | 22 ++- .../timeSeries_endpoints/timeSeries.rst | 60 +++++-- .../timeseries_basics.rst | 35 ---- 11 files changed, 326 insertions(+), 94 deletions(-) delete mode 100644 docs/source/endpoints/timeSeries_endpoints/timeseries_basics.rst diff --git a/docs/source/data/timeseries.rst b/docs/source/data/timeseries.rst index 2b4b23bb9..9e84108c9 100644 --- a/docs/source/data/timeseries.rst +++ b/docs/source/data/timeseries.rst @@ -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 `_ + + - 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 `_ + + +- 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` diff --git a/docs/source/endpoints/timeSeries_endpoints/index.rst b/docs/source/endpoints/timeSeries_endpoints/index.rst index 2c33a6648..c14f30346 100644 --- a/docs/source/endpoints/timeSeries_endpoints/index.rst +++ b/docs/source/endpoints/timeSeries_endpoints/index.rst @@ -16,7 +16,7 @@ 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> /timeseries /timeseries/recent diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst index d105c0a2e..44352f62d 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst @@ -49,18 +49,42 @@ When to use Examples -------- -- Retrieve a profile for the `LOC123` location and `Depth-Temperature` parameter for the `HQ` office: -.. code-block:: urlencoded +- | 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`. - GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ +.. code-block:: bash -- Retrieve a profile for the `RIVER-STATION1` location and `Depth-Temperature` parameter: + GET /timeseries/profile/[location-id]/[parameter-id] -.. code-block:: +.. code-block:: bash GET /timeseries/profile/RIVER-STATION1/Depth-Temperature +- 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 + + 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 index f156b4fd6..9b3f9f98f 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst @@ -56,46 +56,173 @@ When to use Examples -------- -- 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`: +- The user wants to retrieve the latest profile instance data for a specific location and parameter within a defined + time range. They specify the location ID as LOC123: + + | (**location-id**) :code:`LOC123` + | + | the parameter ID as Depth-Temperature: + | (**parameter-id**) :code:`Depth-Temperature` + | + | and the version as CWMS: + | (**version**) :code:`CWMS` + | + | They also set the office to HQ: + | (**office**) :code:`HQ` + | + | and define the time window from October 1, 2025, at 06:00 UTC: + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | to January 21, 2026, at 18:00 UTC: + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | They choose units of meters (m) and Fahrenheit (F) for the response: + | (**unit**) :code:`m,F` + +.. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit] .. 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`: + 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 + +- The user wants to retrieve a specific version of the profile instance by providing a version date. + They specify the same location ID, parameter ID, version, office, units, and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they include the version-date parameter set to January 1, 2026, at 12:00 UTC: + | (**version-date**) :code:`2026-01-01T12:00:00Z` + | + | and the max-version parameter set to False: + | (**max-version**) :code:`False` + +.. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&version-date=[version-date]&max-version=[True/False] .. 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 + 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 + +- The user wants to retrieve the most recent version of the profile instance. + They specify the same location ID, parameter ID, version, office, units, and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the max-version parameter to True and do not include a version-date parameter: + | (**max-version**) :code:`True` + +.. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&max-version=[True/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: +- The user wants to retrieve the most recent version of the profile instance with a specific time zone and + inclusivity settings for the time window. They want to include data points that occur at the beginning and end of + the provided time window. They specify the same location ID, parameter ID, version, office, units, + and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the timezone parameter to Pacific (Los Angeles): + | (**timezone**) :code:`America/Los_Angeles` + | + | and set both the start-time-inclusive and end-time-inclusive parameters to True: + | (**start-time-inclusive**) :code:`True` + | + | (**end-time-inclusive**) :code:`True` + | + | They want to limit the result size to 15 entries, so they include the page-size parameter: + | (**page-size**) :code:`15` + +.. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&start-time-inclusive=[True/False]&end-time-inclusive=[True/False] + .. 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: +- The user wants to retrieve the most recent version of the profile instance with a specific time zone and + inclusivity settings for the time window. They specify the same location ID, parameter ID, version, office, units, + and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the timezone parameter to UTC: + | (**timezone**) :code:`UTC` + + and include the next parameter set to True to include the single time step of data after the end + date of the specified time window: + + | (**next**) :code:`True` + | + | They want to limit the result size to 15 entries, so they include the page-size parameter: + | (**page-size**) :code:`15` + +.. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&next=[True/False] + .. code-block:: urlencoded - 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 + 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=UTC&next=True See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst index 3879c2f0b..ae405c270 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst @@ -48,19 +48,31 @@ When to use Examples -------- -- List all available instances +- The user wants to see all available profile instances in the CWMS database. -.. code-block:: +.. note:: + Depending on the contents of the database, this query may return a large number of results. + Consider filtering the results by known values such as the office, location, or parameter ID. + +.. code-block:: bash GET /timeseries/profile-instance -- List instances for all offices starting with `MV` +- | The user wants to see all available profile instances for offices starting with `MV`, such as `MVR` and `MVS`: + | (**office-mask**) :code:`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: +- | The user wants to list all profile instances at the HQ office: + | (**office-mask**) :code:`HQ` + | + | at locations starting with "ABC": + | (**location-mask**) :code:`ABC*` + | + | for parameter combinations starting with "Flow" (such as Flow-Freq [Flow-Frequency] and Flow-Evap [Flow-Evaporation]): + | (**parameter-id-mask**) :code:`Flow*` .. code-block:: urlencoded diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst index 91a4792cd..db4d8eba5 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst @@ -26,7 +26,14 @@ When to use Examples -------- -- Get the parser for a specific profile with the office `LRL`, location name `STREAM12`, and parameter `Flow-Evap`: +- | The user wants to retrieve the profile parser for Flow-Evaporation data: + | (**parameter-id**) :code:`Flow-Evap` + | + | at the STREAM12 location: + | (**location-id**) :code:`STREAM12` + | + | for the LRL office: + | (**office**) :code:`LRL` .. code-block:: urlencoded diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst index 0e795ddf9..47285a260 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst @@ -32,19 +32,24 @@ When to use Examples -------- -- List all available parsers: +- The user wants to see all available profile parsers in the system. .. code-block:: GET /timeseries/profile-parser -- List available parsers for the `HQ` office: +- | The user wants to see all available profile parsers in the HQ office: + | (**office-mask**) :code:`HQ` .. code-block:: urlencoded GET /timeseries/profile-parser?office-mask=HQ -- List available parsers with the `Area-Evap` parameter for locations ending with `BASIN`: +- | The user wants to see all available profile parsers for the Area-Evaporation parameter: + | (**parameter-id-mask**) :code:`Area-Evap` + | + | at location names ending with "BASIN": + | (**location-mask**) :code:`*BASIN` .. code-block:: urlencoded diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst index 1dada40d8..83e5d1650 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst @@ -44,26 +44,47 @@ When to use Examples -------- -- List profiles at the `HQ` office for locations starting with `ABC`: +- | The user wants to retrieve the profiles of all parameters from the `HQ` office: + | (**office**) :code:`HQ` + + but is unsure of the location name. They know the location name starts with `ABC`, so they use a wildcard search: + + | (**location-mask**) :code:`ABC*` .. code-block:: urlencoded GET /timeseries/profile?location-mask=ABC*&office=HQ -- List profiles for offices starting with `S` for the elevation parameter: +- | The user wants to retrieve the profiles for the elevation parameter: + | (**parameter-id-mask**) :code:`Elev` + | + | across all offices starting with `S`, such as `SPK`, `SRL`, and `SWT`, so they use a wildcard search for the office: + | (**office-mask**) :code:`S*` .. code-block:: urlencoded GET /timeseries/profile?office-mask=S*¶meter-id-mask=Elev -- List profiles at the `SPK` office with 100 results per page +- | The user wants to list the profiles of all parameters at the `SPK` office: + | (**office-mask**) :code:`SPK` + | + | but only wants to see 100 results at a time. + | (**page-size**) :code:`100` .. 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 +- The user wants to list the following page of results from the previous query, using the `next-page` value + of `t!qqoLun283` returned in the prior response. The query remains the same: + + | (**office-mask**) :code:`SPK` + | + | (**page-size**) :code:`100` + | + | but adds the `page` parameter: + | (**page**) :code:`t!qqoLun283` + .. code-block:: urlencoded diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst index a4da6c02e..7511e5742 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst @@ -30,20 +30,32 @@ When to use Examples -------- -- Latest values for a list of series IDs (`STATION1.Flow.Inst.15Minutes.0.CWMS` and \ - `STATION2.Stage.Inst.15Minutes.0.CWMS`) in the Imperial unit system: +- | 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 -- Latest values for time series in the `CALC3` group: +- | 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-ide=CALC3 + GET /timeseries/recent?group-id=CALC3 -- Latest values for time series in the `CALC3` group and in the `COMPUTE` category for the `HQ` office: +- | 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 diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index 22c25dff1..0b05a8e3c 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -57,39 +57,73 @@ When to use Examples ---------- -- Data for the time series by the name `STATION1.Flow.Inst.15Minutes.0.CWMS` in cubic meters per second - starting on October 12, 2025 at 12:35PM. +- | The user wants to retrieve flow data for `STATION1` at 15-minute intervals from the time series: + | (**name**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS` + | + | from October 12, 2025 at 12:35 PM UTC onward: + | (**begin**) :code:`2025-10-12T12:35:00Z` + | + | with the values converted to cubic meters per second: + | (**units**) :code:`m3/s`. .. code-block:: urlencoded GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&units=m3/s -- Data for the time series by the name `STATION2.Elev.Avg.15Minutes.1Day.CWMS` in feet - using the NAVD88 elevation datum. +- | The user wants to retrieve elevation data for `STATION2` at 15-minute intervals from the time series: + | (**name**) :code:`STATION2.Elev.Avg.15Minutes.1Day.CWMS` + | + | with the values converted to feet: + | (**units**) :code:`ft` + | + | and using the NAVD88 datum: + | (**datum**) :code:`NAVD88` .. code-block:: urlencoded GET /timeseries?name=STATION2.Elev.Avg.15Minutes.1Day.CWMS&datum=NAVD88&units=ft -- Data for the time series by the name `STATION3.Temp.Inst.12Hour.1Month.CWMS` with version data `2025-10-01T12:00:00Z` - and office ID `NWDP`. +- | The user wants to retrieve temperature data for `STATION3` at 12-hour intervals from the time series: + | (**name**) :code:`STATION3.Temp.Inst.12Hour.1Month.CWMS` + | + | using the version date of October 1, 2025 at 12:00 PM UTC: + | (**version-date**) :code:`2025-10-01T12:00:00Z` + | + | and limiting results to the office `NWDP`: + | (**office**) :code:`NWDP` .. code-block:: urlencoded GET /timeseries?name=STATION3.Temp.Inst.12Hour.1Month.CWMS&version-date=2025-10-01T12:00:00Z&office=NWDP -- Data for the time series by the name `STATION4.Area.Total.1Day.1Week.Surface-CWMS` with a page size of 25 in the - `America/Los_Angeles` timezone, including the entry dates of the data points. - -.. - The examples listed below are code block literals and thus cannot be placed on separate lines. +- | The user wants to retrieve area data for `STATION4` at 1-day intervals from the time series: + | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` + | + | with 25 results per response: + | (**page-size**) :code:`25` + | + | in the Pacific timezone (Los Angeles): + | (**timezone**) :code:`America/Los_Angeles` + | + | and including the entry dates of each data point: + | (**include-entry-date**) :code:`True` .. code-block:: urlencoded GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True -- Data for the above time series' next page of results, using the generated next-page value of `rGfes*720SJK` - provided in the response from the previous query. +- The user wants to retrieve the following page of results for the above query with a page value of `rGfes*720SJK` + provided by the response from the previous query (`next-page`): + + | (**page**) :code:`rGfes*720SJK` + | + | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` + | + | (**page-size**) :code:`25` + | + | (**timezone**) :code:`America/Los_Angeles` + | + | (**include-entry-date**) :code:`True` .. code-block:: urlencoded diff --git a/docs/source/endpoints/timeSeries_endpoints/timeseries_basics.rst b/docs/source/endpoints/timeSeries_endpoints/timeseries_basics.rst deleted file mode 100644 index f7c097340..000000000 --- a/docs/source/endpoints/timeSeries_endpoints/timeseries_basics.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _timeseries-basics: - -Time Series -============== - - - -- What is a TimeSeries? - - `CWMS database - Time Series Definition `_ - - - 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 `_ - - -- 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: - -- :ref:`timeSeries-endpoints` - - From a7ab4d240ebdb660da17223083199ad424db9cf2 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Fri, 30 Jan 2026 14:59:42 -0800 Subject: [PATCH 6/6] Added shared "when to use" document. Swapped bullet points for numbered lists. --- .../endpoints/timeSeries_endpoints/index.rst | 1 + .../shared_definitions.rst | 2 +- .../shared_when_to_use.rst | 63 ++++ .../timeSeries-profile-byID.rst | 54 ++- .../timeSeries-profile-instance-byID.rst | 352 +++++++++--------- .../timeSeries-profile-instance.rst | 49 ++- .../timeSeries-profile-parser-byID.rst | 32 +- .../timeSeries-profile-parser.rst | 36 +- .../timeSeries-profile.rst | 76 ++-- .../timeSeries-recent.rst | 47 ++- .../timeSeries_endpoints/timeSeries.rst | 155 ++++---- 11 files changed, 454 insertions(+), 413 deletions(-) create mode 100644 docs/source/endpoints/timeSeries_endpoints/shared_when_to_use.rst diff --git a/docs/source/endpoints/timeSeries_endpoints/index.rst b/docs/source/endpoints/timeSeries_endpoints/index.rst index c14f30346..ebec55275 100644 --- a/docs/source/endpoints/timeSeries_endpoints/index.rst +++ b/docs/source/endpoints/timeSeries_endpoints/index.rst @@ -18,6 +18,7 @@ Browse Time Series GET Endpoints: TimeSeries Basic Information <../../data/timeseries.rst> Common Parameter Definitions <./shared_definitions.rst> + Common Reasons for Parameter Usage <./shared_when_to_use.rst> /timeseries /timeseries/recent /timeseries/profile diff --git a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst b/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst index 564821d8a..a46612459 100644 --- a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst +++ b/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst @@ -95,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. diff --git a/docs/source/endpoints/timeSeries_endpoints/shared_when_to_use.rst b/docs/source/endpoints/timeSeries_endpoints/shared_when_to_use.rst new file mode 100644 index 000000000..727979e18 --- /dev/null +++ b/docs/source/endpoints/timeSeries_endpoints/shared_when_to_use.rst @@ -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`. \ 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 index 44352f62d..9cecf475f 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst @@ -41,48 +41,46 @@ When to use :header: "Parameter", "Description", "Required", "When to Use" :widths: 30, 40, 20, 65 - 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`." + 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 -------- -- | 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`. +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 + .. code-block:: bash - GET /timeseries/profile/[location-id]/[parameter-id] + GET /timeseries/profile/[location-id]/[parameter-id] -.. code-block:: bash + .. code-block:: bash - GET /timeseries/profile/RIVER-STATION1/Depth-Temperature + GET /timeseries/profile/RIVER-STATION1/Depth-Temperature -- 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: +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` + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**location-id**) :code:`RIVER-STATION1` + | + | but adds the optional query parameter, `office`: + | (**office**) :code:`HQ` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile/[location-id]/[parameter-id]?office=[office] + GET /timeseries/profile/[location-id]/[parameter-id]?office=[office] -.. code-block:: urlencoded + .. 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`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst index 9b3f9f98f..7db14a729 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance-byID.rst @@ -16,14 +16,12 @@ When to use :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." + location-id,":ref:`def-location-id`","Yes", ":ref:`when_location_id`" + parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`" version,"`CWMS database - version `_ 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." + office,":ref:`def-office`","Yes", ":ref:`when_office`" 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 \ @@ -46,183 +44,181 @@ When to use 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." + start,":ref:`def-start`","Yes", ":ref:`when_start`" + end, ":ref:`def-end`", "Yes", ":ref:`when_end`" + page,":ref:`def-page`","", ":ref:`when_page`" + page-size,":ref:`def-page-size`","", ":ref:`when_page_size`" Examples -------- -- The user wants to retrieve the latest profile instance data for a specific location and parameter within a defined - time range. They specify the location ID as LOC123: - - | (**location-id**) :code:`LOC123` - | - | the parameter ID as Depth-Temperature: - | (**parameter-id**) :code:`Depth-Temperature` - | - | and the version as CWMS: - | (**version**) :code:`CWMS` - | - | They also set the office to HQ: - | (**office**) :code:`HQ` - | - | and define the time window from October 1, 2025, at 06:00 UTC: - | (**start**) :code:`2025-10-01T06:00:00Z` - | - | to January 21, 2026, at 18:00 UTC: - | (**end**) :code:`2026-01-21T18:00:00Z` - | - | They choose units of meters (m) and Fahrenheit (F) for the response: - | (**unit**) :code:`m,F` - -.. code-block:: bash - - GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit] - -.. 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 - -- The user wants to retrieve a specific version of the profile instance by providing a version date. - They specify the same location ID, parameter ID, version, office, units, and time window as before: - - | (**location-id**) :code:`LOC123` - | - | (**parameter-id**) :code:`Depth-Temperature` - | - | (**version**) :code:`CWMS` - | - | (**office**) :code:`HQ` - | - | (**start**) :code:`2025-10-01T06:00:00Z` - | - | (**end**) :code:`2026-01-21T18:00:00Z` - | - | (**unit**) :code:`m,F` - | - | but this time they include the version-date parameter set to January 1, 2026, at 12:00 UTC: - | (**version-date**) :code:`2026-01-01T12:00:00Z` - | - | and the max-version parameter set to False: - | (**max-version**) :code:`False` - -.. code-block:: bash - - GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&version-date=[version-date]&max-version=[True/False] - -.. 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 - -- The user wants to retrieve the most recent version of the profile instance. - They specify the same location ID, parameter ID, version, office, units, and time window as before: - - | (**location-id**) :code:`LOC123` - | - | (**parameter-id**) :code:`Depth-Temperature` - | - | (**version**) :code:`CWMS` - | - | (**office**) :code:`HQ` - | - | (**start**) :code:`2025-10-01T06:00:00Z` - | - | (**end**) :code:`2026-01-21T18:00:00Z` - | - | (**unit**) :code:`m,F` - | - | but this time they set the max-version parameter to True and do not include a version-date parameter: - | (**max-version**) :code:`True` - -.. code-block:: bash - - GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&max-version=[True/False] - - -.. 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 - -- The user wants to retrieve the most recent version of the profile instance with a specific time zone and - inclusivity settings for the time window. They want to include data points that occur at the beginning and end of - the provided time window. They specify the same location ID, parameter ID, version, office, units, - and time window as before: - - | (**location-id**) :code:`LOC123` - | - | (**parameter-id**) :code:`Depth-Temperature` - | - | (**version**) :code:`CWMS` - | - | (**office**) :code:`HQ` - | - | (**start**) :code:`2025-10-01T06:00:00Z` - | - | (**end**) :code:`2026-01-21T18:00:00Z` - | - | (**unit**) :code:`m,F` - | - | but this time they set the timezone parameter to Pacific (Los Angeles): - | (**timezone**) :code:`America/Los_Angeles` - | - | and set both the start-time-inclusive and end-time-inclusive parameters to True: - | (**start-time-inclusive**) :code:`True` - | - | (**end-time-inclusive**) :code:`True` - | - | They want to limit the result size to 15 entries, so they include the page-size parameter: - | (**page-size**) :code:`15` - -.. code-block:: bash - - GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&start-time-inclusive=[True/False]&end-time-inclusive=[True/False] - - -.. 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 - -- The user wants to retrieve the most recent version of the profile instance with a specific time zone and - inclusivity settings for the time window. They specify the same location ID, parameter ID, version, office, units, - and time window as before: - - | (**location-id**) :code:`LOC123` - | - | (**parameter-id**) :code:`Depth-Temperature` - | - | (**version**) :code:`CWMS` - | - | (**office**) :code:`HQ` - | - | (**start**) :code:`2025-10-01T06:00:00Z` - | - | (**end**) :code:`2026-01-21T18:00:00Z` - | - | (**unit**) :code:`m,F` - | - | but this time they set the timezone parameter to UTC: - | (**timezone**) :code:`UTC` - - and include the next parameter set to True to include the single time step of data after the end - date of the specified time window: - - | (**next**) :code:`True` - | - | They want to limit the result size to 15 entries, so they include the page-size parameter: - | (**page-size**) :code:`15` - -.. code-block:: bash - - GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&next=[True/False] - - -.. 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=UTC&next=True +1. The user wants to retrieve the latest profile instance data for a specific location and parameter within a defined + time range. They specify the location ID as LOC123: + + | (**location-id**) :code:`LOC123` + | + | the parameter ID as Depth-Temperature: + | (**parameter-id**) :code:`Depth-Temperature` + | + | and the version as CWMS: + | (**version**) :code:`CWMS` + | + | They also set the office to HQ: + | (**office**) :code:`HQ` + | + | and define the time window from October 1, 2025, at 06:00 UTC: + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | to January 21, 2026, at 18:00 UTC: + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | They choose units of meters (m) and Fahrenheit (F) for the response: + | (**unit**) :code:`m,F` + + .. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit] + + .. 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 + +2. The user wants to retrieve a specific version of the profile instance by providing a version date. + They specify the same location ID, parameter ID, version, office, units, and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they include the version-date parameter set to January 1, 2026, at 12:00 UTC: + | (**version-date**) :code:`2026-01-01T12:00:00Z` + | + | and the max-version parameter set to False: + | (**max-version**) :code:`False` + + .. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&version-date=[version-date]&max-version=[True/False] + + .. 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 + +3. The user wants to retrieve the most recent version of the profile instance. + They specify the same location ID, parameter ID, version, office, units, and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the max-version parameter to True and do not include a version-date parameter: + | (**max-version**) :code:`True` + + .. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&max-version=[True/False] + + + .. 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 + +4. The user wants to retrieve the most recent version of the profile instance with a specific time zone and + inclusivity settings for the time window. They want to include data points that occur at the beginning and end of + the provided time window. They specify the same location ID, parameter ID, version, office, units, + and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the timezone parameter to Pacific (Los Angeles): + | (**timezone**) :code:`America/Los_Angeles` + | + | and set both the start-time-inclusive and end-time-inclusive parameters to True: + | (**start-time-inclusive**) :code:`True` + | + | (**end-time-inclusive**) :code:`True` + | + | They want to limit the result size to 15 entries, so they include the page-size parameter: + | (**page-size**) :code:`15` + + .. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&start-time-inclusive=[True/False]&end-time-inclusive=[True/False] + + + .. 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 + +5. The user wants to retrieve the most recent version of the profile instance with a specific time zone and + inclusivity settings for the time window. They specify the same location ID, parameter ID, version, office, units, + and time window as before: + + | (**location-id**) :code:`LOC123` + | + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**version**) :code:`CWMS` + | + | (**office**) :code:`HQ` + | + | (**start**) :code:`2025-10-01T06:00:00Z` + | + | (**end**) :code:`2026-01-21T18:00:00Z` + | + | (**unit**) :code:`m,F` + | + | but this time they set the timezone parameter to UTC: + | (**timezone**) :code:`UTC` + + and include the next parameter set to True to include the single time step of data after the end + date of the specified time window: + + | (**next**) :code:`True` + | + | They want to limit the result size to 15 entries, so they include the page-size parameter: + | (**page-size**) :code:`15` + + .. code-block:: bash + + GET /timeseries/profile-instance/[location-id]/[parameter-id]/[version]?office=[office]&start=[start]&end=[end]&unit=[unit]&page-size=[page-size]&timezone=[timezone]&next=[True/False] + + + .. 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=UTC&next=True See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst index ae405c270..1440e4393 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst @@ -34,12 +34,9 @@ When to use 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*`." + office-mask,":ref:`def-office-mask`","", ":ref:`when_office_mask`" + location-mask,":ref:`def-location-mask`","", ":ref:`when_location_mask`" + parameter-id-mask,":ref:`def-parameter-id-mask`","", ":ref:`when_parameter_id_mask`" .. note:: Detailed documentation for Regex usage in CDA is currently in development and will be available at @@ -48,35 +45,35 @@ When to use Examples -------- -- The user wants to see all available profile instances in the CWMS database. +1. The user wants to see all available profile instances in the CWMS database. -.. note:: - Depending on the contents of the database, this query may return a large number of results. - Consider filtering the results by known values such as the office, location, or parameter ID. + .. note:: + Depending on the contents of the database, this query may return a large number of results. + Consider filtering the results by known values such as the office, location, or parameter ID. -.. code-block:: bash + .. code-block:: bash - GET /timeseries/profile-instance + GET /timeseries/profile-instance -- | The user wants to see all available profile instances for offices starting with `MV`, such as `MVR` and `MVS`: - | (**office-mask**) :code:`MV*` +2. | The user wants to see all available profile instances for offices starting with `MV`, such as `MVR` and `MVS`: + | (**office-mask**) :code:`MV*` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile-instance?office-mask=MV* + GET /timeseries/profile-instance?office-mask=MV* -- | The user wants to list all profile instances at the HQ office: - | (**office-mask**) :code:`HQ` - | - | at locations starting with "ABC": - | (**location-mask**) :code:`ABC*` - | - | for parameter combinations starting with "Flow" (such as Flow-Freq [Flow-Frequency] and Flow-Evap [Flow-Evaporation]): - | (**parameter-id-mask**) :code:`Flow*` +3. | The user wants to list all profile instances at the HQ office: + | (**office-mask**) :code:`HQ` + | + | at locations starting with "ABC": + | (**location-mask**) :code:`ABC*` + | + | for parameter combinations starting with "Flow" (such as Flow-Freq [Flow-Frequency] and Flow-Evap [Flow-Evaporation]): + | (**parameter-id-mask**) :code:`Flow*` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile-instance?location-mask=ABC*¶meter-id-mask=Flow*&office-mask=HQ + GET /timeseries/profile-instance?location-mask=ABC*¶meter-id-mask=Flow*&office-mask=HQ See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst index db4d8eba5..cde371355 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser-byID.rst @@ -18,26 +18,24 @@ When to use :header: "Parameter", "Description", "Required", "When to Use" :widths: 30, 40, 20, 60 - 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`." + location-id,":ref:`def-location-id`","Yes", ":ref:`when_location_id`" + office,":ref:`def-office`","Yes", ":ref:`when_office`" + parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`" Examples -------- -- | The user wants to retrieve the profile parser for Flow-Evaporation data: - | (**parameter-id**) :code:`Flow-Evap` - | - | at the STREAM12 location: - | (**location-id**) :code:`STREAM12` - | - | for the LRL office: - | (**office**) :code:`LRL` - -.. code-block:: urlencoded - - GET /timeseries/profile-parser/STREAM12/Flow-Evap?office=LRL +1. | The user wants to retrieve the profile parser for Flow-Evaporation data: + | (**parameter-id**) :code:`Flow-Evap` + | + | at the STREAM12 location: + | (**location-id**) :code:`STREAM12` + | + | for the LRL office: + | (**office**) :code:`LRL` + + .. code-block:: urlencoded + + GET /timeseries/profile-parser/STREAM12/Flow-Evap?office=LRL See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst index 47285a260..56c15d6b2 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst @@ -23,37 +23,35 @@ When to use :header: "Parameter", "Description", "Required", "When to Use" :widths: 30, 40, 20, 60 - 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`." + office-mask,":ref:`def-office-mask`","", ":ref:`when_office_mask`" + location-mask,":ref:`def-location-mask`","", ":ref:`when_location_mask`" + parameter-id-mask,":ref:`def-parameter-id-mask`","", ":ref:`when_parameter_id_mask`" Examples -------- -- The user wants to see all available profile parsers in the system. +1. The user wants to see all available profile parsers in the system. -.. code-block:: + .. code-block:: - GET /timeseries/profile-parser + GET /timeseries/profile-parser -- | The user wants to see all available profile parsers in the HQ office: - | (**office-mask**) :code:`HQ` +2. | The user wants to see all available profile parsers in the HQ office: + | (**office-mask**) :code:`HQ` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile-parser?office-mask=HQ + GET /timeseries/profile-parser?office-mask=HQ -- | The user wants to see all available profile parsers for the Area-Evaporation parameter: - | (**parameter-id-mask**) :code:`Area-Evap` - | - | at location names ending with "BASIN": - | (**location-mask**) :code:`*BASIN` +3. | The user wants to see all available profile parsers for the Area-Evaporation parameter: + | (**parameter-id-mask**) :code:`Area-Evap` + | + | at location names ending with "BASIN": + | (**location-mask**) :code:`*BASIN` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile-parser?parameter-id-mask=Area-Evap&location-mask=*BASIN + GET /timeseries/profile-parser?parameter-id-mask=Area-Evap&location-mask=*BASIN See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst index 83e5d1650..67e90e540 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst @@ -30,65 +30,59 @@ When to use :header: "Parameter", "Description", "Required", "When to Use" :widths: 30, 40, 20, 65 - 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`" + location-mask,":ref:`def-location-mask`","", ":ref:`when_location_mask`" + office-mask,":ref:`def-office-mask`","", ":ref:`when_office_mask`" + page,":ref:`def-page`","", ":ref:`when_page`" + page-size,":ref:`def-page-size`","", ":ref:`when_page_size`" + parameter-id-mask,":ref:`def-parameter-id-mask`","", ":ref:`when_parameter_id_mask`" Examples -------- -- | The user wants to retrieve the profiles of all parameters from the `HQ` office: - | (**office**) :code:`HQ` +1. | The user wants to retrieve the profiles of all parameters from the `HQ` office: + | (**office**) :code:`HQ` - but is unsure of the location name. They know the location name starts with `ABC`, so they use a wildcard search: + but is unsure of the location name. They know the location name starts with `ABC`, so they use a wildcard search: - | (**location-mask**) :code:`ABC*` + | (**location-mask**) :code:`ABC*` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile?location-mask=ABC*&office=HQ + GET /timeseries/profile?location-mask=ABC*&office=HQ -- | The user wants to retrieve the profiles for the elevation parameter: - | (**parameter-id-mask**) :code:`Elev` - | - | across all offices starting with `S`, such as `SPK`, `SRL`, and `SWT`, so they use a wildcard search for the office: - | (**office-mask**) :code:`S*` +2. | The user wants to retrieve the profiles for the elevation parameter: + | (**parameter-id-mask**) :code:`Elev` + | + | across all offices starting with `S`, such as `SPK`, `SRL`, and `SWT`, so they use a wildcard search for the office: + | (**office-mask**) :code:`S*` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile?office-mask=S*¶meter-id-mask=Elev + GET /timeseries/profile?office-mask=S*¶meter-id-mask=Elev -- | The user wants to list the profiles of all parameters at the `SPK` office: - | (**office-mask**) :code:`SPK` - | - | but only wants to see 100 results at a time. - | (**page-size**) :code:`100` +3. | The user wants to list the profiles of all parameters at the `SPK` office: + | (**office-mask**) :code:`SPK` + | + | but only wants to see 100 results at a time. + | (**page-size**) :code:`100` -.. code-block:: urlencoded + .. code-block:: urlencoded - GET /timeseries/profile?office-mask=SPK&page-size=100 + GET /timeseries/profile?office-mask=SPK&page-size=100 -- The user wants to list the following page of results from the previous query, using the `next-page` value - of `t!qqoLun283` returned in the prior response. The query remains the same: +4. The user wants to list the following page of results from the previous query, using the `next-page` value + of `t!qqoLun283` returned in the prior response. The query remains the same: - | (**office-mask**) :code:`SPK` - | - | (**page-size**) :code:`100` - | - | but adds the `page` parameter: - | (**page**) :code:`t!qqoLun283` + | (**office-mask**) :code:`SPK` + | + | (**page-size**) :code:`100` + | + | but adds the `page` parameter: + | (**page**) :code:`t!qqoLun283` + .. code-block:: urlencoded -.. code-block:: urlencoded - - GET /timeseries/profile?office-mask=SPK&page-size=100&page=t!qqoLun283 + GET /timeseries/profile?office-mask=SPK&page-size=100&page=t!qqoLun283 See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst index 7511e5742..485a657fb 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst @@ -24,42 +24,41 @@ When to use ts-ids, "`CWMS database - 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`","", "To limit results to a specific office, such as `SPK`, perhaps for the purpose \ - of improving query response time." + office, ":ref:`def-office`","", ":ref:`when_office`" Examples -------- -- | 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` +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 + .. code-block:: urlencoded - GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN + GET /timeseries/recent?ts-ids=STATION1.Flow.Inst.15Minutes.0.CWMS,STATION2.Stage.Inst.15Minutes.0.CWMS&unit-system=EN -- | The user wants to retrieve the recent time series data for all time series in the `CALC3` time series group: - | (**group-id**) :code:`CALC3` +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 + .. code-block:: urlencoded - GET /timeseries/recent?group-id=CALC3 + GET /timeseries/recent?group-id=CALC3 -- | 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` +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 + .. code-block:: urlencoded - GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ + GET /timeseries/recent?group-ide=CALC3&category-id=COMPUTE&office=HQ See the consolidated API documentation: :doc:`/api-references`. diff --git a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst index 0b05a8e3c..2f4496c55 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -21,22 +21,19 @@ When to use :header: "Parameter", "Description", "Required", "When to Use" :widths: 30, 60, 20, 60 - begin, ":ref:`def-start`", "", "To limit the results to be after a specified date and time." + begin, ":ref:`def-start`", "", ":ref:`when_start`" datum, "The standardized reference system used for either vertical measurements. \ Examples: NAVD88, NGVD29, LOCAL, etc.", "", "To retrieve measurements in a specified system." - end, ":ref:`def-end`", "", "To limit the results to be before a specified date and time." + end, ":ref:`def-end`", "", ":ref:`when_end`" format, "The desired response format. Usage differs between endpoints. See note below.", "", "Use this \ to force the format provided in the response." include-entry-date, "Include timestamps for when each data point was added to the CWMS database (true/false).", "\ ", "To determine when each time series data point was stored." name, "The text representation of the unique time series identifier.", "Yes", "To \ differentiate the specific time series data you desire to retrieve." - office, "see :ref:`def-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." - page, ":ref:`def-page`", "", "To get results that were not able to fit in the previous page of results." - page-size, ":ref:`def-page-size`", "", "To specify the number of results you wish to receive \ - from a single query. Further results may be available on a subsequent page of the same length." + office, ":ref:`def-office`", "", ":ref:`when_office`" + page, ":ref:`def-page`", "", ":ref:`when_page`" + page-size, ":ref:`def-page-size`", "", ":ref:`when_page_size`" timezone, ":ref:`def-timezone`", "", "To retrieve data points in a timezone that works best with \ your use case, such as your local timezone." trim, "Trim missing values from the beginning and end of the retrieved values (true/false).", "", "To leave out \ @@ -57,77 +54,77 @@ When to use Examples ---------- -- | The user wants to retrieve flow data for `STATION1` at 15-minute intervals from the time series: - | (**name**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS` - | - | from October 12, 2025 at 12:35 PM UTC onward: - | (**begin**) :code:`2025-10-12T12:35:00Z` - | - | with the values converted to cubic meters per second: - | (**units**) :code:`m3/s`. - -.. code-block:: urlencoded - - GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&units=m3/s - -- | The user wants to retrieve elevation data for `STATION2` at 15-minute intervals from the time series: - | (**name**) :code:`STATION2.Elev.Avg.15Minutes.1Day.CWMS` - | - | with the values converted to feet: - | (**units**) :code:`ft` - | - | and using the NAVD88 datum: - | (**datum**) :code:`NAVD88` - -.. code-block:: urlencoded - - GET /timeseries?name=STATION2.Elev.Avg.15Minutes.1Day.CWMS&datum=NAVD88&units=ft - -- | The user wants to retrieve temperature data for `STATION3` at 12-hour intervals from the time series: - | (**name**) :code:`STATION3.Temp.Inst.12Hour.1Month.CWMS` - | - | using the version date of October 1, 2025 at 12:00 PM UTC: - | (**version-date**) :code:`2025-10-01T12:00:00Z` - | - | and limiting results to the office `NWDP`: - | (**office**) :code:`NWDP` - -.. code-block:: urlencoded - - GET /timeseries?name=STATION3.Temp.Inst.12Hour.1Month.CWMS&version-date=2025-10-01T12:00:00Z&office=NWDP - -- | The user wants to retrieve area data for `STATION4` at 1-day intervals from the time series: - | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` - | - | with 25 results per response: - | (**page-size**) :code:`25` - | - | in the Pacific timezone (Los Angeles): - | (**timezone**) :code:`America/Los_Angeles` - | - | and including the entry dates of each data point: - | (**include-entry-date**) :code:`True` - -.. code-block:: urlencoded - - GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True - -- The user wants to retrieve the following page of results for the above query with a page value of `rGfes*720SJK` - provided by the response from the previous query (`next-page`): - - | (**page**) :code:`rGfes*720SJK` - | - | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` - | - | (**page-size**) :code:`25` - | - | (**timezone**) :code:`America/Los_Angeles` - | - | (**include-entry-date**) :code:`True` - -.. code-block:: urlencoded - - GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True&page=rGfes*720SJK +1. | The user wants to retrieve flow data for `STATION1` at 15-minute intervals from the time series: + | (**name**) :code:`STATION1.Flow.Inst.15Minutes.0.CWMS` + | + | from October 12, 2025 at 12:35 PM UTC onward: + | (**begin**) :code:`2025-10-12T12:35:00Z` + | + | with the values converted to cubic meters per second: + | (**units**) :code:`m3/s`. + + .. code-block:: urlencoded + + GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&units=m3/s + +2. | The user wants to retrieve elevation data for `STATION2` at 15-minute intervals from the time series: + | (**name**) :code:`STATION2.Elev.Avg.15Minutes.1Day.CWMS` + | + | with the values converted to feet: + | (**units**) :code:`ft` + | + | and using the NAVD88 datum: + | (**datum**) :code:`NAVD88` + + .. code-block:: urlencoded + + GET /timeseries?name=STATION2.Elev.Avg.15Minutes.1Day.CWMS&datum=NAVD88&units=ft + +3. | The user wants to retrieve temperature data for `STATION3` at 12-hour intervals from the time series: + | (**name**) :code:`STATION3.Temp.Inst.12Hour.1Month.CWMS` + | + | using the version date of October 1, 2025 at 12:00 PM UTC: + | (**version-date**) :code:`2025-10-01T12:00:00Z` + | + | and limiting results to the office `NWDP`: + | (**office**) :code:`NWDP` + + .. code-block:: urlencoded + + GET /timeseries?name=STATION3.Temp.Inst.12Hour.1Month.CWMS&version-date=2025-10-01T12:00:00Z&office=NWDP + +4. | The user wants to retrieve area data for `STATION4` at 1-day intervals from the time series: + | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` + | + | with 25 results per response: + | (**page-size**) :code:`25` + | + | in the Pacific timezone (Los Angeles): + | (**timezone**) :code:`America/Los_Angeles` + | + | and including the entry dates of each data point: + | (**include-entry-date**) :code:`True` + + .. code-block:: urlencoded + + GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True + +5. The user wants to retrieve the following page of results for the above query with a page value of `rGfes*720SJK` + provided by the response from the previous query (`next-page`): + + | (**page**) :code:`rGfes*720SJK` + | + | (**name**) :code:`STATION4.Area.Total.1Day.1Week.Surface-CWMS` + | + | (**page-size**) :code:`25` + | + | (**timezone**) :code:`America/Los_Angeles` + | + | (**include-entry-date**) :code:`True` + + .. code-block:: urlencoded + + GET /timeseries?name=STATION4.Area.Total.1Day.1Week.Surface-CWMS&page-size=25&timezone=America/Los_Angeles&include-entry-date=True&page=rGfes*720SJK See the consolidated API documentation: :doc:`/api-references`.