# Complex Water Data Queries with CQL2 Canonical URL: https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/ > Use CQL2 POST requests to query the USGS water data APIs for multiple sites, parameter codes, or value ranges at once. # Making CQL queries While you can make most common API queries [using query arguments in your URL](/docs/ogcapi/), 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](/docs/ogcapi/efficiency), the Water Data API platform also supports making more complex queries using [the Common Query Language standard](https://www.ogc.org/standards/cql2/). 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](https://curl.se/), 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: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections//items' \ --header 'Content-Type: application/query-cql-json' \ --data-raw '{ "op": "", "args": [ "" ] }' ``` You provide the [link to the items page](/docs/ogcapi/#items-pages) 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](/docs/ogcapi/efficiency/), one per monitoring location or parameter code, you could also use the "in" operator to query for multiple values at a time: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?limit=1' \ --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. For this example, we added `?limit=1` to the end, so we only get one result back: ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "id": "00009b3da7e44a96a283bc413ff2de48", "unit_of_measure": "ft^3/s", "parameter_name": "Discharge", "parameter_code": "00060", "statistic_id": "00011", "last_modified": "2026-09-30T08:09:46.663252", "begin": "2006-05-18T12:00:00+00:00", "end": "2026-09-30T14:00:00+00:00", "computation_period_identifier": "Points", "computation_identifier": "Instantaneous", "thresholds": [], "sublocation_identifier": null, "primary": "Primary", "monitoring_location_id": "USGS-10172640", "web_description": null, "parameter_description": "Discharge, cubic feet per second", "parent_time_series_id": "769d7201a8044b4ab5218bac4cd282e8", "data_gap_interval": "PT1H12M", "statistics_begin": null }, "id": "00009b3da7e44a96a283bc413ff2de48", "geometry": { "type": "Point", "coordinates": [ -112.13859444444445, 40.780852777777774 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?cursor=MDAwMDliM2RhN2U0NGE5NmEyODNiYzQxM2ZmMmRlNDg&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/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/v1/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/v1/collections/time-series-metadata/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?f=csv&limit=1" }, { "type": "application/json", "title": "Time series metadata", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata" } ], "timeStamp": "2026-09-30T15:29:47.457310Z" } ``` There are plenty of other operators available, including various [spatial functions](https://docs.ogc.org/is/21-065r2/21-065r2.html#spatial-functions) and [temporal functions](https://docs.ogc.org/is/21-065r2/21-065r2.html#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: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?limit=1' \ --header 'Content-Type: application/query-cql-json' \ --data-raw '{ "op": "between", "args": [ { "property": "statistic_id" }, [ "00001", "00003" ] ] }' ``` ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "id": "000068b2a47b45708c656bcff5264f54", "unit_of_measure": "degC", "parameter_name": "Temperature, water", "parameter_code": "00010", "statistic_id": "00002", "last_modified": "2017-05-07T20:53:29.551297", "begin": "1983-11-03T05:00:00+00:00", "end": "1985-04-16T05:00:00+00:00", "computation_period_identifier": "Daily", "computation_identifier": "Min", "thresholds": [], "sublocation_identifier": null, "primary": "Primary", "monitoring_location_id": "USGS-01379790", "web_description": null, "parameter_description": "Temperature, water, degrees Celsius", "parent_time_series_id": null, "data_gap_interval": null, "statistics_begin": null }, "id": "000068b2a47b45708c656bcff5264f54", "geometry": { "type": "Point", "coordinates": [ -74.5836111111111, 40.9177777777778 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?cursor=MDAwMDY4YjJhNDdiNDU3MDhjNjU2YmNmZjUyNjRmNTQ&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/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/v1/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/v1/collections/time-series-metadata/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?f=csv&limit=1" }, { "type": "application/json", "title": "Time series metadata", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata" } ], "timeStamp": "2026-10-01T14:22:47.875821Z" } ``` ## 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: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?limit=1' \ --header 'Content-Type: application/query-cql-json' \ --data-raw '{ "op": "isNull", "args": [ { "property": "qualifier" } ] }' ``` ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "time_series_id": "a8eaa547d91f44cd963a14b560ae80c3", "monitoring_location_id": "USGS-401642106051601", "parameter_code": "00045", "statistic_id": "00006", "time": "2022-09-13", "value": "0.00", "unit_of_measure": "in", "approval_status": "Approved", "qualifier": null, "last_modified": "2026-01-15T00:10:39.578597+00:00" }, "id": "00000008-ed00-43a9-9b23-375d44fe725b", "geometry": { "type": "Point", "coordinates": [ -106.08789444444444, 40.27823055555555 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?cursor=MDAwMDAwMDgtZWQwMC00M2E5LTliMjMtMzc1ZDQ0ZmU3MjVi&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/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/v1/collections/daily/items?f=jsonld&limit=1" }, { "type": "text/html", "rel": "alternate", "title": "This document as HTML", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?f=csv&limit=1" }, { "type": "application/json", "title": "Daily values", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily" } ], "timeStamp": "2026-10-01T14:23:41.038843Z" } ``` # 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: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?limit=1' \ --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: ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "id": "0001c934c87544838a53cb012fb8f1c6", "unit_of_measure": "ft^3/s", "parameter_name": "Discharge", "parameter_code": "00060", "statistic_id": null, "last_modified": "2019-06-20T11:04:48.243216", "begin": "1954-05-13T05:00:00+00:00", "end": "1982-12-27T06:00:00+00:00", "computation_period_identifier": "Water Year", "computation_identifier": "Max At Event Time", "thresholds": [], "sublocation_identifier": null, "primary": "Primary", "monitoring_location_id": "USGS-07367300", "web_description": null, "parameter_description": "Discharge, cubic feet per second", "parent_time_series_id": null, "data_gap_interval": null, "statistics_begin": null }, "id": "0001c934c87544838a53cb012fb8f1c6", "geometry": { "type": "Point", "coordinates": [ -92.2612495161081, 32.4932017390148 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?cursor=MDAwMWM5MzRjODc1NDQ4MzhhNTNjYjAxMmZiOGYxYzY&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/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/v1/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/v1/collections/time-series-metadata/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?f=csv&limit=1" }, { "type": "application/json", "title": "Time series metadata", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata" } ], "timeStamp": "2026-10-01T14:24:28.593725Z" } ``` ## "or" We could alternatively use the "or" operator to select observations which satisfy either requirement: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?limit=1' \ --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" ] ] } ] }' ``` ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "id": "00009b3da7e44a96a283bc413ff2de48", "unit_of_measure": "ft^3/s", "parameter_name": "Discharge", "parameter_code": "00060", "statistic_id": "00011", "last_modified": "2026-10-01T08:09:58.686940", "begin": "2006-05-18T12:00:00+00:00", "end": "2026-10-01T14:00:00+00:00", "computation_period_identifier": "Points", "computation_identifier": "Instantaneous", "thresholds": [], "sublocation_identifier": null, "primary": "Primary", "monitoring_location_id": "USGS-10172640", "web_description": null, "parameter_description": "Discharge, cubic feet per second", "parent_time_series_id": "769d7201a8044b4ab5218bac4cd282e8", "data_gap_interval": "PT1H12M", "statistics_begin": null }, "id": "00009b3da7e44a96a283bc413ff2de48", "geometry": { "type": "Point", "coordinates": [ -112.13859444444445, 40.780852777777774 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?cursor=MDAwMDliM2RhN2U0NGE5NmEyODNiYzQxM2ZmMmRlNDg&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/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/v1/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/v1/collections/time-series-metadata/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?f=csv&limit=1" }, { "type": "application/json", "title": "Time series metadata", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata" } ], "timeStamp": "2026-10-01T14:25:46.950384Z" } ``` 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: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?limit=1' \ --header 'Content-Type: application/query-cql-json' \ --data-raw '{ "op": "not", "args": [ { "op": "isNull", "args": [ { "property": "qualifier" } ] } ] }' ``` ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "time_series_id": "3011904f520d47099a2a2db45e2b0b51", "monitoring_location_id": "USGS-01468500", "parameter_code": "00060", "statistic_id": "00003", "time": "2025-01-10", "value": "92.8", "unit_of_measure": "ft^3/s", "approval_status": "Approved", "qualifier": [ "ESTIMATED" ], "last_modified": "2025-03-25T13:05:08.767057+00:00" }, "id": "00000208-3d6c-4b13-b57a-f11e3f52c4f9", "geometry": { "type": "Point", "coordinates": [ -76.1246622490483, 40.6292577351575 ] } } ], "numberReturned": 1, "links": [ { "rel": "next", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?cursor=MDAwMDAyMDgtM2Q2Yy00YjEzLWI1N2EtZjExZTNmNTJjNGY5&limit=1", "type": "application/geo+json", "title": "Items (next)" }, { "type": "application/geo+json", "rel": "self", "title": "This document as GeoJSON", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/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/v1/collections/daily/items?f=jsonld&limit=1" }, { "type": "text/html", "rel": "alternate", "title": "This document as HTML", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?f=html&limit=1" }, { "type": "text/csv; charset=utf-8", "rel": "alternate", "title": "This document as CSV", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/items?f=csv&limit=1" }, { "type": "application/json", "title": "Daily values", "rel": "collection", "href": "https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily" } ], "timeStamp": "2026-10-01T14:26:22.074852Z" } ``` # Combine URL parameters with CQL queries You can combine CQL queries with normal URL parameters, as well. This is how we've used the normal `limit` argument, for instance, to control how many results we get per page on your CQL queries: ```bash curl -X POST \ 'https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata/items?limit=1' \ --header 'Content-Type: application/query-cql-json' \ --data-raw '{ "op": "in", "args": [ { "property": "parameter_code" }, [ "00060", "00065" ] ] }' ``` ```json { "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/v1/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/v1/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/v1/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/v1/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/v1/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.