Getting started with USGS Water Data OGC APIs
These endpoints provide access to USGS water data using the OGC API family of standards. These APIs will provide access to a wide array of USGS water data, including continuous sensor measurements, daily values, and metadata about individual time series and monitoring locations. These endpoints all use a common set of standards for API behavior and returning data in standardized formats, making it easy to access USGS data from R and from Python, or directly from your GIS application.
This page outlines the structure of these APIs, gives some advice on making efficient queries, and provides information about using API keys with these services to access higher rate limits. For at-a-glance reference information, including a list of available endpoints and the parameters they accept, check out the SwaggerUI documentation for these services.
Querying the APIs
If you query the top-level URL for these APIs, you'll get a response object containing a number of links to the resources the application provides:
https://api.waterdata.usgs.gov/ogcapi/v0/
{
"links":[
{
"rel":"about",
"type":"text/html",
"title":"USGS Water Data OGC APIs",
"href":"https://api.waterdata.usgs.gov"
},
{
"rel":"self",
"type":"application/json",
"title":"This document as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=json"
},
{
"rel":"alternate",
"type":"application/ld+json",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=jsonld"
},
{
"rel":"alternate",
"type":"text/html",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=html",
"hreflang":"en-US"
},
{
"rel":"service-desc",
"type":"application/vnd.oai.openapi+json;version=3.0",
"title":"The OpenAPI definition as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/openapi"
},
{
"rel":"service-doc",
"type":"text/html",
"title":"The OpenAPI definition as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/openapi?f=html",
"hreflang":"en-US"
},
{
"rel":"conformance",
"type":"application/json",
"title":"Conformance",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/conformance"
},
{
"rel":"data",
"type":"application/json",
"title":"Collections",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections"
},
{
"rel":"http://www.opengis.net/def/rel/ogc/1.0/processes",
"type":"application/json",
"title":"Processes",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/processes"
},
{
"rel":"http://www.opengis.net/def/rel/ogc/1.0/job-list",
"type":"application/json",
"title":"Jobs",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/jobs"
},
{
"rel":"http://www.opengis.net/def/rel/ogc/1.0/tiling-schemes",
"type":"application/json",
"title":"The list of supported tiling schemes as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/TileMatrixSets?f=json"
},
{
"rel":"http://www.opengis.net/def/rel/ogc/1.0/tiling-schemes",
"type":"text/html",
"title":"The list of supported tiling schemes as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/TileMatrixSets?f=html"
}
],
"title":"USGS Water Data OGC APIs",
"description":"These APIs provide OGC-compliant interfaces to USGS water data, letting you download continuous sensor measurements, discrete field measurements, metadata about monitoring locations, and more. These APIs are currently in an alpha status, and should not be relied upon for production workloads.\n"
}
Note that these APIs default to returning HTML if you visit them in a browser, meaning that visiting that same URL will return a fully rendered homepage. This lets you view the same information as included in the JSON response in a more human-friendly format. If you'd rather view JSON in your browser, add &f=json to the end of your query to request the JSON format.
Collections pages
The most important of all the links returned is the collections endpoint. This page lists all the individual data types you can download from these APIs, with links to more information about each data set.
https://api.waterdata.usgs.gov/ogcapi/v0/collections
{
"collections":[
{
"id":"daily",
"title":"Daily values",
"description":"Daily data provide one data value to represent water conditions for the day. Throughout much of the history of the USGS, the primary water data available was daily data collected manually at the monitoring location once each day. With improved availability of computer storage and automated transmission of data, the daily data published today are generally a statistical summary or metric of the continuous data collected each day, such as the daily mean, minimum, or maximum value. Daily data are automatically calculated from the continuous data of the same parameter code and are described by parameter code and a statistic code. These data have also been referred to as \u201cdaily values\u201d or \u201cDV\u201d.\n",
"keywords":[
"automated",
"daily",
"statistics",
"current",
"single location"
],
"links":[
{
"type":"application/json",
"rel":"root",
"title":"The landing page of this server as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=json"
},
{
"type":"text/html",
"rel":"root",
"title":"The landing page of this server as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=html"
},
{
"type":"application/json",
"rel":"self",
"title":"This document as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=json"
},
{
"type":"application/ld+json",
"rel":"alternate",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=html"
},
{
"type":"application/json",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/schema",
"title":"Schema of collection in JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/schema?f=json"
},
{
"type":"text/html",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/schema",
"title":"Schema of collection in HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/schema?f=html"
},
{
"type":"application/schema+json",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/queryables",
"title":"Queryables for this collection as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/queryables?f=json"
},
{
"type":"text/html",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/queryables",
"title":"Queryables for this collection as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/queryables?f=html"
},
{
"type":"application/geo+json",
"rel":"items",
"title":"Items as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json"
},
{
"type":"application/ld+json",
"rel":"items",
"title":"Items as RDF (GeoJSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=jsonld"
},
{
"type":"text/html",
"rel":"items",
"title":"Items as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html"
}
],
"extent":{
"spatial":{
"bbox":[
[
-180,
-90,
180,
90
]
],
"crs":"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"itemType":"feature",
"crs":[
"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
],
"storageCRS":"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
],
"links":[
{
"type":"application/json",
"rel":"self",
"title":"This document as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections?f=json"
},
{
"type":"application/ld+json",
"rel":"alternate",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections?f=html"
}
]
}
Just like the homepage, you can also which you can also view this collections page in your browser.
The pages for each individual collection can be found at https://api.waterdata.usgs.gov/ogcapi/v0/collections/{collectionId}, replacing {collectionId} with the id values from the JSON response above. Querying this endpoint returns the same information as in the collections endpoint above:
https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily
{
"id":"daily",
"title":"Daily values",
"description":"Daily data provide one data value to represent water conditions for the day. Throughout much of the history of the USGS, the primary water data available was daily data collected manually at the monitoring location once each day. With improved availability of computer storage and automated transmission of data, the daily data published today are generally a statistical summary or metric of the continuous data collected each day, such as the daily mean, minimum, or maximum value. Daily data are automatically calculated from the continuous data of the same parameter code and are described by parameter code and a statistic code. These data have also been referred to as \u201cdaily values\u201d or \u201cDV\u201d.\n",
"keywords":[
"automated",
"daily",
"statistics",
"current",
"single location"
],
"links":[
{
"type":"application/json",
"rel":"root",
"title":"The landing page of this server as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=json"
},
{
"type":"text/html",
"rel":"root",
"title":"The landing page of this server as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0?f=html"
},
{
"type":"application/json",
"rel":"self",
"title":"This document as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=json"
},
{
"type":"application/ld+json",
"rel":"alternate",
"title":"This document as RDF (JSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=jsonld"
},
{
"type":"text/html",
"rel":"alternate",
"title":"This document as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily?f=html"
},
{
"type":"application/json",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/schema",
"title":"Schema of collection in JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/schema?f=json"
},
{
"type":"text/html",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/schema",
"title":"Schema of collection in HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/schema?f=html"
},
{
"type":"application/schema+json",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/queryables",
"title":"Queryables for this collection as JSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/queryables?f=json"
},
{
"type":"text/html",
"rel":"http://www.opengis.net/def/rel/ogc/1.0/queryables",
"title":"Queryables for this collection as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/queryables?f=html"
},
{
"type":"application/geo+json",
"rel":"items",
"title":"Items as GeoJSON",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json"
},
{
"type":"application/ld+json",
"rel":"items",
"title":"Items as RDF (GeoJSON-LD)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=jsonld"
},
{
"type":"text/html",
"rel":"items",
"title":"Items as HTML",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html"
}
],
"extent":{
"spatial":{
"bbox":[
[
-180,
-90,
180,
90
]
],
"crs":"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"itemType":"feature",
"crs":[
"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
],
"storageCRS":"http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
Items pages
Querying the items link will return the actual observations contained in a collection. For the sake of demonstration, we're going to add two query parameters to our query on this endpoint:
- We'll set
limit=2to only return two observations. - We'll set
api_key=DEMO_KEYto provide an example API key for this documentation. You should replace this with your own API key when making your own requests.
You can see that we added these parameters to the end of our URL after a ?, and separated our parameters using &:
https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?limit=2&api_key=DEMO_KEY
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"statistic_id":"00002",
"timeseries_id":"41e5c231aef84cdaa41916d362f31720",
"monitoring_location_id":"USGS-01376520",
"value":"21700",
"approvals_status":[
"Approved"
],
"last_modified":"2025-01-16T16:53:05.194512+00:00",
"parameter_code":"00095",
"time":"2023-09-25",
"unit_of_measure":"uS/cm",
"qualifier":null
},
"id":"00003678-a0da-4b28-a3a4-1b6b0dee7f4a",
"geometry":{
"type":"Point",
"coordinates":[
-74.0156111111111,
40.7215277777778
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"timeseries_id":"83b2af1b29ae48e49bd660e82fcb32b2",
"monitoring_location_id":"USGS-444302070252401",
"value":"17.47",
"approvals_status":[
"Approved"
],
"last_modified":"2025-01-15T23:29:08.662341+00:00",
"parameter_code":"72019",
"time":"2024-03-13",
"unit_of_measure":"ft",
"qualifier":null
},
"id":"0000cf15-5a66-4b6d-9cbb-b4c36b8a644b",
"geometry":{
"type":"Point",
"coordinates":[
-70.4228435127509,
44.7172813270818
]
}
}
],
"numberMatched":238474,
"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"
},
{
"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"
},
{
"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"
},
{
"type":"application/geo+json",
"rel":"next",
"title":"Items (next)",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?offset=2&limit=2"
},
{
"type":"application/json",
"title":"Daily values",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
}
],
"timeStamp":"2025-01-27T15:42:52.029885Z"
}
The returned response is a GeoJSON object. Each individual observation is returned as a "feature", nested inside the "features" key. The "properties" key of each feature contains all the data and metadata associated with an observation, while the "geometry" key contains spatial information about the observation.
At the end of the response are a number of links. The most important of these is the "next" link, which has a "rel" attribute of "next". If your query produces too many matching results, these APIs will automatically break them into a number of pages that you'll need to request and download separately. This "next" link will always point to the location of the next page of results. You'll know that you've downloaded all the results for your query when your response doesn't have a "next" link or returns 0 features.
We can add additional parameters to tailor our query further. For instance, we can use the datetime parameter to only return observations that were collected during a certain time window. This argument can be used a few different ways:
- Passing a single date or datetime, for instance
datetime=2024-12-01T00:00Z, will only return observations which were collected at precisely that date or time. - You can pass an interval of two datetimes by separating the timestamps with a
/. For instance,datetime=2024-12-01/2024-12-31will return all observations that were collected between January 1 and January 31 2024. These timestamps and intervals are defined in RFC3339. - You can also leave one of these timestamps "empty" to retrieve all data from before or after a date by replacing a timestamp with
... For instance,datetime=2024-12-01/..will return all observations collected after January 1 2024. - Finally, you can provide a duration to get all data collected within a certain interval from the current time. For instance,
datetime=P7Dwill return all data with a timestamp in the last seven days, whiledatetime=PT6Hwill return all data from the past six hours. These APIs will understand any ISO8601 duration object.
We can add this datetime parameter right at the end of our previous URL:
https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?limit=2&api_key=DEMO_KEY&datetime=2024-12-01/2024-12-31
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"statistic_id":"00001",
"timeseries_id":"d27aa93e0e8b475fbb09ebc32bd631c9",
"monitoring_location_id":"USGS-01359165",
"value":"1.3",
"approvals_status":[
"Working"
],
"last_modified":"2025-01-16T11:49:11.323551+00:00",
"parameter_code":"00010",
"time":"2024-12-19",
"unit_of_measure":"degC",
"qualifier":null
},
"id":"000a05b2-e699-4f5b-b2fa-ace54e923e43",
"geometry":{
"type":"Point",
"coordinates":[
-73.7589166666667,
42.6195277777778
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00001",
"timeseries_id":"555ded622dc04dfe84f1a3daf3a994b6",
"monitoring_location_id":"USGS-03197950",
"value":"38.60",
"approvals_status":[
"Working"
],
"last_modified":"2025-01-16T17:07:12.002939+00:00",
"parameter_code":"32295",
"time":"2024-12-15",
"unit_of_measure":"QSE",
"qualifier":null
},
"id":"0016ace6-9acd-4e55-ac07-6388a1fe7bf3",
"geometry":{
"type":"Point",
"coordinates":[
-81.6270679796084,
38.3581527283073
]
}
}
],
"numberMatched":6096,
"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"
},
{
"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"
},
{
"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"
},
{
"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"
},
{
"type":"application/json",
"title":"Daily values",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
}
],
"timeStamp":"2025-01-27T17:18:34.234818Z"
}
You can also query these APIs using any properties included in the response object. For instance, the daily endpoint includes both parameter_code and statistic_id as metadata attached to each observation. If we only wanted the mean (statistic_id of 00003) daily value for stream discharge (parameter_code of 00065), we could add both of those as parameters to our URL:
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¶meter_code=00065
{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"timeseries_id":"17d91ed719544fa38c8c6a1949a690b3",
"monitoring_location_id":"USGS-05060000",
"value":"8.07",
"approvals_status":[
"Working"
],
"last_modified":"2024-12-05T06:58:52.681608+00:00",
"parameter_code":"00065",
"time":"2024-12-03",
"unit_of_measure":"ft",
"qualifier":[
"SEASONAL"
]
},
"id":"03cc27ba-b76e-4d50-9253-b584f8d9146e",
"geometry":{
"type":"Point",
"coordinates":[
-97.1064770662731,
46.8660826341224
]
}
},
{
"type":"Feature",
"properties":{
"statistic_id":"00003",
"timeseries_id":"00f2843003ed4b2aba79c811588c1663",
"monitoring_location_id":"USGS-07161450",
"value":"8.01",
"approvals_status":[
"Working"
],
"last_modified":"2024-12-05T02:20:39.407136+00:00",
"parameter_code":"00065",
"time":"2024-12-02",
"unit_of_measure":"ft",
"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¶meter_code=00065"
},
{
"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¶meter_code=00065"
},
{
"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¶meter_code=00065"
},
{
"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¶meter_code=00065"
},
{
"type":"application/json",
"title":"Daily values",
"rel":"collection",
"href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily"
}
],
"timeStamp":"2025-01-27T17:11:21.979108Z"
}