Making efficient queries

Below are a few tips for getting data from the USGS Water Data APIs faster and with fewer repeated requests.

Limit the data you download

The slowest part of every API query is the time it takes to send data over the Internet from our servers to your computer. If you want your queries to run faster, the best thing you can do is to download less data.

One way to do this is to use the properties parameter to only download the data and metadata you're interested in. If provided, these APIs will only return the fields listed in properties with each request, which can significantly reduce the overall size of the response object.

For instance, if we're downloading the mean (statistic_id of 00003) daily value for stream discharge (parameter_code of 00065), we know that the statistic_id, parameter_code, and unit_of_measure fields in our response will always have the same values. As such, we can use the properties key to drop these fields from our download, shrinking the size of the response object and speeding our query up:

https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?limit=2&api_key=DEMO_KEY&datetime=2024-12-01/2024-12-31&statistic_id=00003&parameter_code=00065&properties=timeseries_id,monitoring_location_id,value,approvals_status,last_modified,time,qualifier

{
    "type":"FeatureCollection",
    "features":[
        {
            "type":"Feature",
            "properties":{
                "timeseries_id":"17d91ed719544fa38c8c6a1949a690b3",
                "monitoring_location_id":"USGS-05060000",
                "value":"8.07",
                "approvals_status":[
                    "Working"
                ],
                "last_modified":"2024-12-05T06:58:52.681608+00:00",
                "time":"2024-12-03",
                "qualifier":[
                    "SEASONAL"
                ]
            },
            "id":"03cc27ba-b76e-4d50-9253-b584f8d9146e",
            "geometry":{
                "type":"Point",
                "coordinates":[
                    -97.1064770662731,
                    46.8660826341224
                ]
            }
        },
        {
            "type":"Feature",
            "properties":{
                "timeseries_id":"00f2843003ed4b2aba79c811588c1663",
                "monitoring_location_id":"USGS-07161450",
                "value":"8.01",
                "approvals_status":[
                    "Working"
                ],
                "last_modified":"2024-12-05T02:20:39.407136+00:00",
                "time":"2024-12-02",
                "qualifier":null
            },
            "id":"0be65b91-47db-43e0-8b2e-bdff2b408a91",
            "geometry":{
                "type":"Point",
                "coordinates":[
                    -96.9122504261661,
                    35.9858926974527
                ]
            }
        }
    ],
    "numberMatched":62,
    "numberReturned":2,
    "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&limit=2&datetime=2024-12-01%2F2024-12-31&statistic_id=00003&parameter_code=00065&properties=timeseries_id,monitoring_location_id,value,approvals_status,last_modified,time,qualifier"
        },
        {
            "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&limit=2&datetime=2024-12-01%2F2024-12-31&statistic_id=00003&parameter_code=00065&properties=timeseries_id,monitoring_location_id,value,approvals_status,last_modified,time,qualifier"
        },
        {
            "type":"text/html",
            "rel":"alternate",
            "title":"This document as HTML",
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html&limit=2&datetime=2024-12-01%2F2024-12-31&statistic_id=00003&parameter_code=00065&properties=timeseries_id,monitoring_location_id,value,approvals_status,last_modified,time,qualifier"
        },
        {
            "type":"application/geo+json",
            "rel":"next",
            "title":"Items (next)",
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?offset=2&limit=2&datetime=2024-12-01%2F2024-12-31&statistic_id=00003&parameter_code=00065&properties=timeseries_id,monitoring_location_id,value,approvals_status,last_modified,time,qualifier"
        },
        {
            "type":"application/json",
            "title":"Daily values",
            "rel":"collection",
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
        }
    ],
    "timeStamp":"2025-01-27T19:11:48.738301Z"
}

Depending on our application we might go even further. For instance, if we're not planning on incorporating timeseries or site level metadata, we might drop the ID fields from our list of properties, or drop the last_modified column. Each of these changes will shrink our total download size and speed our queries up.

Other ways to reduce the amount of time you spend downloading data is to reduce the amount of duplicate or overlapping downloads your application generates. For instance, if you're interested in only the most recent data (or the most recent updates), consider using the datetime or last_modified fields to only retrieve the most recent records that match the rest of your parameters.

Make more, smaller queries

When you query these APIs, our server has to first go find all the records that match your query, and then split them up into pages to send back to your computer. This means that requests which match many records will take longer to execute -- and will be relatively slow to page through as the query gets re-run when generating each page.

As a result, you can speed up your download times by chopping your query into smaller pieces. For instance, if you're interested in a full year of data for a query, consider downloading each month separately instead. By limiting the total number of results which match your query, you can speed up how quickly the server builds each page of results it returns, which can potentially significantly speed up your download process.