Climate Data Online Web Services: Location Search

This version of the Climate Data Online web services API is deprecated. Please switch to Climate Data Online web services API version 2.

Base URL Address

Every request should begin with the following standard URL. All requests must begin with this base URL.

Base URL
http://www.ncdc.noaa.gov/cdo-services/services

Retrieve Stations

Search for currently available stations within 100km of a given latitude and longitude. Use an URI from below with your token. Search results contain infomation such as an identifier (id), display name (name), minimum date (minDate), maximum date (maxDate), and the type of result (type).

URI Patterns

/datasets/{dataSet}/locationsearch

Output

CDO Web Services returns data output specified by the MIME type of application's request to the CDO Web Service system. For example, sending a request to the CDO services with a request type of "application/json" will retrieve JSON formatted data from the service. Output can also be specified by appending .xml or .json to the end of the service URI address and before any query-type parameters.

Additional Parameters

Below is a list of query parameters that are available for this URI pattern. Construct the web service target from the base URL and the URI patterns above then add these parameters after the question mark query separator (with each field-value pair separated by an ampersand).

Parameter Example Description
token This must be a valid token token supplied to you by NCDC's Climate Data Online access token generator. This is a required option. No data responses will be returned without a valid token.
radius 25 Measured in kilometers, the default is 100km but can be specified at any level. Requires latitude and longitude.
latitude 35.59528 The latitude of a point in decimal format. Required.
longitude -82.55667 The longitude of a point in decimal format. Required.
startdate 20000101 The date format pattern to limit the start date of the web service query. This is a string date mask represented by "yyyyMMdd" where yyyy is a 4-digit year, MM is the 2-digit month, and dd is the 2-digit day. Optional.
enddate 20101231 The date format pattern to limit the end date of the web service query. This is a string date mask represented by "yyyyMMdd" where yyyy is a 4-digit year, MM is the 2-digit month, and dd is the 2-digit day. Optional.
sort best This parameter accepts a string as input and is optional; the default value is best. Valid values for this parameter are: best, alpha, and reverseAlpha.
category stationsOnly Parameter to choose stations, location, or both as results for the search service. Valid string values for this optional parameter are: all, stationsOnly, and locationsOnly.
page 1 This controls which page of data is returned from the service. This variable only accepts an integer as input and is optional.
pagesize 10 This controls the size of the page of data which is returned from the service. This variable only accepts an integer as input and is optional.

URI Examples

Click on the links below and a preview will display example results from
each REST query. Select either XML or JSON to view each respective format.
Copy the URL listed below to use as a reference.
*Note: Your token is required to use these queries

http://www.ncdc.noaa.gov/cdo-services/services/datasets/GHCND/locationsearch?latitude=35.59528&longitude=-82.55667

http://www.ncdc.noaa.gov/cdo-services/services/datasets/PRECIP_HLY/locationsearch?latitude=38.002511&longitude=-98.514404&radius=25

Troubleshooting

If you are having issues retrieving data, please check the following:

  • Check code for typos paying close attention to case
  • Double check your token
  • Try the full RESTful URL in a web browser to see if you are getting the same results