Skip to content

Querying GeoConnex

GeoConnex queries the reference features at reference.geoconnex.us. It takes no key and never receives USGS_API_KEY. This notebook lists the 22 two-digit hydrologic regions of hu02 without their geometry, streams them a few at a time, and maps the 18 regions of the contiguous United States with a CQL2 filter. to_arrow() turns each result into a table for polars or geopandas, which needs the arrow extra.

from water_ogcapi import GeoConnex

gc = GeoConnex()

A service keeps its HTTP connections open until it is closed. In a script, use it in a with block, with GeoConnex() as gc:, which closes it on exit. A notebook keeps one service across cells, so it calls gc.close() explicitly in its last cell.

List the regions

Geometry is most of a response. skipGeometry asks the server to leave it out, and keep_pages=True keeps each page's bytes in Page.content, so the notebook can report their size. to_arrow() on features without geometry returns a table of the properties and the feature id, which polars reads.

regions = gc.collect("hu02", params={"skipGeometry": "true"}, keep_pages=True)
print(len(regions.geojson["features"]), "regions in", regions.pagination.page_count, "page(s)")
print(regions.pagination.completeness, regions.pagination.checks)
print(sum(len(page.content or b"") for page in regions.pages) / 1e3, "kB")
22 regions in 1 page(s)
complete ('end_of_links', 'count', 'unique_ids')
13.623 kB
import polars as pl

pl.Config.set_tbl_rows(22)
pl.DataFrame(regions.to_arrow()).select("id", "name", "gnis_id").sort("id")
shape: (22, 3)
idnamegnis_id
strstri64
"01""New England Region"2730131
"02""Mid Atlantic Region"2730132
"03""South Atlantic-Gulf Region"2730133
"04""Great Lakes Region"2730134
"05""Ohio Region"2730135
"06""Tennessee Region"2730136
"07""Upper Mississippi Region"2730137
"08""Lower Mississippi Region"2730138
"09""Souris-Red-Rainy Region"2730139
"10""Missouri Region"2730141
"11""Arkansas-White-Red Region"2730142
"12""Texas-Gulf Region"2730143
"13""Rio Grande Region"2730144
"14""Upper Colorado Region"2730145
"15""Lower Colorado Region"2730146
"16""Great Basin Region"2730147
"17""Pacific Northwest Region"2730148
"18""California Region"2730149
"19""Alaska Region"2730150
"20""Hawaii Region"2730151
"21""Caribbean Region"2730152
"22""South Pacific Region"2741385

Stream pages

iter_pages() yields one Page per response and follows each page's next link. A limit of 10 splits the 22 regions into three pages. GeoConnex reports numberMatched on every page.

for page in gc.iter_pages("hu02", params={"skipGeometry": "true", "limit": "10"}):
    print(page.status, page.feature_count, page.number_matched)
200 10 22


200 10 22


200 2 22

Filter with CQL2

queryables() lists the properties of a collection that a filter can name:

print(", ".join(gc.queryables("hu02").properties or {}))
geometry, fid, uri, name, gnis_url, gnis_id, huc2, loaddate

huc2 is a string, so a CQL2-Text filter of huc2 <= '18' keeps the 18 regions of the contiguous United States and leaves out Alaska, Hawaii, the Caribbean, and the South Pacific, which sit far from the rest. With geometry, the response is much larger than the list above.

conus = gc.collect("hu02", filter="huc2 <= '18'", keep_pages=True)
print(len(conus.geojson["features"]), "regions,", end=" ")
print(round(sum(len(page.content or b"") for page in conus.pages) / 1e6), "MB")
print(conus.pagination.completeness, conus.pagination.checks)
print(conus.crs.effective, conus.crs.source)
18 regions, 23 MB
complete ('end_of_links', 'count', 'unique_ids')
http://www.opengis.net/def/crs/OGC/1.3/CRS84 content_crs

Map the regions

to_arrow() returns a pyarrow Table whose geometry column carries the CRS, so geopandas reads it as a GeoDataFrame with that CRS. EPSG:5070 is an equal-area projection of the contiguous United States, so the polygon areas it gives are true areas.

import geopandas as gpd
import matplotlib.patheffects as pe
import matplotlib.pyplot as plt

frame = gpd.GeoDataFrame.from_arrow(conus.to_arrow()).to_crs(5070)
frame["area"] = frame.area / 1e9  # thousand km²
ax = frame.plot(
    column="area",
    cmap="Blues",
    edgecolor="white",
    linewidth=0.8,
    figsize=(7, 4.6),
    legend=True,
    legend_kwds={"label": "Area (thousand km²)", "shrink": 0.6},
)
for point, code in zip(frame.representative_point(), frame["huc2"], strict=True):
    ax.annotate(
        code,
        (point.x, point.y),
        ha="center",
        va="center",
        fontsize=8,
        path_effects=[pe.withStroke(linewidth=2, foreground="white")],
    )
ax.set(title="Hydrologic regions of the contiguous United States")
ax.set_axis_off()
plt.tight_layout()

png

gc.close()