[Bug]: About vertical datum conversion

Describe the bug

Hi there,

We are using the CWMS Data API endpoint below to retrieve time-series elevation data and are currently working on handling conversions between NAVD88 and NGVD29:

https://cwms-data.usace.army.mil/cwms-data/timeseries?

In the Swagger UI, the datum query parameter is described as follows:

datum (string, query): Specifies the elevation datum of the response. This field affects only elevation location levels. Valid values are NAVD88 and NGVD29. This parameter is not supported for application/json;version=2 or application/xml;version=2.

Based on this description, my understanding is that the datum parameter should not be supported when using API version 2, is that true?

However, I am currently able to specify datum while requesting API version 2, and the API appears to honor it. I tested both:

-H 'accept: application/json'

and

-H 'accept: application/json;version=2'

while keeping the other parameters unchanged. In both cases, specifying either datum=NGVD29 or datum=NAVD88 appears to adjust the returned elevation values to the requested datum.

The main issue I observed is related to pagination. When datum is specified and the requested date range contains more records than the specified page-size, the API returns only the first page and does not include a next-page field. If I remove the datum parameter while keeping everything else unchanged, pagination works normally and next-page is returned.

Could you please clarify whether supporting datum for API version 2 is intentional? If it is supported, the missing pagination information when datum is specified appears to be a bug.

Expected behavior

When the datum parameter is supported, the API should:

1. Return elevation values converted to the requested datum (NAVD88 or NGVD29).
2. Return the next-page parameter when the result contains more than one page, so that the remaining time-series data can be retrieved.

If datum is not intended to be supported in API version 2, it would also be helpful to clarify the recommended method for retrieving or converting time-series data to a desired vertical datum.

To Reproduce

1. API version 2 without datum: the response contains the expected data and a next-page parameter:
   curl -X 'GET'
   'https://cwms-data.usace.army.mil/cwms-data/timeseries?name=HUGO.Elev.Inst.1Hour.0.Ccp-Rev&office=SWT&begin=2020-01-01T00%3A00%3A00Z&page-size=10&_cb=1789518779642'
   -H 'accept: application/json;version=2'
   -H 'Cache-Control: no-cache, no-store, max-age=0'
   -H 'Pragma: no-cache'

Results:
{
"begin": "2020-01-01T00:00:00Z",
"date-version-type": "UNVERSIONED",
"end": "2026-09-16T00:32:59.867083Z",
"interval": "PT1H",
"interval-offset": 0,
"name": "HUGO.Elev.Inst.1Hour.0.Ccp-Rev",
"next-page": "MTU3Nzg3MjgwMDAwMHx8NTg4MDF8fDEw",
"office-id": "SWT",
"page": "MTU3NzgzNjgwMDAwMHx8NTg4MDF8fDEw",
"page-size": 10,
"time-zone": "US/Central",
"total": 58801,
"units": "ft",
"value-columns": [
{
"name": "date-time",
"ordinal": 1,
"datatype": "java.sql.Timestamp"
},
{
"name": "value",
"ordinal": 2,
"datatype": "java.lang.Double"
},
{
"name": "quality-code",
"ordinal": 3,
"datatype": "int"
}
],
"values": [
[
1577836800000,
406.74999999999994,
0
],
[
1577840400000,
406.75999999999993,
0
],
[
1577844000000,
406.77,
0
],
[
1577847600000,
406.7799999999999,
0
],
[
1577851200000,
406.78999999999996,
0
],
[
1577854800000,
406.79999999999995,
0
],
[
1577858400000,
406.80999999999995,
0
],
[
1577862000000,
406.81999999999994,
0
],
[
1577865600000,
406.81999999999994,
0
],
[
1577869200000,
406.8399999999999,
0
]
],
"vertical-datum-info": {
"office": "SWT",
"unit": "ft",
"location": "HUGO",
"native-datum": "NGVD-29",
"elevation": 351.499,
"offsets": [
{
"estimate": true,
"to-datum": "NAVD-88",
"value": 0.1785
}
]
}
}

2. API version 2 with datum=NAVD88: the elevation values appear to be converted to NAVD88, but no next-page parameter is returned:

curl -X 'GET'
'https://cwms-data.usace.army.mil/cwms-data/timeseries?name=HUGO.Elev.Inst.1Hour.0.Ccp-Rev&office=SWT&datum=NAVD88&begin=2020-01-01T00%3A00%3A00Z&page-size=10&_cb=1789518949967'
-H 'accept: application/json;version=2'
-H 'Cache-Control: no-cache, no-store, max-age=0'
-H 'Pragma: no-cache'

Results:
{
"begin": "2020-01-01T00:00:00Z",
"date-version-type": "UNVERSIONED",
"end": "2026-09-16T00:35:50.358309Z",
"interval": "PT1H",
"interval-offset": 0,
"name": "HUGO.Elev.Inst.1Hour.0.Ccp-Rev",
"office-id": "SWT",
"page": "TVRVM056Z3pOamd3TURBd01IeDhOVGc0TURGOGZERXd8fDU4ODAxfHwxMA==",
"page-size": 10,
"time-zone": "US/Central",
"total": 58801,
"units": "ft",
"value-columns": [
{
"name": "date-time",
"ordinal": 1,
"datatype": "java.sql.Timestamp"
},
{
"name": "value",
"ordinal": 2,
"datatype": "java.lang.Double"
},
{
"name": "quality-code",
"ordinal": 3,
"datatype": "int"
}
],
"values": [
[
1577836800000,
406.92849999999993,
0
],
[
1577840400000,
406.9384999999999,
0
],
[
1577844000000,
406.94849999999997,
0
],
[
1577847600000,
406.9584999999999,
0
],
[
1577851200000,
406.96849999999995,
0
],
[
1577854800000,
406.97849999999994,
0
],
[
1577858400000,
406.98849999999993,
0
],
[
1577862000000,
406.9984999999999,
0
],
[
1577865600000,
406.9984999999999,
0
],
[
1577869200000,
407.0184999999999,
0
]
],
"vertical-datum-info": {
"office": "SWT",
"unit": "ft",
"location": "HUGO",
"native-datum": "NAVD-88",
"elevation": 351.6775,
"offsets": [
{
"estimate": true,
"to-datum": "NGVD-29",
"value": -0.1785
}
]
}
}

3. API version 1 with datum=NAVD88: the same pagination issue occurs: the requested datum appears to be applied, but no next-page parameter is returned.

curl -X 'GET'
'https://cwms-data.usace.army.mil/cwms-data/timeseries?name=HUGO.Elev.Inst.1Hour.0.Ccp-Rev&office=SWT&datum=NAVD88&begin=2020-01-01T00%3A00%3A00Z&page-size=10&_cb=1789520122525'
-H 'accept: application/json'
-H 'Cache-Control: no-cache, no-store, max-age=0'
-H 'Pragma: no-cache'

Results:
{
"begin": "2020-01-01T00:00:00Z",
"date-version-type": "UNVERSIONED",
"end": "2026-09-16T00:55:22.729997Z",
"interval": "PT1H",
"interval-offset": 0,
"name": "HUGO.Elev.Inst.1Hour.0.Ccp-Rev",
"office-id": "SWT",
"page": "TVRVM056Z3pOamd3TURBd01IeDhOVGc0TURGOGZERXd8fDU4ODAxfHwxMA==",
"page-size": 10,
"time-zone": "US/Central",
"total": 58801,
"units": "ft",
"value-columns": [
{
"name": "date-time",
"ordinal": 1,
"datatype": "java.sql.Timestamp"
},
{
"name": "value",
"ordinal": 2,
"datatype": "java.lang.Double"
},
{
"name": "quality-code",
"ordinal": 3,
"datatype": "int"
}
],
"values": [
[
1577836800000,
406.92849999999993,
0
],
[
1577840400000,
406.9384999999999,
0
],
[
1577844000000,
406.94849999999997,
0
],
[
1577847600000,
406.9584999999999,
0
],
[
1577851200000,
406.96849999999995,
0
],
[
1577854800000,
406.97849999999994,
0
],
[
1577858400000,
406.98849999999993,
0
],
[
1577862000000,
406.9984999999999,
0
],
[
1577865600000,
406.9984999999999,
0
],
[
1577869200000,
407.0184999999999,
0
]
],
"vertical-datum-info": {
"office": "SWT",
"unit": "ft",
"location": "HUGO",
"native-datum": "NAVD-88",
"elevation": 351.6775,
"offsets": [
{
"estimate": true,
"to-datum": "NGVD-29",
"value": -0.1785
}
]
}
}

Priority

High

CDA Version

2026.05.12-i

Additional context

No response

Start by reproducing the /cwms-data/timeseries curl requests in the issue, comparing pagination with and without datum for API versions 1 and 2. Trace how datum conversion and page metadata are handled, then verify that supported requests return next-page information or that the API clearly rejects or documents unsupported combinations.