{"openapi":"3.1.0","info":{"title":"AWDB REST API","description":"AWDB REST API","version":"1.0"},"servers":[{"url":"https://wcc.sc.egov.usda.gov/awdbRestApi","description":"Generated server url"}],"tags":[{"name":"Station Metadata","description":"Method to retrieve the station metadata for one or more stations"},{"name":"Forecast","description":"Method to get forecast data for one or more stations"},{"name":"Reference Data","description":"Gets reference data"},{"name":"Data","description":"Method to get data for one or more stations"}],"paths":{"/services/v1/stations":{"get":{"tags":["Station Metadata"],"summary":"Gets the metadata for one or more stations","description":"Retrieves the station metadata for one or more stations","operationId":"getStations","parameters":[{"name":"stationTriplets","in":"query","description":"A comma separated list of station triplets (ie. stationId:stateCode:networkCode).  Any portion of the triplet can contain the '\\*' wildcard character.  For example, if you want all SNOTEL stations in OR or WA, you can request '*:OR:SNTL, *:WA:SNTL'.","required":false,"schema":{"type":"string"}},{"name":"stationNames","in":"query","description":"A comma separated list of station names (can contain wildcards)","required":false,"schema":{"type":"string"}},{"name":"dcoCodes","in":"query","description":"A comma separated list of DCO codes","required":false,"schema":{"type":"string"}},{"name":"countyNames","in":"query","description":"A comma separated list of county names (can contain wildcards).  If specified, only stations from at least one of the counties specified will be returned.","required":false,"schema":{"type":"string"}},{"name":"elements","in":"query","description":"A comma separated list of elements in the format elementCode:heightDepth:ordinal.  Any part of the element string can contain the '*' wildcard character.  The heightDepth and ordinal are optional.  If heightDepth is not specified then it is assumed to be null.  If the ordinal is not specified, then it is assumed to be 1.  The heightDepth is in inches. The list of stations will be filtered to only those that contain at least one of the elements specified and the list of stations elements will be filter to only those that have these elements.  Examples: PREC, WTEQ, SMS:\\*, PREC::2","required":false,"schema":{"type":"string"}},{"name":"durations","in":"query","description":"A comma separated list of durations.  The available durations are: HOURLY, DAILY, SEMIMONTHLY, MONTHLY, CALENDAR_YEAR, WATER_YEAR, and SEASONAL.  Only stations that have a station element for at least one of the durations specified will be returned.  The list of station elements returned will be limited to these durations.","required":false,"schema":{"type":"string"}},{"name":"hucs","in":"query","description":"A comma separated list of hucs (can contain wildcards)","required":false,"schema":{"type":"string"}},{"name":"returnForecastPointMetadata","in":"query","description":"If true, return forecast point metadata for stations that are forecast points","required":false,"schema":{"type":"boolean","default":false}},{"name":"returnReservoirMetadata","in":"query","description":"If true, return reservoir metadata for reservoir stations","required":false,"schema":{"type":"boolean","default":false}},{"name":"returnStationElements","in":"query","description":"If true, return the list of station elements for each station","required":false,"schema":{"type":"boolean","default":false}},{"name":"activeOnly","in":"query","description":"If true, only return active stations and station elements","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Successful retrieval of the station metadata","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StationDTO"}}}}},"400":{"description":"Bad request. One or more of the parameters are invalid"},"500":{"description":"Internal server error"}}}},"/services/v1/reference-data":{"get":{"tags":["Reference Data"],"summary":"Gets reference data","description":"Retrieves one or more types of reference data","operationId":"getReferenceData","parameters":[{"name":"referenceLists","in":"query","description":"A comma-separated list of reference data to return. Options include: dcos, durations, elements, forecastPeriods, functions, instruments, networks, physicalElements, states, and units. If not specified, all the lists are returned.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful retrieval of the data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceDataDTO"}}}},"400":{"description":"Bad request. Invalid parameter."},"500":{"description":"Internal server error"}}}},"/services/v1/forecasts":{"get":{"tags":["Forecast"],"summary":"Gets forecast data for one or more stations","description":"Retrieves forecast data for one or more stations","operationId":"getForecasts","parameters":[{"name":"stationTriplets","in":"query","description":"A comma separated list of station triplets (ie. stationId:stateCode:networkCode). Any portion of the triplet can contain the wildcard character. For example, if you want all USGS stations in OR or WA, you can request '*:OR:USGS, *:WA:USGS'.","required":true,"schema":{"type":"string"}},{"name":"elementCodes","in":"query","description":"A comma separated list of element codes. Examples: RESC, SRVO, SRVOO, JDAY, REST","required":false,"schema":{"type":"string"}},{"name":"beginPublicationDate","in":"query","description":"The beginning of the publication date period for which to retrieve data. Expects either 'yyyy-MM-dd' or 'MM/dd/yyyy' format. Defaulted to the start of the current water year, if not specified.","required":false,"schema":{"type":"string"}},{"name":"endPublicationDate","in":"query","description":"The end of the publication date period for which to retrieve data. Expects either 'yyyy-MM-dd' or 'MM/dd/yyyy' format. Defaulted to current day, if not specified.","required":false,"schema":{"type":"string"}},{"name":"exceedenceProbabilities","in":"query","description":"A comma separated list of exceedence probabilities. Example: \"10,30,50\"","required":false,"schema":{"type":"string"}},{"name":"forecastPeriods","in":"query","description":"A comma separated list of forecast periods. Examples: 03-01,07-31 or [03-01,07-31] or [,07-31] or [03-01,]","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful retrieval of the data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ForecastDTO"}}}}},"400":{"description":"Bad request. One or more of the parameters are invalid or too much data requested."},"413":{"description":"Request too large"},"500":{"description":"Internal server error"}}}},"/services/v1/data":{"get":{"tags":["Data"],"summary":"Gets data for one or more stations","description":"Retrieves data for one or more stations","operationId":"getData","parameters":[{"name":"stationTriplets","in":"query","description":"A comma separated list of station triplets (ie. stationId:stateCode:networkCode).  Any portion of the triplet can contain the '\\*' wildcard character.  For example, if you want all SNOTEL stations in OR or WA, you can request '*:OR:SNTL, *:WA:SNTL'.","required":true,"schema":{"type":"string"}},{"name":"elements","in":"query","description":"A comma separated list of elements in the format elementCode:heightDepth:ordinal.  Any part of the element string can contain the '*' wildcard character.  The heightDepth and ordinal are optional.  If heightDepth is not specified then it is assumed to be null.  If the ordinal is not specified, then it is assumed to be 1.  The heightDepth is in inches. Examples: PREC, WTEQ, SMS:\\*, PREC::2","required":true,"schema":{"type":"string"}},{"name":"duration","in":"query","description":"The duration of the data to retrieve","required":false,"schema":{"type":"string","default":"DAILY","enum":["DAILY","HOURLY","SEMIMONTHLY","MONTHLY","CALENDAR_YEAR","WATER_YEAR"]}},{"name":"beginDate","in":"query","description":"The begin date of the data to retrieve. Expects either a date or a relative date. The date must be in the 'yyyy-MM-dd HH:mm' or 'MM/dd/yyyy HH:mm' format (time defaults to midnight when not specified). Relative dates can be 0 (the current date) or -n where the unit of n corresponds to the duration.","required":false,"schema":{"type":"string"}},{"name":"endDate","in":"query","description":"The end date of the data to retrieve. Expects either a date or a relative date. The date must be in the 'yyyy-MM-dd HH:mm' or 'MM/dd/yyyy HH:mm' format (time defaults to midnight when not specified). Relative dates can be 0 (the current date) or -n where the unit of n corresponds to the duration.","required":false,"schema":{"type":"string"}},{"name":"insertOrUpdateBeginDate","in":"query","description":"The date from which to retrieve new or changed data. Expects either yyyy-MM-dd HH:mm or MM/dd/yyyy HH:mm format. Hours and minutes are optional and will be considered as 00 if not specified.","required":false,"schema":{"type":"string"}},{"name":"periodRef","in":"query","description":"Indicates whether data shall be returned with a timestamp at the START of the period for which it was recorded or the END","required":false,"schema":{"type":"string","default":"END","enum":["START","END"]}},{"name":"centralTendencyType","in":"query","description":"The central tendencies to return with each data value.  If set to ALL, then both average and median will be returned.  If MEDIAN, only medians will be returned.  If AVERAGE, only averages will be returned.","required":false,"schema":{"type":"string","default":"NONE","enum":["NONE","ALL","MEDIAN","AVERAGE"]}},{"name":"returnFlags","in":"query","description":"If true, return the flags with each data value","required":false,"schema":{"type":"boolean","default":false}},{"name":"returnOriginalValues","in":"query","description":"If true, return original values (and original flags if returnFlags=true)","required":false,"schema":{"type":"boolean","default":false}},{"name":"returnSuspectData","in":"query","description":"If true, data marked as suspect will not be filtered out","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful retrieval of the data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StationDataDTO"}}}}},"400":{"description":"Bad request. One or more of the parameters are invalid or too much data requested."},"413":{"description":"Request too large"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"DataDTO":{"type":"object","description":"Data for a given station and element","properties":{"stationElement":{"$ref":"#/components/schemas/StationElementDTO"},"timingCentralTendencies":{"$ref":"#/components/schemas/TimingCentralTendenciesDTO"},"values":{"type":"array","items":{"$ref":"#/components/schemas/DataValueDTO"}},"error":{"type":"string","example":"Unsupported operation - the insertOrUpdateBeginDate parameter is not supported for derived data (NOTE: Only included when there is an error)."}}},"DataValueDTO":{"type":"object","description":"A data value","properties":{"date":{"type":"string","description":"The timestamp of the data. Used only for DAILY and HOURLY durations.","example":"2022-01-01"},"month":{"type":"integer","format":"int32","description":"The month of the data value (1-12). Used only for MONTHLY and SEMIMONTHLY durations.","example":1},"monthPart":{"type":"string","description":"The half of month of the data value ('1' for first half, '2' for second half). Used only for SEMIMONTHLY durations.","example":"1"},"year":{"type":"integer","format":"int32","description":"The year of the data value. Used only for WATER_YEAR, CALENDAR_YEAR, MONTHLY, and SEMIMONTHLY durations.","example":2022},"collectionDate":{"type":"string","description":"The date the data value was collected. Used only for SEMIMONTHLY durations.","example":"2021-12-31"},"value":{"type":"number","description":"The data value","example":1.2},"qcFlag":{"type":"string","description":"The qc flag of the data value","example":"E"},"qaFlag":{"type":"string","description":"The qa flag of the data value","example":"A"},"origValue":{"type":"number","description":"The original data value","example":1.3},"origQcFlag":{"type":"string","description":"The original qc flag of the data value","example":"V"},"average":{"type":"number","description":"The 30-year average","example":1.4},"median":{"type":"number","description":"The 30-year median","example":1.0}}},"DcoDTO":{"type":"object","description":"Contains DCO reference data.","properties":{"code":{"type":"string","description":"The DCO code","example":"OR"},"name":{"type":"string","description":"The DCO Name","example":"OREGON"}}},"DurationDTO":{"type":"object","description":"Contains duration reference data.","properties":{"code":{"type":"string","description":"The duration code","example":"D"},"name":{"type":"string","description":"The duration name","example":"DAILY"},"durationMinutes":{"type":"string","description":"The duration in minutes","example":"1440"}}},"ElementDTO":{"type":"object","description":"Contains element reference data.","properties":{"code":{"type":"string","description":"The element code","example":"PREC"},"name":{"type":"string","description":"The element name","example":"PRECIPITATION ACCUMULATION"},"physicalElementName":{"type":"string","description":"The physical element name","example":"precipitation accumulation"},"functionCode":{"type":"string","description":"The function code","example":"C"},"dataPrecision":{"type":"integer","format":"int32","description":"The precision of the data","example":2},"description":{"type":"string","description":"The element description","example":"Water Year Accumulated Precipitation"},"storedUnitCode":{"type":"string","description":"The stored unit code","example":"in"},"englishUnitCode":{"type":"string","description":"The english unit code","example":"in"},"metricUnitCode":{"type":"string","description":"The metric unit code","example":"mm"}}},"ForecastDTO":{"type":"object","description":"Contains one or more forecasts for a forecast point.","properties":{"stationTriplet":{"type":"string","description":"The station triplet of the forecast point.","example":"09430500:CO:USGS"},"forecastPointName":{"type":"string","description":"The name of the forecast point.","example":"Gila R at Gila"},"data":{"type":"array","description":"Contains forecast data for a forecast point.","items":{"$ref":"#/components/schemas/ForecastDataDTO"}}}},"ForecastDataDTO":{"type":"object","description":"Contains forecast data for a forecast point.","properties":{"elementCode":{"type":"string","description":"The element code related to the forecast record.","example":"SRVO"},"forecastPeriod":{"type":"array","description":"The start (MM-DD) and end (MM-DD) of the forecast period that the forecast is for.","example":["04-01","07-31"],"items":{"type":"string"}},"forecastStatus":{"type":"string","description":"Indicates the status of the Forecast.","example":"final"},"issueDate":{"type":"string","description":"The issue date of the forecast.","example":"2023-10-02 07:45:52"},"periodNormal":{"type":"number","description":"The forecast period normal.","example":13.6},"publicationDate":{"type":"string","description":"The publication date of the forecast value.","example":"2023-04-01"},"unitCode":{"type":"string","description":"The unit code of a forecast.","example":"kac_ft"},"forecastValues":{"type":"object","additionalProperties":{"type":"number"},"description":"A dictionary of forecast values where the key is the exceedence probability and the value is the corresponding forecast value.","example":{"10":36.5,"30":28.3,"50":24.1}}}},"ForecastPeriodDTO":{"type":"object","description":"Contains forecast period reference data.","properties":{"code":{"type":"string","description":"The forecast period code","example":"D1"},"name":{"type":"string","description":"The forecast period name","example":"J15-JAN"},"description":{"type":"string","description":"The forecast period description","example":"Jan 15 through Jan"},"beginMonthDay":{"type":"string","description":"The beginning month and day for the forecast period","example":"01-15"},"endMonthDay":{"type":"string","description":"The ending month and day for the forecast period","example":"01-31"}}},"ForecastPointDTO":{"type":"object","description":"Contains information about a forecast point","properties":{"name":{"type":"string","description":"The name of the forecast point","example":"Alamosa Ck ab Terrace Reservoir"},"forecaster":{"type":"string","description":"The user name of the forecaster who forecasts for this station","example":"agoodbody"},"exceedenceProbabilities":{"type":"array","description":"The name to display in the UI for the profile type","example":[10,30,50,70,90],"items":{"type":"integer","format":"int32"}}}},"FunctionDTO":{"type":"object","description":"Contains function reference data.","properties":{"code":{"type":"string","description":"The function code","example":"C"},"abbreviation":{"type":"string","description":"The abbreviation","example":"OBS"},"name":{"type":"string","description":"The name","example":"current observation"}}},"InstrumentDTO":{"type":"object","description":"Contains instrument reference data.","properties":{"name":{"type":"string","description":"The instrument name","example":"150\" transducer - unknown"},"transducerLength":{"type":"integer","format":"int32","description":"The transducer length","example":150},"dataPrecisionAdjustment":{"type":"integer","format":"int32","description":"The data precision adjustment","example":0},"manufacturer":{"type":"string","description":"The manufacturer","example":"Sensotec/Druck/Edcliff"},"model":{"type":"string","description":"The model","example":"unknown"},"active":{"type":"boolean","description":"Is this instrument active","example":false}}},"NetworkDTO":{"type":"object","description":"Contains network reference data.","properties":{"code":{"type":"string","description":"The network code","example":"USGS"},"name":{"type":"string","description":"The network name","example":"STREAMFLOW"},"description":{"type":"string","description":"The network description","example":"STREAMFLOW NETWORK STATIONS"}}},"PhysicalElementDTO":{"type":"object","description":"Contains physical element reference data.","properties":{"name":{"type":"string","description":"The physical element name","example":"snow depth"},"shefPhysicalElementCode":{"type":"string","description":"The SHEF physical element code","example":"SD"}}},"ReferenceDataDTO":{"type":"object","description":"Contains one or more types of reference data.","properties":{"dcos":{"type":"array","description":"Contains DCO reference data.","items":{"$ref":"#/components/schemas/DcoDTO"}},"durations":{"type":"array","description":"Contains duration reference data.","items":{"$ref":"#/components/schemas/DurationDTO"}},"elements":{"type":"array","description":"Contains element reference data.","items":{"$ref":"#/components/schemas/ElementDTO"}},"forecastPeriods":{"type":"array","description":"Contains forecast period reference data.","items":{"$ref":"#/components/schemas/ForecastPeriodDTO"}},"functions":{"type":"array","description":"Contains function reference data.","items":{"$ref":"#/components/schemas/FunctionDTO"}},"instruments":{"type":"array","description":"Contains instrument reference data.","items":{"$ref":"#/components/schemas/InstrumentDTO"}},"networks":{"type":"array","description":"Contains network reference data.","items":{"$ref":"#/components/schemas/NetworkDTO"}},"physicalElements":{"type":"array","description":"Contains physical element reference data.","items":{"$ref":"#/components/schemas/PhysicalElementDTO"}},"states":{"type":"array","description":"Contains State reference data.","items":{"$ref":"#/components/schemas/StateDTO"}},"units":{"type":"array","description":"Contains unit reference data.","items":{"$ref":"#/components/schemas/UnitDTO"}}}},"ReservoirMetadataDTO":{"type":"object","description":"Contains reservoir metadata","properties":{"capacity":{"type":"number","description":"The capacity of the reservoir in acre-feet","example":153000.0},"elevationAtCapacity":{"type":"number","description":"The elevation of the reservoir (in feet) when it is at capacity","example":350.0},"usableCapacity":{"type":"number","description":"The usable capacity of the reservoir in acre-feet","example":148640.0}}},"StateDTO":{"type":"object","description":"Contains state reference data.","properties":{"code":{"type":"string","description":"The state code","example":"CO"},"fipsNumber":{"type":"string","description":"The state FIPS number code","example":"08"},"name":{"type":"string","description":"The state name","example":"COLORADO"},"countryCode":{"type":"string","description":"The country code","example":"US"}}},"StationDTO":{"type":"object","description":"Contains metadata about a station","properties":{"stationTriplet":{"type":"string","description":"The station triplet of the station","example":"302:OR:SNTL"},"stationId":{"type":"string","description":"The id of the station","example":"302"},"stateCode":{"type":"string","description":"The 2-character state code of the station","example":"OR"},"networkCode":{"type":"string","description":"The network code of the station","example":"SNTL"},"name":{"type":"string","description":"The name of the station","example":"ANEROID LAKE #2"},"dcoCode":{"type":"string","description":"The DCO code of the station","example":"OR"},"countyName":{"type":"string","description":"The name of the county that the station is located in","example":"Wallowa"},"huc":{"type":"string","description":"The hydrologic unit code of the station","example":"170601050101"},"elevation":{"type":"number","description":"The elevation (in feet) of the station","example":7400.0},"latitude":{"type":"number","description":"The latitude of the station","example":45.21328},"longitude":{"type":"number","description":"The longitude of the station","example":45.21328},"dataTimeZone":{"type":"number","description":"The timezone offset from GMT of the data for the station","example":-8.0},"pedonCode":{"type":"string","description":"The NRCS pedon code for the station"},"shefId":{"type":"string","description":"The SHEF id of the station","example":"ANR03"},"operator":{"type":"string","description":"The entity in charge of the station","example":"NRCS"},"beginDate":{"type":"string","description":"The date that the station was put into service","example":"1980-10-01 00:00"},"endDate":{"type":"string","description":"The date that the station was taken out of service or 2100-01-01 if still in service","example":"2100-01-01"},"forecastPoint":{"$ref":"#/components/schemas/ForecastPointDTO"},"reservoirMetadata":{"$ref":"#/components/schemas/ReservoirMetadataDTO"},"stationElements":{"type":"array","description":"The station elements of the station","items":{"$ref":"#/components/schemas/StationElementDTO"}},"associatedHucs":{"type":"array","description":"Hydrologic units within 5000m of this station","example":["170501041601","170501070301","170501070404","170501041603","170501041703","170501041304"],"items":{"type":"string"}}},"required":["stationId"]},"StationDataDTO":{"type":"object","description":"Contains data for a station and one or more station elements","properties":{"stationTriplet":{"type":"string","description":"The station triplet of the station","example":"302:OR:SNTL"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DataDTO"}}}},"StationElementDTO":{"type":"object","description":"Contains information about a station element","properties":{"elementCode":{"type":"string","description":"The element code","example":"WTEQ"},"ordinal":{"type":"integer","format":"int32","description":"The ordinal of the station element","example":1},"heightDepth":{"type":"integer","format":"int32","description":"The height/depth of the station element in inches","example":null},"durationName":{"type":"string","description":"The duration name of the station element","enum":["DAILY, HOURLY, SEMIMONTHLY, MONTHLY, CALENDAR_YEAR, WATER_YEAR"],"example":"DAILY"},"dataPrecision":{"type":"integer","format":"int32","description":"The data precision of the data for the station element","example":2},"storedUnitCode":{"type":"string","description":"The units that the data is stored in","example":"in"},"originalUnitCode":{"type":"string","description":"The units that the data was collected in","example":"in"},"beginDate":{"type":"string","description":"The date that the station element was put into service","example":"1980-10-30 15:53"},"endDate":{"type":"string","description":"The date that the station element was taken out of service or 2100-01-01 if still in service","example":"2100-01-01"},"derivedData":{"type":"boolean","description":"true/false if the station element data is derived","example":false}}},"TimingCentralTendenciesDTO":{"type":"object","properties":{"medianPeak":{"$ref":"#/components/schemas/TimingWithValueDTO","description":"Median month, day and value in which snow water equivalent peak occurs"},"medianOnset":{"$ref":"#/components/schemas/TimingDTO","description":"Median month and day in which snow water equivalent onset occurs"},"medianMeltout":{"$ref":"#/components/schemas/TimingDTO","description":"Median month and day in which snow water equivalent meltout occurs"},"averagePeak":{"$ref":"#/components/schemas/TimingWithValueDTO","description":"Average month, day and value in which snow water equivalent peak occurs"},"averageOnset":{"$ref":"#/components/schemas/TimingDTO","description":"Average month and day in which snow water equivalent onset occurs"},"averageMeltout":{"$ref":"#/components/schemas/TimingDTO","description":"Average month and day in which snow water equivalent meltout occurs"}}},"TimingDTO":{"type":"object","properties":{"month":{"type":"integer","format":"int32","description":"The month","maximum":12,"minimum":1},"day":{"type":"integer","format":"int32","description":"The day","maximum":31,"minimum":1}}},"TimingWithValueDTO":{"type":"object","properties":{"month":{"type":"integer","format":"int32","description":"The month","maximum":12,"minimum":1},"day":{"type":"integer","format":"int32","description":"The day","maximum":31,"minimum":1},"value":{"type":"number","description":"The value","example":23.2}}},"UnitDTO":{"type":"object","description":"Contains unit reference data.","properties":{"code":{"type":"string","description":"The unit code","example":"bar"},"singularName":{"type":"string","description":"The singular unit name","example":"bar"},"pluralName":{"type":"string","description":"The plural unit name","example":"bars"},"description":{"type":"string","description":"The unit description","example":"barometric pressure"}}}}}}