The Service Records

Every request Tidemark sends to a public service is answered in that service's own shape, and the package reads each answer through a typed record, a Pydantic model that names the fields it expects and refuses a response that lacks one. A service that renames a field therefore stops a rebuild or a fetch with an error naming the field, rather than writing an empty column into a table the package keeps.

Inside the Station Catalog, The Gauge Series, and The Satellite Passes say what each service is for, and the table below names the records each one answers through, written from the declaration in tidemark.docs.holdings by mise run docs:render.

Service	Records	Documented At
The NERACOOS ERDDAP	ErddapCatalog, ErddapDataset, ErddapVariables	The ERDDAP documentation on its allDatasets table and its info responses
NOAA CO-OPS	CoopsRoster, CoopsEntry, CoopsStation, CoopsBenchmark, CoopsSensors, CoopsSensor, CoopsSheet, CoopsInventory, CoopsStretch	The CO-OPS Metadata API, the bench mark sheets CO-OPS publishes for each station, which CoopsSheet reads, and the CO-OPS web services listing the Water Level/Met Data Inventory the last two read
The USGS Water Data API	UsgsLocations, UsgsLocation, UsgsTimeSeries, UsgsPage	The USGS Water Data OGC API on its monitoring-locations, time-series-metadata, and continuous collections
PO.DAAC	Granule, OpendapPass	The CMR Search API on the UMM record NASA Earthdata's search returns for each granule, and the DAP4 specification on the metadata response PO.DAAC's OPeNDAP service answers for each pass
AVISO	AvisoPass	The THREDDS Client Catalog Primer on the urlPath of each dataset AVISO's THREDDS catalog lists, and the DUACS Level 3 handbook on the name each file takes (§3.3)

A record keeps only the fields the catalog or a fetch reads and ignores the rest of a response, so a service that adds a field changes nothing here. Where a service spells a field differently from the name the package gives it, the meaning says so, because that spelling is what a reader will find in the raw response.

The Records

mise run docs:render writes each section below from the record's own declaration, the sentence beneath a heading from the record's docstring and each row from a field's.

CoopsBenchmark

One bench mark the CO-OPS metadata API lists for a NOAA station.

Field	Holds	Meaning
designation	text	The name CO-OPS files the mark under, such as 841 3320 D
published	true or false	Whether the station's published bench mark sheet sets the mark out
pid	text or empty	The PID NGS files the mark under, which the listing spells idbPid and leaves empty where no NGS datasheet carries the mark
stamping	text or empty	The words stamped on the mark, such as K 22 1934

CoopsEntry

One station in the CO-OPS listing, which reports only the stations NOAA still operates.

Field	Holds	Meaning
identifier	text	The station id NOAA files this gauge under, which the listing spells id
state	text or empty	The two-letter state code the listing carries, which is absent where the listing files none

CoopsInventory

Every stretch of readings one NOAA station holds, as the CO-OPS Water Level/Met Data Inventory lists them, naming the first and the last reading of each unbroken stretch.

Field	Holds	Meaning
stretches	list of CoopsStretch	Every stretch the inventory lists, one for each parameter element

CoopsRoster

The CO-OPS listing of every water level station NOAA still operates.

Field	Holds	Meaning
stations	list of CoopsEntry	Every water level station the listing returned, with one entry for each

CoopsSensor

One sensor the CO-OPS sensor listing names for a station.

Field	Holds	Meaning
name	text	The sensor's descriptive name, such as Microwave WL or Wind
enabled	true or false	Whether CO-OPS lists the sensor as enabled, which the listing spells status and writes as 1 or 0

CoopsSensors

The sensors the CO-OPS metadata API lists for one station, which it answers as null at a station it lists none for.

Field	Holds	Meaning
sensors	list of CoopsSensor or empty	Every sensor the listing names, of any kind, enabled or not

CoopsSheet

The height of each bench mark of a NOAA station above the station's tidal datums, as the bench mark sheet CO-OPS publishes for the station sets them out, the sheet https://tidesandcurrents.noaa.gov/benchmarks.html shows, whose table the metadata API does not serve.

Field	Holds	Meaning
heights	map from text to map from text to number	The height in meters of each mark above each datum the sheet's table lists, keyed by the stamping or the designation the table names the mark by

CoopsStation

One NOAA station, read out of the stations list that wraps it and the bench marks, details, and datums blocks that expand folds into the same response.

Field	Holds	Meaning
latitude	number	Where the station sits in degrees north, which the response spells lat
longitude	number	Where the station sits in degrees east, which the response spells lng
accepted	date or empty	The date CO-OPS accepted the station's datum heights, which stays empty where the datums block names none
benchmarks	list of CoopsBenchmark	Every bench mark the metadata API lists for the station, read from the benchmarks list inside the response's benchmarks block
datums	map from text to number or empty	The height of every datum the station's datum table lists above the station datum, keyed by its name, such as MLLW or NAVD88, read from the datums list inside the response's datums block
epoch	text	The years the station's tidal datums average over, such as 1983-2001
identifier	text	The station id NOAA files this gauge under, read from the first entry of the response's stations list
name	text	The place the station sits, as NOAA names it
retired	date or empty	The date NOAA removed the station, which stays empty while it operates
units	text	The unit the datums block gives every height in, which the request sets to meters

CoopsStretch

One unbroken stretch of one kind of reading a NOAA station holds, as the CO-OPS data inventory lists it.

Field	Holds	Meaning
first	date and time	The instant of the stretch's first reading, to the minute in UTC
last	date and time	The instant of the stretch's last reading, to the minute in UTC
name	text	What the stretch holds, such as Verified 6-Minute Water Level

ErddapCatalog

Every dataset the NERACOOS ERDDAP publishes a water level for, read from allDatasets, the table the server keeps about its own holdings.

Field	Holds	Meaning
datasets	list of ErddapDataset	Every dataset the allDatasets table returned, with one entry for each

ErddapDataset

One tide dataset as the NERACOOS ERDDAP's allDatasets table describes it.

Field	Holds	Meaning
latitude	number	Where the gauge sits in degrees north, which the listing spells minLatitude
longitude	number	Where the gauge sits in degrees east, which the listing spells minLongitude
institution	text	The organization the server's listing names for the dataset, which the catalog records as the gauge's operator
title	text	The dataset's title, from which the record reads the gauge's place name and, together with the id, its state
identifier	text	The dataset id the server files this gauge under, which the listing spells datasetID

ErddapVariables

The variables and attributes one ERDDAP dataset publishes, read from the information table the server keeps for it.

Field	Holds	Meaning
columns	list of text	The column names of the information table, read from table.columnNames
rows	list of list of text	Every row of the information table, each a list of cells in the order columns gives

UsgsLocation

One USGS monitoring location, as a feature of the API's monitoring-locations collection describes it, whose altitude is the gage datum a USGS gauge's gage height is measured above.

Field	Holds	Meaning
latitude	number	Where the location sits in degrees north, the second coordinate of the feature's point
longitude	number	Where the location sits in degrees east, the first coordinate of the feature's point
accuracy	number or empty	How far the altitude may be off in feet, which the collection documents as half the contour interval for an altitude read off a map
altitude	number or empty	The altitude of the location in feet above vertical_datum, which is empty where USGS records none
identifier	text	The monitoring location id, the agency code and the site number joined by a hyphen, such as USGS-01049505
method	text or empty	How USGS set the altitude, such as Interpolated from Digital Elevation Model
site_type	text	The hydrologic setting the collection names for the location, such as Tidal stream or Estuary
vertical_datum	text or empty	The datum the altitude is referenced to, which the collection spells NAVD88 for NAVD 88

UsgsLocations

The USGS monitoring locations inside one box, as features of the API's monitoring-locations collection.

Field	Holds	Meaning
locations	list of UsgsLocation	Every location the box holds, which the collection lists as features

UsgsPage

One page of the gage heights the API's continuous collection answers a query with, beside the address of the next page, where the query holds more readings than one page carries.

Field	Holds	Meaning
following	text or empty	The address of the next page, which the page's links name under the relation next, and which is empty on the last page
readings	list of map from text to text or list of text or empty	The properties of every reading the page carries, one for each of the page's features

UsgsTimeSeries

The gage heights one USGS monitoring location records at its own interval, as the API's time-series-metadata collection describes the series whose statistic is 00011, the code USGS gives a series of individual points.

Field	Holds	Meaning
begin	date and time or empty	The instant of the series' first reading, which is empty where the location records no such series

Granule

One pass as the listing NASA Earthdata returns describes it, read from the UMM record earthaccess.search_data hands back for each granule.

Field	Holds	Meaning
counter	whole number	The product counter, which rises each time the archive makes the pass's file again under the same CRID, and which the UMM record names ProductCounter among its Identifiers
crid	text	The composite release identifier naming the processing software and inputs that produced the pass, which the UMM record lists among its Identifiers under the type CRID
cycle_number	whole number	The cycle the pass belongs to, which the UMM record spells Cycle under its Track
end	date and time	The last instant the pass covers, in UTC, which the UMM record spells EndingDateTime
opendap	text or empty	The pass's address on PO.DAAC's OPeNDAP service, the USE SERVICE API entry of subtype OPENDAP DATA among the UMM record's RelatedUrls, and empty where the record lists none
pass_number	whole number	The pass within its cycle, which the UMM record spells Pass in the first of the Passes under its Track
start	date and time	The first instant the pass covers, in UTC, which the UMM record spells BeginningDateTime
url	text	The address the pass's file downloads from in PO.DAAC's archive, which the UMM record lists among its RelatedUrls as the GET DATA entry served over HTTPS

OpendapPass

One pass as PO.DAAC's OPeNDAP service describes it in its DAP4 metadata response, its DMR, which names every dimension and every variable the pass holds, at the root or within a group.

Field	Holds	Meaning
sizes	map from text to whole number	The size of every dimension the DMR names, under the dimension's path, such as /num_lines at the root or /left/num_lines within a group
url	text	The address the service answers for the pass at, which the pass's UMM record names
variables	list of text	The path of every variable the DMR names, in the order it names them

AvisoPass

One pass of the Level 3 Unsmoothed product as AVISO's THREDDS catalog lists it, under one of the two directories the handbook names, reproc for the files calibrated from the delayed-time nadir products and forward for those calibrated from the near-real-time ones (§5.8).

Field	Holds	Meaning
cycle_number	whole number	The cycle the pass belongs to, which the file's name carries as the handbook spells it (§3.3)
pass_number	whole number	The pass within its cycle, which the file's name carries after its cycle
path	text	The path the catalog gives the pass's file as the urlPath of its dataset, which follows the server's fileServer and dodsC services alike
stream	Temporality	The directory the catalog lists the file under, forward or reproc