REST Services Usage

Before using REST Services you must obtain a License Token.

If you would like a user friendly interface try the link builder.

All requests follow the form: /services/requestType/.../?output=outputType&token=token

• Valid requestTypes:
  • Site Request
  • Site Info Request
  • Variable Request
  • Variable Info Request
  • Value Request
• Valid outputTypes:
  • csv - all requestTypes and all datasets
  • xml - all requestTypes and all datasets
  • waterml - all requestTypes and all datasets except daily values
• Valid tokens:
  • tokens can be obtained at web services home.
  • Any request made with an invalid token will get a response code of 400.
  • Any request made with a token which has exceeded its frequency will get a response code of 503. Additionally the response header attribute Retry-After will be set to reflect how long the client must wait to retry the request.

Site Request

Url Pattern: /services/sites/datasetId/{locationType}/{locationId1}/{locationId2}/{startDate}/{endDate}/

• Valid datasetIds:
  • daily
  • isd
  • ish
• Valid locationTypes(not required for full station list):
  • countryId - Requires only locationId1
  • countryAbbrev - Requires only locationId1
  • stateId - Requires only locationId1
  • stateAbbrev - Requires only locationId1
• Valid locationId1(not required for full station list):
  • locationId=countryId - country fips
  • locationId=countryAbbrev - country abbrev
  • locationId=stateId - state fips
  • locationId=stateAbbrev - state abbrev
• Valid locationId2(not required in all cases):
• Valid startDates(not required):
  • YYYY
  • YYYYMM
  • YYYYMMDD
  • YYYYMMDDhh
  • YYYYMMDDhhmm
• Valid endDates(not required):
  • YYYY
  • YYYYMM
  • YYYYMMDD
  • YYYYMMDDhh
  • YYYYMMDDhhmm

Site Info Request

Url Pattern: /services/siteinfo/datasetId/stationId/

• Valid datasetIds:
  • daily
  • isd
  • ish
• Valid stationIds:
  • Any stationId determined by a site request

Variable Request

Url Pattern: /services/variables/datasetId/

• Valid datasetIds:
  • daily
  • isd
  • ish

Variable Info Request

Url Pattern: /services/variableinfo/datasetId/variableId/

• Valid datasetIds:
  • daily
  • isd
  • ish
• Valid variableIds:
  • Any variableId(abbrev) determined by a variable requests.

Value Request

Url Pattern: /services/values/datasetId/stationId/variableId/startDate/endDate/

• Valid datasetIds:
  • daily
  • isd
  • ish
• Valid stationIds:
  • Any stationId determined by a site request
• Valid variableIds:
  • Any variableId(abbrev) determined by a variable request
• Valid startDates:
  • YYYY
  • YYYYMM
  • YYYYMMDD
  • YYYYMMDDhh
  • YYYYMMDDhhmm
• Valid endDates:
  • YYYY
  • YYYYMM
  • YYYYMMDD
  • YYYYMMDDhh
  • YYYYMMDDhhmm