Skip to content

Commit 535fb8a

Browse files
rma-kaylazack-rmarma-rripken
authored
Updates to time series endpoint documentation (CDA-64) (#1537)
Contributes to documentation requested in #1117 Initial updates to time series endpoint documentation. Reviewed documentation updates from @zack-rma, Made edits and reworded descriptions to keep it user friendly. Cleaned up .rst syntax errors Corrected inconsistencies between each endpoint. Adjusted linking to internal pages and CWMS database read the docs. Added notes regarding future links to documentation on legacy format and regex Ran buildtheDocs and verified clean build and useable read the docs pages and toc tree. --------- Co-authored-by: zack-rma <zack@rmanet.com> Co-authored-by: Ryan Ripken <89810919+rma-rripken@users.noreply.github.com>
1 parent c15518b commit 535fb8a

17 files changed

+389
-254
lines changed

‎docs/source/endpoints/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ Endpoints
22
============
33

44
.. toctree::
5-
:caption: Endpoints
65
:maxdepth: 2
76

87
Time Series Endpoints <timeSeries_endpoints/index.rst>

‎docs/source/endpoints/timeSeries_endpoints/index.rst‎

Lines changed: 7 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,11 @@
11
.. _timeseries-endpoints:
22

3-
Time Series Endpoints
3+
TimeSeries Endpoints
44
=======================
55

6-
7-
`CWMS database - Time Series Definition <https://cwms-database.readthedocs.io/en/latest/naming.html#time-series>`_
8-
9-
`CDA Time Series Endpoints Wiki <https://github.com/USACE/cwms-data-api/wiki/TimeSeries>`_
10-
11-
12-
13-
146
.. note::
157

16-
The documentation is a work in progress. This section currently includes the below TimeSeries endpoints and focuses
8+
This documentation is a work in progress. This section currently includes the below TimeSeries endpoints and focuses
179
on the GET methods and their parameters.
1810

1911
POST, PATCH, and DELETE methods and their specific parameters are coming soon.
@@ -24,30 +16,13 @@ Browse Time Series GET Endpoints:
2416
.. toctree::
2517
:maxdepth: 1
2618

27-
TimeSeries Basics <./timeseries_basics.rst>
19+
TimeSeries Basic Information <./timeseries_basics.rst>
20+
Common Parameter Definitions <./shared_definitions.rst>
2821
/timeseries <timeSeries>
2922
/timeseries/recent <timeSeries-recent>
3023
/timeseries/profile <timeSeries-profile>
31-
/timeseries/profile/{location-id}/{parameter-id} <timeSeries-profile-byIDs>
24+
/timeseries/profile/{location-id}/{parameter-id} <timeSeries-profile-byID>
3225
/timeseries/profile-parser <timeSeries-profile-parser>
33-
/timeseries/profile-parser/{location-id}/{parameter-id} <timeSeries-profile-parser-byIDs>
26+
/timeseries/profile-parser/{location-id}/{parameter-id} <timeSeries-profile-parser-byID>
3427
/timeseries/profile-instance <timeSeries-profile-instance>
35-
/timeseries/profile-instance/{location-id}/{parameter-id}/{version} <timeSeries-profile-instance-byIDs>
36-
Shared Definitions <./shared_definitions.rst>
37-
38-
39-
.. note::
40-
41-
Using the intersphinx extension, a reference instead of the hard-coded link is preferred for maintainability:
42-
43-
See #:ref:#`cwmsdb:time-series` for details.
44-
45-
Once the build on the CWMS Database docs is live and stable each section that needs to be referenced
46-
will need a label added to it in the cwms-database docs like this:
47-
48-
.. code-block::
49-
50-
.. _time-series:
51-
52-
Time Series
53-
---------------
28+
/timeseries/profile-instance/{location-id}/{parameter-id}/{version} <timeSeries-profile-instance-byID>

‎docs/source/endpoints/timeSeries_endpoints/shared_definitions.rst‎

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,59 @@ Shared timeseries endpoint parameters
66
Shared parameter definitions
77
----------------------------
88

9-
This section lists and describes the parameters that are shared across multiple TimeSeries endpoints.
9+
This section lists and describes common parameters that are used by multiple TimeSeries endpoints.
1010
If the parameter is only used by a single endpoint, please refer to that endpoint's documentation for details.
1111
If a shared parameter has endpoint-specific behavior or constraints, those details will be noted in the individual
1212
endpoint documentation.
1313

1414
.. _def-end:
1515

1616
end
17-
End date/time for the time series data to stop.
17+
The date and time marking the end of the time window for data included in the response.
18+
The format for this field is ISO 8601 extended with optional offset and timezone.
19+
20+
.. code-block:: sql
21+
22+
Example:
23+
YYYY-MM-ddThh:mm:ss[Z[VV]]
24+
2021-06-10T13:00:00-07:00 OR 2025-10-25T12:25:00Z
25+
26+
.. note::
27+
Detailed documentation for Timestamps usage in CDA is currently in development and will be available at
28+
https://cwms-data.usace.army.mil/cwms-data/timestamps in a future release.
29+
1830

1931
.. _def-location-id:
2032

2133
location-id
22-
Description pending.
34+
`CWMS database - Location Naming <https://cwms-database.readthedocs.io/en/latest/naming.html#locations>`_
35+
`CWMS database - Location Definition <https://cwms-database.readthedocs.io/en/latest/locations.html#overview>`_
2336

2437
.. _def-location-mask:
2538

2639
location-mask
27-
Description pending.
40+
A regular expression used to filter the location name associated with the queried time series data. See the Regex
41+
documentation page for more information on usage:
42+
43+
.. note::
44+
Detailed documentation for Regex usage in CDA is currently in development and will be available at
45+
https://cwms-data.usace.army.mil/cwms-data/regexp in a future release.
2846

2947
.. _def-office:
3048

3149
office
32-
The organizational context used to scope data access and defaults. Some endpoints infer a default office; you can also specify it explicitly.
50+
The organizational context used to scope data access and defaults. Some endpoints infer a default office;
51+
you can also specify it explicitly.
3352

3453
.. _def-office-mask:
3554

3655
office-mask
37-
Description pending.
56+
A regular expression used to filter the office identifier associated with the queried time series data.
57+
See the Regex documentation page for more information on usage:
58+
59+
.. note::
60+
Detailed documentation for Regex usage in CDA is currently in development and will be available at
61+
https://cwms-data.usace.army.mil/cwms-data/regexp in a future release.
3862

3963
.. _def-page:
4064

@@ -49,24 +73,56 @@ page-size
4973
.. _def-parameter-id:
5074

5175
parameter-id
52-
Description pending.
76+
A text identifier specifying the type of data measured by the time series, such as "Flow", "Stage", "Elev", etc.
77+
78+
.. note::
79+
This link will take you to the Parameter Types definition. Scroll up one section to see the Parameter Definition.
80+
`CWMS database - parameter types <https://cwms-database.readthedocs.io/en/latest/naming.html#parameter-types>`_
81+
82+
As soon as this link is repaired, we will replace the above link with the correct one:
83+
`CWMS database - parameters <https://cwms-database.readthedocs.io/en/latest/naming.html#parameters>`_
5384

5485
.. _def-parameter-id-mask:
5586

5687
parameter-id-mask
57-
Description pending.
88+
A regular expression used to filter the parameter of the queried time series data.
89+
See the Regex documentation for more information on usage:
90+
91+
.. note::
92+
Detailed documentation for Regex usage in CDA is currently in development and will be available at
93+
https://cwms-data.usace.army.mil/cwms-data/regexp in a future release.
94+
95+
.. _def-start:
96+
97+
start (also referred to as begin)
98+
The date and time marking the beginning of the time window for data included in the response.
99+
The format for this field is ISO 8601 extended with optional offset and timezone.
100+
101+
.. code-block:: sql
102+
103+
Example:
104+
YYYY-MM-ddThh:mm:ss[Z[VV]]
105+
2021-06-10T13:00:00-07:00 OR 2025-10-25T12:25:00Z
106+
107+
.. note::
108+
Detailed documentation for Timestamps usage in CDA is currently in development and will be available at
109+
https://cwms-data.usace.army.mil/cwms-data/timestamps in a future release.
58110

59111
.. _def-timezone:
60112

61113
timezone
62-
Description pending.
114+
The timezone to use for retrieved time data, such as "UTC", "America/Los_Angeles", etc.
63115

64116
.. _def-unit:
65117

66-
unit
67-
Deprecated; prefer units or unit-system.
118+
unit `(Deprecated, prefer units or unit-system)`
119+
The unit system or specific unit to convert the response data into. Available unit systems are SI or EN.
120+
Examples of other units are m, ft, m3, etc.
121+
For reference: `CWMS database - units <https://cwms-database.readthedocs.io/en/latest/naming.html#units>`_
68122

69123
.. _def-version-date:
70124

71125
version-date
72-
Description pending.
126+
A date associated with a time series to make identification of the most recent data possible.
127+
Often uses the forecast date.
128+

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _timeseries-profile-byID-endpoint:
2+
3+
TimeSeries — GET /timeseries/profile/{location-id}/{parameter-id}
4+
===================================================================
5+
6+
7+
What it does
8+
------------
9+
Retrieves a specific time series profile for a given location and parameter.
10+
11+
A "profile" stores multiple values for each point in time. Think of it as a combination of time series data
12+
and paired data. It’s called a “profile” because it’s often used for things like temperature profiles in lakes over time.
13+
14+
In profile data, there is:
15+
16+
- An independent variable (e.g., Depth)
17+
- Dependent variables (e.g., Temperature at those depths over time)
18+
19+
The independent variable describes the dependent variables and is NOT tied to time. For example, in a lake temperature
20+
profile, depths are the independent variable, and temperatures at those depths are the dependent variables.
21+
22+
The endpoint path must include the independent variable name, followed by a dash "-", and then the dependent variable
23+
name. For example: `/Depth-Temperature/`.
24+
25+
Important Rules:
26+
27+
- The number of independent variables must stay consistent across the entire dataset. For example, if you have 10 depth
28+
readings, you must keep 10 depth readings for the entire dataset (missing values can be marked as such).
29+
- You must include an independent variable set, even if it's not used. For example, if you store multiple time series
30+
values, you still need an independent variable array, (it can contain zeros if unused).
31+
32+
Profile data can include quality indicators and notes, similar to other time series data. It can use regular or
33+
irregular intervals, with minute granularity (default) or second granularity.
34+
35+
When to use
36+
-----------
37+
- You wish to retrieve a specific time series profile and already know the location and parameter.
38+
39+
40+
.. csv-table:: GET /timeseries/profile/{location-id}/{parameter-id} - Endpoint Parameters
41+
:header: "Parameter", "Description", "Required"
42+
:widths: 20, 60, 15
43+
44+
location-id,":ref:`def-location-id`","Yes"
45+
parameter-id,":ref:`def-parameter-id`","Yes"
46+
office,":ref:`def-office`",""
47+
48+
Examples
49+
--------
50+
- Fetch a profile for a location and parameter:
51+
52+
.. code-block::
53+
54+
GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ
55+
56+
See the consolidated API documentation: :doc:`/api-references`.
57+
58+
.. include:: /_includes/feedback_button.rst

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

Lines changed: 0 additions & 33 deletions
This file was deleted.

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. _timeSeries-profile-instance-byID-endpoint:
2+
3+
TimeSeries — GET /timeseries/profile-instance/{location-id}/{parameter-id}/{version}
4+
======================================================================================
5+
6+
What it does
7+
------------
8+
Retrieves a specific versioned profile instance for a location and parameter.
9+
10+
When to use
11+
-----------
12+
- To retrieve a specific instance of a time series profile with a known version, parameter, and location.
13+
14+
15+
.. csv-table:: GET /timeseries/profile-instance{location-id}/{parameter-id}/{version} - Endpoint Parameters
16+
:header: "Parameter", "Description", "Required"
17+
:widths: 20, 60, 15
18+
19+
location-id,":ref:`def-location-id`","Yes"
20+
parameter-id,":ref:`def-parameter-id`","Yes"
21+
version,"`CWMS database - version <https://cwms-database.readthedocs.io/en/latest/naming.html#versions>`_","Yes"
22+
office,":ref:`def-office`","Yes"
23+
timezone,":ref:`def-timezone`",""
24+
version-date,":ref:`def-version-date`",""
25+
unit,":ref:`def-unit`","Yes"
26+
start-time-inclusive,"Resulting data includes data from the exact start time of the time window (true/false).",""
27+
end-time-inclusive,"Resulting data includes data from the exact end of the time window (true/false).",""
28+
previous,"Include the previous time window of the time series profile instance (true/false).",""
29+
next,"Include the next time window of the time series profile instance (true/false).",""
30+
max-version,"Use the most recent version date (true/false). Only for time series utilizing dates in the version.",""
31+
start,":ref:`def-start`","Yes"
32+
end, ":ref:`def-end`", "Yes"
33+
page,":ref:`def-page`",""
34+
page-size,":ref:`def-page-size`",""
35+
36+
37+
Examples
38+
--------
39+
- Fetch a specific instance version:
40+
41+
.. code-block:: sql
42+
43+
GET /timeseries/profile-instance/LOC123/Flow/2?office=HQ
44+
45+
46+
See the consolidated API documentation: :doc:`/api-references`.
47+
48+
.. include:: /_includes/feedback_button.rst

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

Lines changed: 0 additions & 45 deletions
This file was deleted.

0 commit comments

Comments
 (0)