Provides derived oceanographic products computed from CO-OPS observational data, including sea level trends, sea level rise projections, high tide flooding statistics and projections, extreme water levels, peak water levels, and benchmark data.
{
"openapi": "3.0.3",
"info": {
"title": "NOAA CO-OPS Derived Product API",
"description": "Provides derived oceanographic products computed from CO-OPS observational data, including sea level trends, sea level rise projections, high tide flooding statistics and projections, extreme water levels, peak water levels, and benchmark data.",
"version": "1.0.0",
"contact": {
"name": "Tide Predictions",
"email": "[email protected]"
},
"license": {
"name": "Public Domain",
"url": "https://www.noaa.gov/disclaimer"
}
},
"servers": [
{
"url": "https://api.tidesandcurrents.noaa.gov/dpapi/prod/webapi",
"description": "NOAA CO-OPS Derived Product API"
}
],
"paths": {
"/toptenwaterlevels": {
"get": {
"operationId": "getTopTenWaterLevels",
"summary": "Get top ten water levels",
"description": "Returns the top ten highest recorded water levels for a given station.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "units",
"in": "query",
"required": false,
"description": "Unit system for returned values.",
"schema": {
"type": "string",
"enum": ["english", "metric"],
"default": "metric"
}
},
{
"name": "datum",
"in": "query",
"required": false,
"description": "Vertical datum for water level values.",
"schema": {
"type": "string",
"enum": ["STND", "MHHW", "MHW", "MSL", "MTL", "MLW", "MLLW", "NAVD", "IGLD", "LWD"]
}
}
],
"responses": {
"200": {
"description": "Top ten water level events",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WaterLevelEvent"
}
}
}
}
}
}
}
}
}
},
"/peakwaterlevels": {
"get": {
"operationId": "getPeakWaterLevels",
"summary": "Get peak water levels by event",
"description": "Returns peak water levels for a specific storm or event.",
"parameters": [
{
"name": "eventid",
"in": "query",
"required": true,
"description": "Numerical event identifier.",
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "units",
"in": "query",
"required": false,
"description": "Unit system for returned values.",
"schema": {
"type": "string",
"enum": ["english", "metric"],
"default": "metric"
}
},
{
"name": "datum",
"in": "query",
"required": false,
"description": "Vertical datum for water level values.",
"schema": {
"type": "string",
"enum": ["STND", "MHHW", "MHW", "MSL", "MTL", "MLW", "MLLW", "NAVD", "IGLD", "LWD"]
}
}
],
"responses": {
"200": {
"description": "Peak water level data for the specified event",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WaterLevelEvent"
}
}
}
}
}
}
}
}
}
},
"/extremewaterlevels": {
"get": {
"operationId": "getExtremeWaterLevels",
"summary": "Get extreme water levels",
"description": "Returns statistically computed extreme (annual or monthly) high and low water levels for a station.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "units",
"in": "query",
"required": false,
"description": "Unit system for returned values.",
"schema": {
"type": "string",
"enum": ["english", "metric"],
"default": "metric"
}
},
{
"name": "extremeType",
"in": "query",
"required": false,
"description": "Whether to return annual or monthly extremes.",
"schema": {
"type": "string",
"enum": ["annuals", "monthlies"]
}
},
{
"name": "levelType",
"in": "query",
"required": false,
"description": "Whether to return high or low extreme water levels.",
"schema": {
"type": "string",
"enum": ["high", "low"]
}
},
{
"name": "details",
"in": "query",
"required": false,
"description": "Additional detail to include in response.",
"schema": {
"type": "string",
"enum": ["exceedancelevels", "exceedancelevelsmonth"]
}
}
],
"responses": {
"200": {
"description": "Extreme water level statistics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
},
"/sealvltrends": {
"get": {
"operationId": "getSeaLevelTrends",
"summary": "Get sea level trends",
"description": "Returns mean sea level trend data for a given station, including rate of change and confidence intervals.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "affiliation",
"in": "query",
"required": false,
"description": "Station affiliation context.",
"schema": {
"type": "string",
"enum": ["Global", "US"],
"default": "US"
}
}
],
"responses": {
"200": {
"description": "Sea level trend data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SeaLevelTrend"
}
}
}
}
}
}
},
"/slr_projections": {
"get": {
"operationId": "getSeaLevelRiseProjections",
"summary": "Get sea level rise projections",
"description": "Returns future sea level rise projections for a station or geographic area based on NOAA scenarios.",
"parameters": [
{
"name": "station",
"in": "query",
"required": false,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "affiliation",
"in": "query",
"required": false,
"description": "Station affiliation.",
"schema": {
"type": "string",
"enum": ["Global", "US"]
}
},
{
"name": "projection_year",
"in": "query",
"required": false,
"description": "Target projection year (e.g., 2050, 2100).",
"schema": {
"type": "integer",
"example": 2050
}
},
{
"name": "scenario",
"in": "query",
"required": false,
"description": "Sea level rise scenario.",
"schema": {
"type": "string",
"enum": [
"low",
"intermediate-low",
"intermediate",
"intermediate-high",
"high",
"extreme"
]
}
},
{
"name": "lat",
"in": "query",
"required": false,
"description": "Latitude for geographic bounding queries.",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "lon",
"in": "query",
"required": false,
"description": "Longitude for geographic bounding queries.",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "min_lat",
"in": "query",
"required": false,
"description": "Minimum latitude for bounding box search.",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "max_lat",
"in": "query",
"required": false,
"description": "Maximum latitude for bounding box search.",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "min_lon",
"in": "query",
"required": false,
"description": "Minimum longitude for bounding box search.",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "max_lon",
"in": "query",
"required": false,
"description": "Maximum longitude for bounding box search.",
"schema": {
"type": "number",
"format": "double"
}
}
],
"responses": {
"200": {
"description": "Sea level rise projections",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
},
"/htf_annual": {
"get": {
"operationId": "getHighTideFloodingAnnual",
"summary": "Get annual high tide flooding statistics",
"description": "Returns annual high tide flooding day counts and flood threshold exceedances for a given station.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "year",
"in": "query",
"required": false,
"description": "Specific year to retrieve (YYYY).",
"schema": {
"type": "integer",
"example": 2022
}
},
{
"name": "range",
"in": "query",
"required": false,
"description": "Number of years to include.",
"schema": {
"type": "integer",
"example": 5
}
},
{
"name": "units",
"in": "query",
"required": false,
"description": "Unit system for returned values.",
"schema": {
"type": "string",
"enum": ["english", "metric"],
"default": "metric"
}
},
{
"name": "datum",
"in": "query",
"required": false,
"description": "Vertical datum for water level values.",
"schema": {
"type": "string",
"enum": ["MHHW", "MHW", "MSL", "MLLW", "NAVD"]
}
}
],
"responses": {
"200": {
"description": "Annual high tide flooding statistics",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HighTideFloodingResponse"
}
}
}
}
}
}
},
"/htf_monthly": {
"get": {
"operationId": "getHighTideFloodingMonthly",
"summary": "Get monthly high tide flooding statistics",
"description": "Returns monthly high tide flooding day counts for a given station.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "year",
"in": "query",
"required": false,
"description": "Year (YYYY).",
"schema": {
"type": "integer",
"example": 2022
}
},
{
"name": "month",
"in": "query",
"required": false,
"description": "Month number (1-12).",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"example": 6
}
}
],
"responses": {
"200": {
"description": "Monthly high tide flooding data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HighTideFloodingResponse"
}
}
}
}
}
}
},
"/htf_projection_decadal": {
"get": {
"operationId": "getHighTideFloodingProjectionDecadal",
"summary": "Get decadal high tide flooding projections",
"description": "Returns projected number of high tide flooding days per decade for a station under different flood thresholds.",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"description": "7-digit station ID.",
"schema": {
"type": "string",
"example": "9414290"
}
},
{
"name": "decade",
"in": "query",
"required": false,
"description": "Target decade (e.g., 2030, 2040).",
"schema": {
"type": "integer",
"example": 2030
}
},
{
"name": "range",
"in": "query",
"required": false,
"description": "Number of decades to project.",
"schema": {
"type": "integer",
"example": 3
}
},
{
"name": "flood_threshold",
"in": "query",
"required": false,
"description": "Flood severity threshold to apply.",
"schema": {
"type": "string",
"enum": ["minor", "moderate", "major"]
}
}
],
"responses": {
"200": {
"description": "Decadal high tide flooding projections",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HighTideFloodingResponse"
}
}
}
}
}
}
},
"/benchmarks": {
"get": {
"operationId": "getBenchmarks",
"summary": "Get benchmark data",
"description": "Returns geodetic benchmark data for a specified survey mark.",
"parameters": [
{
"name": "vm",
"in": "query",
"required": false,
"description": "4-digit vertical monument code.",
"schema": {
"type": "string",
"example": "1234"
}
},
{
"name": "pid",
"in": "query",
"required": false,
"description": "Permanent identifier for a benchmark mark (2 letters + 4 digits).",
"schema": {
"type": "string",
"example": "AB1234"
}
},
{
"name": "date",
"in": "query",
"required": false,
"description": "Date of benchmark survey (YYYY-MM-DD).",
"schema": {
"type": "string",
"format": "date",
"example": "2020-01-01"
}
}
],
"responses": {
"200": {
"description": "Benchmark data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"WaterLevelEvent": {
"type": "object",
"properties": {
"rank": {
"type": "integer",
"description": "Rank of this event (1 = highest)",
"example": 1
},
"date": {
"type": "string",
"description": "Date of the event",
"example": "1982-12-21"
},
"level": {
"type": "number",
"format": "double",
"description": "Water level value",
"example": 2.34
},
"units": {
"type": "string",
"description": "Unit of measurement",
"example": "m"
}
}
},
"SeaLevelTrend": {
"type": "object",
"properties": {
"stationId": {
"type": "string",
"description": "Station ID",
"example": "9414290"
},
"stationName": {
"type": "string",
"description": "Station name",
"example": "San Francisco"
},
"trend": {
"type": "number",
"format": "double",
"description": "Sea level trend rate (mm/year)",
"example": 1.94
},
"ci95": {
"type": "number",
"format": "double",
"description": "95% confidence interval (mm/year)",
"example": 0.19
},
"startYear": {
"type": "integer",
"description": "First year of record used",
"example": 1897
},
"endYear": {
"type": "integer",
"description": "Last year of record used",
"example": 2022
}
}
},
"HighTideFloodingResponse": {
"type": "object",
"properties": {
"stationId": {
"type": "string",
"description": "Station ID",
"example": "9414290"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"year": {
"type": "integer",
"description": "Year of the flooding data",
"example": 2022
},
"minor": {
"type": "number",
"description": "Number of minor flood days",
"example": 4
},
"moderate": {
"type": "number",
"description": "Number of moderate flood days",
"example": 1
},
"major": {
"type": "number",
"description": "Number of major flood days",
"example": 0
}
}
}
}
}
}
}
},
"tags": [
{
"name": "Sea Level",
"description": "Sea level trends and projections"
},
{
"name": "High Tide Flooding",
"description": "High tide flooding statistics and projections"
},
{
"name": "Extreme Water Levels",
"description": "Extreme and peak water level events"
}
]
}