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..ebec55275 100644 --- a/docs/source/endpoints/timeSeries_endpoints/index.rst +++ b/docs/source/endpoints/timeSeries_endpoints/index.rst @@ -16,8 +16,9 @@ Browse Time Series GET Endpoints: .. toctree:: :maxdepth: 1 - TimeSeries Basic Information <./timeseries_basics.rst> + TimeSeries Basic Information <../../data/timeseries.rst> Common Parameter Definitions <./shared_definitions.rst> + Common Reasons for Parameter Usage <./shared_when_to_use.rst> /timeseries /timeseries/recent /timeseries/profile diff --git a/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst b/docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst index 9896a107d..a46612459 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: @@ -94,7 +95,7 @@ parameter-id-mask .. _def-start: -start (also referred to as begin) +start/begin The date and time marking the beginning of the time window for data included in the response. The format for this field is ISO 8601 extended with optional offset and timezone. 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 7e50ce574..9cecf475f 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-byID.rst @@ -38,20 +38,50 @@ When to use .. csv-table:: GET /timeseries/profile/{location-id}/{parameter-id} - Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 40, 20, 65 - location-id,":ref:`def-location-id`","Yes" - parameter-id,":ref:`def-parameter-id`","Yes" - office,":ref:`def-office`","" + location-id,":ref:`def-location-id`","Yes", ":ref:`when_location_id`" + parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`" + office,":ref:`def-office`","", ":ref:`when_office`" Examples -------- -- Fetch a profile for a location and parameter: -.. code-block:: +1. | The user wants to retrieve the temperature profile at various depths: + | (**parameter-id**) :code:`Depth-Temperature` + | + | for the RIVER-STATION1 location: + | (**location-id**) :code:`RIVER-STATION1` + | + | but is unsure of which office to use. Query includes required path parameters, `location-id` and `parameter-id`. + + .. code-block:: bash + + GET /timeseries/profile/[location-id]/[parameter-id] + + .. code-block:: bash + + GET /timeseries/profile/RIVER-STATION1/Depth-Temperature + +2. The user reviews the results from the previous example query and decides to to narrow the search to the `HQ` office. + Query remains the same: + + | (**parameter-id**) :code:`Depth-Temperature` + | + | (**location-id**) :code:`RIVER-STATION1` + | + | but adds the optional query parameter, `office`: + | (**office**) :code:`HQ` + + .. code-block:: urlencoded + + GET /timeseries/profile/[location-id]/[parameter-id]?office=[office] + + .. code-block:: urlencoded + + GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ - GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ See the consolidated API documentation: :doc:`/api-references`. 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..7db14a729 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,212 @@ 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", ":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", ":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 \ + instance. Not including this parameter will result in the response containing the instance with the most recent \ + version date" + unit,":ref:`def-unit` + Units must be compatible with desired instance data. For this endpoint, they are comma separated for the two \ + associated parameters, e.g. `m,F` for the `Depth-Temperature` parameter","Yes", "To specify the \ + desired units for the instance response." + start-time-inclusive,"Resulting data includes data from the exact start time of the time window (true/false).","\ + ", "To choose whether data points on the configured start-time parameter will be included in the response, \ + such as for the purpose of calculating averages for a time window." + end-time-inclusive,"Resulting data includes data from the exact end of the time window (true/false).","", "To \ + choose whether data points on the configured end-time parameter will be included in the response, such as for the \ + purpose of calculating averages for a time window." + previous,"Include the previous time window of the time series profile instance (true/false).","", "To include data \ + starting at the closest timestamp before the specified `start` date and time." + next,"Include the next time window of the time series profile instance (true/false).","", "To include data up to \ + the closest timestamp after the specified `end` parameter date and time." + max-version,"Use the most recent version date (true/false). Only for time series utilizing dates in the version.","\ + ", "To retrieve the instance with the latest version date (true), or to use in combination with a specific \ + version date (false) by providing a date using the version-date parameter." + start,":ref:`def-start`","Yes", ":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 -------- -- Fetch a specific instance version: +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:: sql + .. code-block:: urlencoded - GET /timeseries/profile-instance/LOC123/Flow/2?office=HQ + GET /timeseries/profile-instance/LOC123/Depth-Temperature/CWMS?office=HQ&start=2025-10-01T06:00:00Z&end=2026-01-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 6aeb695c8..1440e4393 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-instance.rst @@ -28,14 +28,15 @@ 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 +.. 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.","" - office-mask,":ref:`def-office-mask`","" - location-mask,":ref:`def-location-mask`","" - parameter-id-mask,":ref:`def-parameter-id-mask`","" + 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`","", ":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 @@ -44,11 +45,35 @@ When to use Examples -------- -- List instances for a parameter at locations starting with ABC: +1. The user wants to see all available profile instances in the CWMS database. -.. code-block:: sql + .. 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. - GET /timeseries/profile-instance?location-mask=ABC*¶meter-id-mask=Flow*&office=HQ + .. code-block:: bash + + GET /timeseries/profile-instance + +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 + + GET /timeseries/profile-instance?office-mask=MV* + +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 + + 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..cde371355 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,27 @@ 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", ":ref:`when_location_id`" + office,":ref:`def-office`","Yes", ":ref:`when_office`" + parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`" Examples -------- -- Get the parser for a specific profile: - -.. code-block:: sql - - GET /timeseries/profile-parser/LOC123/Flow?office=HQ +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 06cb144b3..56c15d6b2 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile-parser.rst @@ -20,21 +20,38 @@ 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`","", ":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 -------- -- List available parsers for your office: +1. The user wants to see all available profile parsers in the system. -.. code-block:: sql + .. code-block:: - GET /timeseries/profile-parser?office=HQ + GET /timeseries/profile-parser + +2. | 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 + +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 + + 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 037eef258..67e90e540 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-profile.rst @@ -27,23 +27,62 @@ When to use .. csv-table:: GET /timeseries/profile - Endpoint Parameters - :header: "Parameter", "Description", "Required" - :widths: 20, 60, 15 + :header: "Parameter", "Description", "Required", "When to Use" + :widths: 30, 40, 20, 65 - location-mask,":ref:`def-location-mask`","" - office-mask,":ref:`def-office-mask`","" - page,":ref:`def-page`","" - page-size,":ref:`def-page-size`","" - parameter-id-mask,":ref:`def-parameter-id-mask`","" + location-mask,":ref:`def-location-mask`","", ":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 -------- -- List profiles for locations starting with ABC: +1. | The user wants to retrieve the profiles of all parameters from the `HQ` office: + | (**office**) :code:`HQ` -.. code-block:: sql + but is unsure of the location name. They know the location name starts with `ABC`, so they use a wildcard search: - GET /timeseries/profile?location-mask=ABC*&office=HQ + | (**location-mask**) :code:`ABC*` + + .. code-block:: urlencoded + + GET /timeseries/profile?location-mask=ABC*&office=HQ + +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 + + GET /timeseries/profile?office-mask=S*¶meter-id-mask=Elev + +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 + + GET /timeseries/profile?office-mask=SPK&page-size=100 + +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` + + .. 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..485a657fb 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries-recent.rst @@ -14,24 +14,51 @@ 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`","", ":ref:`when_office`" Examples -------- -- Latest values for a list of series IDs: +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:: 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 +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 + + GET /timeseries/recent?group-id=CALC3 + +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 + + 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 d7f0a0aaa..2f4496c55 100644 --- a/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst +++ b/docs/source/endpoints/timeSeries_endpoints/timeSeries.rst @@ -18,38 +18,113 @@ 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", "When to Use" + :widths: 30, 60, 20, 60 + + 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`", "", ":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, ":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 \ + 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 ---------- -- Latest 24 hours in metric units: - -.. code-block:: sql - - GET /timeseries?name=STATION1.Flow.Inst.15Minutes.0.CWMS&begin=2025-10-12T12:35:00.000Z&unit=m3/s +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`. 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` - -