Custom Connector
USGS Water Data OGC Connector
US
The USGS Water Data OGC Connector integrates with the USGS Water Data OGC APIs, providing access to geospatial water data — continuous sensor measurements, daily data, field measurements, and metadata about monitoring locations, aquifers, and reference codes. Built on OGC API standards, it supports JSON, HTML, JSON-LD, and CSV responses for hydrologic analysis on GCP.
Overview
Integration Overview
This connector exposes OGC API - Features endpoints across ~25 collections. Beyond the API-level endpoints (landing page, collections, conformance, OpenAPI), each collection offers the same seven operations — describe collection, list features, get feature by ID, queryables, schema, and OPTIONS for both the items endpoint and a single item. The collections are documented as a group below.
- getLandingPage. Retrieve the API landing page — title, description, links, and conformance.
- getCollections. Retrieve the list of available collections.
- getConformance / getOpenapi. Retrieve the conformance declaration and the OpenAPI specification.
- describe<Collection>. Retrieve metadata for a collection (id, title, description, extent, links).
- get<Collection>Features. Retrieve features from a collection, with bbox, properties, sort, and pagination filters.
- get<Collection>Feature. Retrieve a single feature by ID.
- get<Collection>Queryables / Schema. Retrieve queryable properties and the schema for a collection.
- options<Collection>Features / Feature. Retrieve supported HTTP methods and parameters for the items endpoint or a single item.
Documentation
Detailed Integration Documentation
Landing Page
| Action | getLandingPage |
|---|---|
| Purpose | Retrieves the API landing page — the entry point with title, description, links to collections and conformance, and conformance declarations. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Optional: format (json, html, jsonld, csv; default json); lang (default en-US). |
| Output | Successful: JSON/HTML/JSON-LD/CSV with title, description, links (href, rel, type, title, hreflang), and conformsTo. Failure: 400 Invalid parameter value. |
| Workflow example | Execute getLandingPage with format=json, then extract links to navigate to collections. |
Collections & API Metadata
| Action | getCollections / getConformance / getOpenapi |
|---|---|
| Purpose | Retrieves the list of available collections (id, title, description, extent, itemType, links), the API conformance declaration, and the OpenAPI specification document. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Optional: format (json, html, jsonld, csv; default json); lang (default en-US). |
| Output | Successful: JSON/HTML/JSON-LD/CSV with a collections array (or conformance URIs, or the OpenAPI document) and links. Failure: 400 Invalid parameter value. |
| Workflow example | Execute getCollections with format=json to identify collections (e.g. monitoring-locations, parameter-codes) for further queries. |
Available Collections
| Reference collections | agency-codes, altitude-datums, aquifer-codes, aquifer-types, coordinate-accuracy-codes, coordinate-datum-codes, coordinate-method-codes, hydrologic-unit-codes, medium-codes, national-aquifer-codes, parameter-codes, reliability-codes, site-types, statistic-codes, topographic-codes, time-zone-codes. |
|---|---|
| Data collections | latest-continuous, daily, latest-daily, field-measurements, time-series-metadata, monitoring-locations. |
| Note | Each collection supports the same seven operations documented below (describe, features, feature, queryables, schema, and OPTIONS ×2). |
Describe Collection
| Action | describe<Collection>Collection (e.g. describeMonitoringLocationsCollection) |
|---|---|
| Purpose | Retrieves metadata for a collection — id, title, description, spatial/temporal extent, itemType, and links. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Required: resourceId (the collection identifier, e.g. monitoring-locations). Optional: format (json, html, jsonld, csv; default json); lang (default en-US). |
| Output | Successful: JSON/HTML/JSON-LD/CSV with id, title, description, extent, itemType, and links. Failure: 404 Resource not found. |
| Workflow example | Execute describeParameterCodesCollection with resourceId=parameter-codes to understand a collection before querying it. |
Get Features (list)
| Action | get<Collection>Features (e.g. getMonitoringLocationsFeatures) |
|---|---|
| Purpose | Retrieves features (items) from a collection, supporting filtering by bounding box and properties, sorting, and pagination. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Optional: format (json, html, jsonld, csv; default json); lang (default en-US). bbox (4 or 6 numbers); bbox-crs; crs; limit (default 10000, max 10000); properties (comma-separated); skipGeometry; sortby (e.g. +field); offset; collection-specific property filters (e.g. agency_name, aquifer_name); api_key. |
| Output | Successful: a FeatureCollection with type, timeStamp, numberMatched, numberReturned, a features array (id, geometry, properties, links), and links. Failure: 400 Invalid parameter value. |
| Workflow example | Execute getMonitoringLocationsFeatures with limit=100 and a bbox, then process the features for mapping or analysis. |
Get Feature (by ID)
| Action | get<Collection>Feature (e.g. getMonitoringLocationsFeature) |
|---|---|
| Purpose | Retrieves a single feature by ID from a collection — detailed information about one item. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Required: featureId (unique feature identifier). Optional: format (json, html, jsonld, csv; default json); lang (default en-US). crs; api_key. |
| Output | Successful: a Feature object with type, id, geometry, properties, and links. Failure: 404 Resource not found. |
| Workflow example | Execute getAgencyCodesFeature with featureId=USGS and format=json to display detailed information for that code. |
Queryables & Schema
| Action | get<Collection>Queryables / get<Collection>Schema |
|---|---|
| Purpose | Retrieves the queryable properties (with optional actual-domain or valid-domain profile) and the schema for a collection — for building dynamic queries and validating data. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | Optional: format (json, html, jsonld, csv; default json); lang (default en-US). properties (comma-separated); profile (actual-domain, valid-domain — queryables only); api_key. |
| Output | Successful: JSON/HTML/JSON-LD/CSV with a queryables array (queryable, type, description, title, language, type-ref). Failure: 404 Resource not found. |
| Workflow example | Execute getAgencyCodesQueryables with profile=actual-domain to determine which properties can be queried. |
OPTIONS (items & single item)
| Action | options<Collection>Features / options<Collection>Feature |
|---|---|
| Purpose | Retrieves supported HTTP methods and parameters for a collection’s items endpoint, or for a specific item by ID. |
| Configuration | Configure the base URL via CONNECTOR_ENV_USGSWATERDATAOGC_BASE_URL (e.g. https://api.waterdata.usgs.gov/ogcapi/v0), with an optional API key via CONNECTOR_ENV_USGSWATERDATAOGC_API_KEY. |
| Parameters | options…Feature required: featureId. Optional: api_key. |
| Output | Successful: an options response with supported methods and parameters. Failure: 500 Server error (items) or 404 Resource not found (single item). |
| Workflow example | Execute optionsMonitoringLocationsFeatures to determine supported operations before building requests. |
Example Workflow: Water Data Analysis
| Discover collections | Use getLandingPage and getCollections to identify collections (e.g. monitoring-locations, daily, parameter-codes). |
|---|---|
| Query features | Use get<Collection>Features (e.g. getDailyFeatures) with bbox, properties, and limit to fetch data. |
| Inspect a record | Use get<Collection>Feature with a featureId for a specific record, and getQueryables/getSchema to understand fields. |
| Integrate | Process the GeoJSON/CSV results in a GCP pipeline for environmental monitoring, research, or resource management. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.