Making CQL queries
While you can make most common API queries using query arguments in your URL, it can be difficult to make more complex requests using these URL arguments alone. While it's often more efficient to try and break your query down into multiple smaller requests, the Water Data API platform also supports making more complex queries using the Common Query Language standard. This page explains how you can make these queries and provides a number of example requests.
These examples mostly require making POST requests, which you can't make in your browser. The examples below use the curl library, but you should be able to make POST requests in any programming language of your choice as well.
Requests that use CQL all follow the same basic pattern, swapping out the all-caps sections in angle brackets for actual query parameters:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/<ENDPOINT TO QUERY>/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "<OPERATION TO PERFORM>",
"args": [
"<ARGUMENTS TO OPERATION>"
]
}'
You provide the link to the items page of the collection you want to query, the type of query you want to perform, and arguments to that query operation. By varying these parameters, you can make many different types of queries to these APIs.
Query for data with values "in" a fixed set
For instance, a common request is to query for multiple monitoring locations or parameter codes in a single query. While it will often be faster to break your request into multiple queries, one per monitoring location or parameter code, you could also use the "in" operator to query for multiple values at a time:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "in",
"args": [
{ "property": "parameter_code" },
[ "00060", "00065" ]
]
}'
Here, we're querying the time-series-metadata endpoint using the "in" operator. We then provide two arguments to the "in" operator -- the first one is a named argument that specifies which property we want to check, and the second is an unnamed argument that lists all the parameter codes we want included. Altogether, this query will return all the time series which have parameter codes of either 00060 or 00065:
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-05-09T09:08:52.452174",
"end":"2025-05-09T09:00:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-10172640",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2006-05-18T06:00:00",
"computation_period_identifier":"Points",
"thresholds":[],
"primary":"Primary"
},
"id":"00009b3da7e44a96a283bc413ff2de48",
"geometry":{
"type":"Point",
"coordinates":[
-112.13859444444445,
40.780852777777774
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-05-09T06:50:31.310775",
"end":"2025-05-09T06:45:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-01017960",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2003-10-01T04:00:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"2 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:07:52.3815962Z",
"SuppressData":false,
"ReferenceValue":2320
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"10 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:12.3076592Z",
"SuppressData":false,
"ReferenceValue":3580
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"50 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:33.0016344Z",
"SuppressData":false,
"ReferenceValue":4720
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"100 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:57.0907346Z",
"SuppressData":false,
"ReferenceValue":5210
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"No discharging < 15 cfs for Tate & Lyle (call if < 20 cfs)",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"Comments":"Call Tate & Lyle if <20 cfs",
"StartTime":"2015-10-19T00:00:00.0000000-05:00",
"AppliedTime":"0001-01-01T00:00:00Z",
"SuppressData":false,
"ReferenceValue":20,
"SecondaryReferenceValue":25
}
],
"Severity":0,
"Description":"NWISWeb reference line displayed to USGS level users",
"DisplayColor":"#00CCFF",
"ReferenceCode":"NWISWeb ref level - USGS",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary"
},
"id":"0000cad393b040af82fd418466fc76cd",
"geometry":{
"type":"Point",
"coordinates":[
-67.8813888888889,
46.105
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2019-06-19T17:36:08.802107",
"end":"1997-01-01T10:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-16759080",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1963-01-16T10:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"00019bc6bc6146e18320f87378606519",
"geometry":{
"type":"Point",
"coordinates":[
-155.7280520013026,
19.86667611965882
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-05-09T06:31:41.016746",
"end":"2025-05-09T06:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-08025500",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1955-10-02T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary"
},
"id":"0001b4c983f34d6796fdb39145740404",
"geometry":{
"type":"Point",
"coordinates":[
-93.5157294738185,
31.3071273652596
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2025-05-09T07:45:55.992761",
"end":"2025-05-09T07:30:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"Headwater",
"monitoring_location_id":"USGS-02431011",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":"00011",
"begin":"2017-06-02T13:45:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"upper limit",
"Type":"ThresholdAbove",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"0001-01-01T00:00:00.0000000+00:00",
"AppliedTime":"2017-09-06T13:51:18.9943235Z",
"SuppressData":true,
"ReferenceValue":275
}
],
"Severity":0,
"Description":"Unspecified threshold value",
"DisplayColor":"#990600",
"ReferenceCode":"AQUARIUS only",
"ProcessingOrder":"Suppression"
},
{
"Name":"lower limit",
"Type":"ThresholdBelow",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"0001-01-01T00:00:00.0000000+00:00",
"AppliedTime":"2017-09-06T13:50:34.3252767Z",
"SuppressData":true,
"ReferenceValue":269.5
}
],
"Severity":0,
"Description":"Unspecified threshold value",
"DisplayColor":"#990600",
"ReferenceCode":"AQUARIUS only",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary"
},
"id":"0001c2bd82ab4713aca2753b1a80712c",
"geometry":{
"type":"Point",
"coordinates":[
-88.4241666666667,
34.2549722222222
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2019-06-20T11:04:48.243216",
"end":"1982-12-27T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-07367300",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":null,
"begin":"1954-05-13T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"0001c934c87544838a53cb012fb8f1c6",
"geometry":{
"type":"Point",
"coordinates":[
-92.2612495161081,
32.4932017390148
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2021-08-27T18:58:18.094579",
"end":"2020-07-01T08:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-09419659",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1988-01-27T08:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary"
},
"id":"0001de6b28634f478d714ed9021f26be",
"geometry":{
"type":"Point",
"coordinates":[
-115.074280555556,
36.2286416666667
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2022-12-04T22:58:25.889646",
"end":"2021-01-01T07:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-06131100",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1974-01-01T07:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"0004a3d749d34e3288e791a702d6fda0",
"geometry":{
"type":"Point",
"coordinates":[
-106.170841666667,
47.3858805555556
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2019-06-20T01:55:20.010637",
"end":"1985-11-19T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-05570350",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1972-09-14T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"00055464292d473ba105749bbc0990f0",
"geometry":{
"type":"Point",
"coordinates":[
-90.0534507480865,
40.4975394281952
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2017-05-13T14:58:45.093148",
"end":"1983-12-20T06:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-06340780",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1977-09-02T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary"
},
"id":"000660ad835d4bb4bec9ebaf6ad85175",
"geometry":{
"type":"Point",
"coordinates":[
-101.309878686776,
47.2691636197024
]
}
}
],
"numberReturned":10,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=html"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?offset=10"
},
{
"type":"application/json",
"title":"Time series metadata",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata"
}
],
"timeStamp":"2025-05-09T19:16:30.896580Z"
}
There are plenty of other operators available, including various spatial functions and temporal functions supported by this server. On the rest of this page, we'll walk through some of the other most common operators.
Query for data "between" two values
Often the values that you're interested in are in a specific range -- for instance, you want a set of statistics that all have similar statistic_id fields. In those situations, you can use the "between" operator to select all values that fall within two values (inclusively), specifying the smallest and largest values that you are interested in:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "between",
"args": [
{ "property": "statistic_id" },
[ "00001", "00003" ]
]
}'
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"parameter_name":"Temperature, water",
"statistic_id":"00002",
"begin":"1983-11-04T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"degC",
"parameter_code":"00010",
"last_modified":"2017-05-07T20:53:29.551297",
"end":"1985-04-17T05:00:00",
"computation_identifier":"Min",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-01379790",
"web_description":null
},
"id":"000068b2a47b45708c656bcff5264f54",
"geometry":{
"type":"Point",
"coordinates":[
-74.5836111111111,
40.9177777777778
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Specific cond at 25C",
"statistic_id":"00001",
"begin":"2011-02-13T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"uS/cm",
"parameter_code":"00095",
"last_modified":"2017-10-14T18:50:59.438311",
"end":"2015-11-03T05:00:00",
"computation_identifier":"Max",
"sublocation_identifier":"Downstream Lock Side",
"monitoring_location_id":"USGS-03277200",
"web_description":null
},
"id":"00011cb2ffa14f01ae22886ace3d5da9",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1955-10-02T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2025-05-09T06:31:41.016746",
"end":"2025-05-09T06:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-08025500",
"web_description":null
},
"id":"0001b4c983f34d6796fdb39145740404",
"geometry":{
"type":"Point",
"coordinates":[
-93.5157294738185,
31.3071273652596
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1988-01-27T08:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2021-08-27T18:58:18.094579",
"end":"2020-07-01T08:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-09419659",
"web_description":null
},
"id":"0001de6b28634f478d714ed9021f26be",
"geometry":{
"type":"Point",
"coordinates":[
-115.074280555556,
36.2286416666667
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Water level, depth LSD",
"statistic_id":"00002",
"begin":"2011-04-01T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft",
"parameter_code":"72019",
"last_modified":"2024-01-12T17:40:14.604168",
"end":"2023-10-01T05:00:00",
"computation_identifier":"Min",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-351132079275301",
"web_description":null
},
"id":"00024da3e7be4be4bc1a0e74e65f9c66",
"geometry":{
"type":"Point",
"coordinates":[
-79.46475,
35.192
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Temperature, air",
"statistic_id":"00002",
"begin":"2002-07-14T08:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"degC",
"parameter_code":"00020",
"last_modified":"2017-04-04T02:04:29.365468",
"end":"2015-04-16T08:00:00",
"computation_identifier":"Min",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-10337500",
"web_description":null
},
"id":"0002c9bc05714c26bd359dfe60ce821d",
"geometry":{
"type":"Point",
"coordinates":[
-120.14433725998278,
39.16627309425266
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Temperature, water",
"statistic_id":"00002",
"begin":"2004-10-16T07:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"degC",
"parameter_code":"00010",
"last_modified":"2025-05-09T07:07:41.098714",
"end":"2025-05-09T07:00:00",
"computation_identifier":"Min",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-13016450",
"web_description":null
},
"id":"000325d95e614de6872a5f59f7930b25",
"geometry":{
"type":"Point",
"coordinates":[
-110.871599998594,
43.5007600531178
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Water level, depth LSD",
"statistic_id":"00002",
"begin":"2017-03-15T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":null,
"unit_of_measure":"ft",
"parameter_code":"72019",
"last_modified":"2019-03-07T18:42:34.341949",
"end":"2018-10-31T06:00:00",
"computation_identifier":"Min",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-433247092260703",
"web_description":null
},
"id":"0003ebcd6fe24306b29e96d6f1c58eb3",
"geometry":{
"type":"Point",
"coordinates":[
-92.4354111111111,
43.5464888888889
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Specific cond at 25C",
"statistic_id":"00003",
"begin":"2001-12-21T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"uS/cm",
"parameter_code":"00095",
"last_modified":"2025-05-09T05:36:02.749830",
"end":"2025-05-09T05:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-02266200",
"web_description":null
},
"id":"000436b687434cb3af974c05fe68dc4f",
"geometry":{
"type":"Point",
"coordinates":[
-81.6164632035713,
28.3850074920712
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Soil moisture",
"statistic_id":"00001",
"begin":"2012-08-16T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"%",
"parameter_code":"74207",
"last_modified":"2017-06-05T15:45:39.316546",
"end":"2015-11-05T06:00:00",
"computation_identifier":"Max",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-434034088252401",
"web_description":null
},
"id":"0004b63028174ca2b732e788370c87b2",
"geometry":{
"type":"Point",
"coordinates":[
-88.4233611111111,
43.6760555555555
]
}
}
],
"numberReturned":10,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=html"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?offset=10"
},
{
"type":"application/json",
"title":"Time series metadata",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata"
}
],
"timeStamp":"2025-05-09T19:53:51.467946Z"
}
Query for data that "isNull"
These endpoints return null for empty fields. If you're interested in filtering down to just data with null values for a specific field (for instance, filtering to just daily values without a qualifier) you can use the isNull operator:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "isNull",
"args": [
{ "property": "qualifier" }
]
}'
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-02172050",
"statistic_id":"00003",
"time_series_id":"b014dd13ca5a4fc8b802bbbcf7b1278a",
"value":"24.5",
"approval_status":"Approved",
"last_modified":"2025-03-11T18:52:55.185984+00:00",
"parameter_code":"00010",
"time":"2000-09-20",
"unit_of_measure":"degC",
"qualifier":null
},
"id":"00000007-1343-41f0-80ac-c7ae4f4bce2c",
"geometry":{
"type":"Point",
"coordinates":[
-79.9357777777778,
33.0576666666667
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-02289019",
"statistic_id":"00003",
"time_series_id":"d7c6271e2e194428ba9cf9c032539e0f",
"value":"489",
"approval_status":null,
"last_modified":"2024-12-03T09:23:01.506761+00:00",
"parameter_code":"00060",
"time":"2020-10-24",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"0000000a-c34b-497d-9391-c9e37e4d80a2",
"geometry":{
"type":"Point",
"coordinates":[
-80.7694722222222,
25.7618333333333
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-06621000",
"statistic_id":"00003",
"time_series_id":"486a1343bed348019358ea2fd7b07b4c",
"value":"11.0",
"approval_status":"Approved",
"last_modified":"2025-03-12T00:20:17.759174+00:00",
"parameter_code":"00060",
"time":"1953-12-24",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"00000030-163d-45f4-a9d0-908c5b23e563",
"geometry":{
"type":"Point",
"coordinates":[
-106.307567099172,
41.0810672871383
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-03081000",
"statistic_id":"00001",
"time_series_id":"8968f2ea57a44a7e8b9269dcd1f3aa9f",
"value":"10.8",
"approval_status":"Approved",
"last_modified":"2025-04-11T04:59:02.642012+00:00",
"parameter_code":"00300",
"time":"2007-12-01",
"unit_of_measure":"mg/l",
"qualifier":null
},
"id":"00000033-1bf5-4b89-80d1-2212608f94c0",
"geometry":{
"type":"Point",
"coordinates":[
-79.3725353377293,
39.8275767388252
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-03535912",
"statistic_id":"00003",
"time_series_id":"b9a40e2f0a00420a80d1ad5c0c93c9dd",
"value":"3410",
"approval_status":"Approved",
"last_modified":"2025-03-11T19:35:56.340486+00:00",
"parameter_code":"00060",
"time":"1992-07-12",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"00000034-2a39-4eae-b7ca-02b949ca1c06",
"geometry":{
"type":"Point",
"coordinates":[
-84.3007557963552,
35.88535522096
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-13251000",
"statistic_id":"00003",
"time_series_id":"1fc12c3097234a41a4adfc0745997646",
"value":"1260",
"approval_status":"Approved",
"last_modified":"2025-03-11T02:41:18.734415+00:00",
"parameter_code":"00060",
"time":"2018-08-25",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"00000059-e424-4d95-b25c-0a441f68131e",
"geometry":{
"type":"Point",
"coordinates":[
-116.925277777778,
44.0422222222222
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-07237500",
"statistic_id":"00003",
"time_series_id":"66605858a7a6465d928183ad4ca5832f",
"value":"45.1",
"approval_status":"Approved",
"last_modified":"2025-03-11T16:15:52.985007+00:00",
"parameter_code":"00060",
"time":"2018-08-19",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"0000005f-657d-4d20-9dc2-dc13043cd9d0",
"geometry":{
"type":"Point",
"coordinates":[
-99.2784383440768,
36.4367033648087
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-07061290",
"statistic_id":"00001",
"time_series_id":"7b1c6ae05a4144fc92c424d9f58b5f50",
"value":"3.2",
"approval_status":"Approved",
"last_modified":"2025-04-05T06:24:53.244560+00:00",
"parameter_code":"63680",
"time":"2013-12-30",
"unit_of_measure":"_FNU",
"qualifier":null
},
"id":"00000073-cee3-4630-85c5-4692bcd3e965",
"geometry":{
"type":"Point",
"coordinates":[
-90.8383333333333,
37.4936111111111
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-424004088440601",
"statistic_id":"00001",
"time_series_id":"348d4b2289a9487eb8a07f17998cbef9",
"value":"76.04",
"approval_status":"Provisional",
"last_modified":"2025-04-11T18:18:25.605094+00:00",
"parameter_code":"72019",
"time":"2025-02-01",
"unit_of_measure":"ft",
"qualifier":null
},
"id":"00000075-700b-4616-bb69-c918ad2d6898",
"geometry":{
"type":"Point",
"coordinates":[
-88.7346,
42.66780555555555
]
}
},
{
"type":"Feature",
"properties":{
"monitoring_location_id":"USGS-03316000",
"statistic_id":"00003",
"time_series_id":"722305c81da7411d8b381b3ae1c92f8a",
"value":"54.0",
"approval_status":"Approved",
"last_modified":"2025-03-11T05:41:23.675424+00:00",
"parameter_code":"00060",
"time":"1957-05-04",
"unit_of_measure":"ft^3/s",
"qualifier":null
},
"id":"0000007d-9b78-4a35-94e1-8605235d8686",
"geometry":{
"type":"Point",
"coordinates":[
-86.907218967024,
37.0042112113962
]
}
}
],
"numberReturned":10,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?offset=10"
},
{
"type":"application/json",
"title":"Daily values",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
}
],
"timeStamp":"2025-05-09T19:43:37.841285Z"
}
Combining CQL queries
While these operators individually let you make more complex queries, you can get much more flexibility by combining multiple CQL queries together using a "combination" operator. These operators work mostly the same way as the operators we've already talked about, except they take other CQL queries as their arguments.
"and"
For example, to filter down to both a list of monitoring locations and a list of parameter codes, we can provide two separate "in" queries as arguments to the "and" operator:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "and",
"args": [
{
"op": "in",
"args": [
{ "property": "parameter_code" },
[ "00060", "00065" ]
]
},
{
"op": "in",
"args": [
{ "property": "monitoring_location_id" },
[ "USGS-07367300", "USGS-03277200" ]
]
}
]
}'
Note that both of the arguments we provided are valid CQL queries of their own. The "and" operator will apply them both and only return results which satisfy both conditions:
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2019-06-20T11:04:48.243216",
"end":"1982-12-27T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-07367300",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":null,
"begin":"1954-05-13T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"0001c934c87544838a53cb012fb8f1c6",
"geometry":{
"type":"Point",
"coordinates":[
-92.2612495161081,
32.4932017390148
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2025-05-09T08:49:56.417413",
"end":"2025-05-09T08:45:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"Downstream Lock Side",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":"00011",
"begin":"1987-03-27T16:00:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"Operational limit (maximum) Equipment Limit",
"Type":"ThresholdAbove",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2001-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2017-01-01T17:29:47.131456Z",
"SuppressData":true,
"ReferenceValue":60.72,
"SecondaryReferenceValue":54.648
}
],
"Severity":0,
"Description":"Values above a specified threshold limit",
"DisplayColor":"#CCCCCC",
"ReferenceCode":"Operational limit - high-Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"Operational limit (minimum) Equipment Limit",
"Type":"ThresholdBelow",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2001-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2017-01-01T17:29:48.1684483Z",
"SuppressData":true,
"ReferenceValue":8,
"SecondaryReferenceValue":8.2
}
],
"Severity":0,
"Description":"Values below a specified threshold limit",
"DisplayColor":"#666666",
"ReferenceCode":"Operational limit - low-Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"National Weather Service Floodstage",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2001-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2017-01-01T17:29:49.3508397Z",
"SuppressData":false,
"ReferenceValue":51
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#00CCFF",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary"
},
"id":"086374fa523a47448b255f477e830a64",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2025-04-08T18:50:25.318427",
"end":"2025-04-08T18:45:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1971-02-09T05:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"14279f60c8084d18bfea9a9b0bda7069",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2025-05-09T05:50:17.281779",
"end":"2025-05-09T05:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":"00003",
"begin":"1987-03-29T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary"
},
"id":"4c47e2dfb41147aba262df23cb147199",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-05-09T19:26:24.506503",
"end":"2025-05-10T05:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1970-05-02T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary"
},
"id":"68c0662bba654b24911712c25cf9a88e",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-05-09T08:19:00.425643",
"end":"2025-05-09T04:00:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2015-10-01T05:00:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"High Threshold",
"Type":"ThresholdAbove",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2021-11-02T00:00:00.0000000-05:00",
"AppliedTime":"2022-05-06T15:54:27.8121392Z",
"SuppressData":true,
"ReferenceValue":2000000
}
],
"Severity":0,
"Description":"Unspecified threshold value",
"DisplayColor":"#990600",
"ReferenceCode":"AQUARIUS only",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary"
},
"id":"730f6b4628d448e090f7d2679edfc0e2",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00065",
"last_modified":"2019-06-20T11:04:48.628423",
"end":"1982-12-27T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-07367300",
"web_description":null,
"unit_of_measure":"ft",
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1954-05-13T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"80e67299fafd468fa3afaf85827a41ab",
"geometry":{
"type":"Point",
"coordinates":[
-92.2612495161081,
32.4932017390148
]
}
},
{
"type":"Feature",
"properties":{
"parameter_code":"00060",
"last_modified":"2025-04-27T11:21:12.716160",
"end":"2025-04-09T00:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-03277200",
"web_description":null,
"unit_of_measure":"ft^3/s",
"parameter_name":"Discharge",
"statistic_id":null,
"begin":"1971-02-23T05:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary"
},
"id":"e641d5a3d7e84fdca103187fabb6e47e",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
}
],
"numberReturned":8,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=html"
},
{
"type":"application/json",
"title":"Time series metadata",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata"
}
],
"timeStamp":"2025-05-09T19:58:07.632117Z"
}
"or"
We could alternatively use the "or" operator to select observations which satisfy either requirement:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "or",
"args": [
{
"op": "in",
"args": [
{ "property": "parameter_code" },
[ "00060", "00065" ]
]
},
{
"op": "in",
"args": [
{ "property": "monitoring_location_id" },
[ "USGS-07367300", "USGS-03277200" ]
]
}
]
}'
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2006-05-18T06:00:00",
"computation_period_identifier":"Points",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2025-05-12T10:09:28.794889",
"end":"2025-05-12T10:00:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-10172640",
"web_description":null
},
"id":"00009b3da7e44a96a283bc413ff2de48",
"geometry":{
"type":"Point",
"coordinates":[
-112.13859444444445,
40.780852777777774
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2003-10-01T04:00:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"2 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:07:52.3815962Z",
"SuppressData":false,
"ReferenceValue":2320
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"10 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:12.3076592Z",
"SuppressData":false,
"ReferenceValue":3580
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"50 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:33.0016344Z",
"SuppressData":false,
"ReferenceValue":4720
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"100 Year Peak Flow *",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"2020-10-01T00:00:00.0000000-05:00",
"AppliedTime":"2021-01-22T14:08:57.0907346Z",
"SuppressData":false,
"ReferenceValue":5210
}
],
"Severity":0,
"Description":"Display reference value",
"DisplayColor":"#990600",
"ReferenceCode":"NWISWeb ref level - Public",
"ProcessingOrder":"Suppression"
},
{
"Name":"No discharging < 15 cfs for Tate & Lyle (call if < 20 cfs)",
"Type":"None",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"Comments":"Call Tate & Lyle if <20 cfs",
"StartTime":"2015-10-19T00:00:00.0000000-05:00",
"AppliedTime":"0001-01-01T00:00:00Z",
"SuppressData":false,
"ReferenceValue":20,
"SecondaryReferenceValue":25
}
],
"Severity":0,
"Description":"NWISWeb reference line displayed to USGS level users",
"DisplayColor":"#00CCFF",
"ReferenceCode":"NWISWeb ref level - USGS",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2025-05-12T06:51:17.258513",
"end":"2025-05-12T06:45:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-01017960",
"web_description":null
},
"id":"0000cad393b040af82fd418466fc76cd",
"geometry":{
"type":"Point",
"coordinates":[
-67.8813888888889,
46.105
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Specific cond at 25C",
"statistic_id":"00001",
"begin":"2011-02-13T05:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"uS/cm",
"parameter_code":"00095",
"last_modified":"2017-10-14T18:50:59.438311",
"end":"2015-11-03T05:00:00",
"computation_identifier":"Max",
"sublocation_identifier":"Downstream Lock Side",
"monitoring_location_id":"USGS-03277200",
"web_description":null
},
"id":"00011cb2ffa14f01ae22886ace3d5da9",
"geometry":{
"type":"Point",
"coordinates":[
-84.9723888888889,
38.77525
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1963-01-16T10:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft",
"parameter_code":"00065",
"last_modified":"2019-06-19T17:36:08.802107",
"end":"1997-01-01T10:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-16759080",
"web_description":null
},
"id":"00019bc6bc6146e18320f87378606519",
"geometry":{
"type":"Point",
"coordinates":[
-155.7280520013026,
19.86667611965882
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1955-10-02T06:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2025-05-12T06:31:46.282340",
"end":"2025-05-12T06:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-08025500",
"web_description":null
},
"id":"0001b4c983f34d6796fdb39145740404",
"geometry":{
"type":"Point",
"coordinates":[
-93.5157294738185,
31.3071273652596
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Gage height",
"statistic_id":"00011",
"begin":"2017-06-02T13:45:00",
"computation_period_identifier":"Points",
"thresholds":[
{
"Name":"upper limit",
"Type":"ThresholdAbove",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"0001-01-01T00:00:00.0000000+00:00",
"AppliedTime":"2017-09-06T13:51:18.9943235Z",
"SuppressData":true,
"ReferenceValue":275
}
],
"Severity":0,
"Description":"Unspecified threshold value",
"DisplayColor":"#990600",
"ReferenceCode":"AQUARIUS only",
"ProcessingOrder":"Suppression"
},
{
"Name":"lower limit",
"Type":"ThresholdBelow",
"Periods":[
{
"EndTime":"9999-12-31T23:59:59.9999999+00:00",
"StartTime":"0001-01-01T00:00:00.0000000+00:00",
"AppliedTime":"2017-09-06T13:50:34.3252767Z",
"SuppressData":true,
"ReferenceValue":269.5
}
],
"Severity":0,
"Description":"Unspecified threshold value",
"DisplayColor":"#990600",
"ReferenceCode":"AQUARIUS only",
"ProcessingOrder":"Suppression"
}
],
"primary":"Primary",
"unit_of_measure":"ft",
"parameter_code":"00065",
"last_modified":"2025-05-12T07:46:20.607429",
"end":"2025-05-12T07:30:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"Headwater",
"monitoring_location_id":"USGS-02431011",
"web_description":null
},
"id":"0001c2bd82ab4713aca2753b1a80712c",
"geometry":{
"type":"Point",
"coordinates":[
-88.4241666666667,
34.2549722222222
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":null,
"begin":"1954-05-13T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2019-06-20T11:04:48.243216",
"end":"1982-12-27T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-07367300",
"web_description":null
},
"id":"0001c934c87544838a53cb012fb8f1c6",
"geometry":{
"type":"Point",
"coordinates":[
-92.2612495161081,
32.4932017390148
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00003",
"begin":"1988-01-27T08:00:00",
"computation_period_identifier":"Daily",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2021-08-27T18:58:18.094579",
"end":"2020-07-01T08:00:00",
"computation_identifier":"Mean",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-09419659",
"web_description":null
},
"id":"0001de6b28634f478d714ed9021f26be",
"geometry":{
"type":"Point",
"coordinates":[
-115.074280555556,
36.2286416666667
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1974-01-01T07:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft",
"parameter_code":"00065",
"last_modified":"2022-12-04T22:58:25.889646",
"end":"2021-01-01T07:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-06131100",
"web_description":null
},
"id":"0004a3d749d34e3288e791a702d6fda0",
"geometry":{
"type":"Point",
"coordinates":[
-106.170841666667,
47.3858805555556
]
}
},
{
"type":"Feature",
"properties":{
"parameter_name":"Gage height",
"statistic_id":null,
"begin":"1972-09-14T06:00:00",
"computation_period_identifier":"Water Year",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft",
"parameter_code":"00065",
"last_modified":"2019-06-20T01:55:20.010637",
"end":"1985-11-19T06:00:00",
"computation_identifier":"Max At Event Time",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-05570350",
"web_description":null
},
"id":"00055464292d473ba105749bbc0990f0",
"geometry":{
"type":"Point",
"coordinates":[
-90.0534507480865,
40.4975394281952
]
}
}
],
"numberReturned":10,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=html"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?offset=10"
},
{
"type":"application/json",
"title":"Time series metadata",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata"
}
],
"timeStamp":"2025-05-12T14:00:41.725698Z"
}
This query returns any observation that comes from one of our specified monitoring locations or matches one of our requested parameter codes, which is a much broader query than the "and" version. Make sure you're using the appropriate combination operator for the query you're trying to make!
"not"
Last but not least, we can additionally use the "not" operator to query for results which do not satisfy a condition. For instance, if we want to filter to only observations which do have a qualifier -- that is, whose qualifier field is not null -- we can pass a query using "isNull" as an argument to the "not" operator:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "not",
"args": [
{
"op": "isNull",
"args": [
{ "property": "qualifier" }
]
}
]
}'
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"statistic_id":"00001",
"time_series_id":"f4b3af29c5e14c2087871953760117fe",
"monitoring_location_id":"USGS-422308088195601",
"value":"11.1",
"approval_status":"Provisional",
"last_modified":"2025-04-04T05:11:11.384949+00:00",
"parameter_code":"00010",
"time":"2023-06-17",
"unit_of_measure":"degC",
"qualifier":[
"DISCONTINUED"
]
},
"id":"0000013b-e926-4bc1-ba44-75bcfa62e386",
"geometry":{
"type":"Point",
"coordinates":[
-88.33225,
42.3854722222222
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"3011904f520d47099a2a2db45e2b0b51",
"monitoring_location_id":"USGS-01468500",
"value":"92.8",
"approval_status":"Approved",
"last_modified":"2025-03-25T13:05:08.767057+00:00",
"parameter_code":"00060",
"time":"2025-01-10",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"00000208-3d6c-4b13-b57a-f11e3f52c4f9",
"geometry":{
"type":"Point",
"coordinates":[
-76.1246622490483,
40.6292577351575
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":null,
"time_series_id":"819f7fbf279249bf99603e6017e2f488",
"monitoring_location_id":"USGS-07240500",
"value":"7650",
"approval_status":"Approved",
"last_modified":"2025-03-11T16:17:37.593743+00:00",
"parameter_code":"00054",
"time":"2011-05-05",
"unit_of_measure":"Acre-ft",
"qualifier":[
"ESTIMATED"
]
},
"id":"000004c5-cbdf-4761-a1cd-c5188b6da5db",
"geometry":{
"type":"Point",
"coordinates":[
-97.6664309085446,
35.4864459751822
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"bb00a97f245d4125b43c86263bc1820c",
"monitoring_location_id":"USGS-09419745",
"value":"0.01",
"approval_status":"Approved",
"last_modified":"2025-03-11T10:05:45.062322+00:00",
"parameter_code":"00060",
"time":"2015-10-01",
"unit_of_measure":"ft^3/s",
"qualifier":[
"LESSTHAN"
]
},
"id":"00000581-11a1-4b63-bc99-45940a75b0d5",
"geometry":{
"type":"Point",
"coordinates":[
-114.968333333333,
36.085
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"cf590436d3e84b05b2719791d964959d",
"monitoring_location_id":"USGS-09405200",
"value":"0.73",
"approval_status":"Approved",
"last_modified":"2025-03-11T21:46:35.387275+00:00",
"parameter_code":"00060",
"time":"1990-11-07",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"00000671-1c9c-477b-9015-4e93c596f026",
"geometry":{
"type":"Point",
"coordinates":[
-112.88438762506,
37.5216447846746
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"c6e21c277c1e4b90989ba4323ceae991",
"monitoring_location_id":"USGS-03141870",
"value":"42.4",
"approval_status":"Approved",
"last_modified":"2025-02-19T01:07:38.035730+00:00",
"parameter_code":"00060",
"time":"2021-02-21",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"000009f8-1697-448c-91ce-6a4a1b58965f",
"geometry":{
"type":"Point",
"coordinates":[
-81.4956758475849,
39.9900717884196
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"85aa31c9b42a4e99be94b4fcda40df25",
"monitoring_location_id":"USGS-06635000",
"value":"36.0",
"approval_status":"Approved",
"last_modified":"2025-03-03T19:03:22.311772+00:00",
"parameter_code":"00060",
"time":"2009-12-04",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"00000b52-2caa-4414-b68c-06bac316a829",
"geometry":{
"type":"Point",
"coordinates":[
-106.513138135649,
42.0096681738866
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00001",
"time_series_id":"5912e5d5cccf457a94783cbbfef12fd8",
"monitoring_location_id":"USGS-04213152",
"value":"26.5",
"approval_status":"Approved",
"last_modified":"2025-03-31T04:54:24.145486+00:00",
"parameter_code":"00010",
"time":"2015-07-21",
"unit_of_measure":"degC",
"qualifier":[
"SEASONAL"
]
},
"id":"00000c2c-4dc1-41f7-9d00-3e3024178acd",
"geometry":{
"type":"Point",
"coordinates":[
-80.23472222222222,
42.073888888888895
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"6db42dc413174e5e938a9a2f10cccb5d",
"monitoring_location_id":"USGS-08397620",
"value":"0.00",
"approval_status":"Approved",
"last_modified":"2025-05-09T12:59:13.284179+00:00",
"parameter_code":"00060",
"time":"2004-05-16",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"00000d6a-12a9-4c28-9b73-9c755f8f20cb",
"geometry":{
"type":"Point",
"coordinates":[
-105.069422222222,
32.8367722222222
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"time_series_id":"50ef1a02acbd4287adab9f276a35e10b",
"monitoring_location_id":"USGS-03348000",
"value":"177",
"approval_status":"Approved",
"last_modified":"2025-03-11T03:40:10.806616+00:00",
"parameter_code":"00060",
"time":"2021-02-04",
"unit_of_measure":"ft^3/s",
"qualifier":[
"ESTIMATED"
]
},
"id":"00000d87-0d33-48c0-9ef2-58c57f889653",
"geometry":{
"type":"Point",
"coordinates":[
-85.6713888888889,
40.10527777777778
]
}
}
],
"numberReturned":10,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?offset=10"
},
{
"type":"application/json",
"title":"Daily values",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
}
],
"timeStamp":"2025-05-09T19:45:16.591526Z"
}
Combine URL parameters with CQL queries
You can combine CQL queries with normal URL parameters, as well. This means that you can use the normal limit argument, for instance, to control how many results you get per page on your CQL queries:
curl -X POST \
'https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?limit=1' \
--header 'Content-Type: application/query-cql-json' \
--data-raw '{
"op": "in",
"args": [
{ "property": "parameter_code" },
[ "00060", "00065" ]
]
}'
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"parameter_name":"Discharge",
"statistic_id":"00011",
"begin":"2006-05-18T06:00:00",
"computation_period_identifier":"Points",
"thresholds":[],
"primary":"Primary",
"unit_of_measure":"ft^3/s",
"parameter_code":"00060",
"last_modified":"2025-05-12T10:09:28.794889",
"end":"2025-05-12T10:00:00",
"computation_identifier":"Instantaneous",
"sublocation_identifier":"",
"monitoring_location_id":"USGS-10172640",
"web_description":null
},
"id":"00009b3da7e44a96a283bc413ff2de48",
"geometry":{
"type":"Point",
"coordinates":[
-112.13859444444445,
40.780852777777774
]
}
}
],
"numberReturned":1,
"links":[
{
"type":"application/geo+json",
"rel":"self",
"title":"This document as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=json&limit=1"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=jsonld&limit=1"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?f=html&limit=1"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata/items?offset=1&limit=1"
},
{
"type":"application/json",
"title":"Time series metadata",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/time-series-metadata"
}
],
"timeStamp":"2025-05-12T19:53:22.685354Z"
}
Similarly, you can then use the next links returned by the server to find your next page of results. This combination will also let you provide API keys through the URL while making CQL-based queries.