Pilot Mountain

CRONOS API Reference

  1. Basic URL Request Format
  2. Examples and Descriptions
  3. Language Specific Code Examples
  4. Station Inventory
  5. Known Issues/Limitations


BASIC REQUEST DESCRIPTION

Each request is sent to the service using a URL string. The format is as follows:

http://www.nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=LAKE&start=2009-08-14&end=2009-08-24&obtype=H&parameter=temp,rh,sr,ws,precip&hash=

Note the hash above is empty. Please use the unique hash assigned to you by the State Climate Office.

Options are passed to the service using the http get request. This begins after the "?" in the above URL.

Required inputs

  • station - Specifies the station(s) of interest
    • Can be one or more stations, separated by commas
    • Stations can be from different networks - e.g. station=KRDU,LAKE,KTTA,NDUK
  • start - Specifies the start date for the data
    • Date in yyyy-mm-dd format for obtype=D (daily data)
    • Date in yyyy-mm-dd hh:mm:ss format for obtype=H, obtype=O (hourly and minute data)
  • end - Specifies the end date for the data
    • Same as above - (if no date is specified, today's date is assumed)
  • obtype - Specifies the desired time resolution. You may only request one obtype at a time
    • O - for minute data (ECONET only)
    • H - for hourly data
    • D - for daily data
  • parameter - Specifies the desired parameters, separated by comma
    • you may use "all" for all available paramaters, but this will generate a large amount of data and is not recommended if requesting stations from different networks
    • see full list of parameters
  • hash - Unique string assigned by the State Climate Office that identifies each user

Optional inputs

  • delimiter - Character/string used to separate data observations -- default is "|" (pipe).
    • tab
    • comma
  • blank - Some parameters may have a NULL value, which will appear as a blank. Use this argument to change the blank to something else (i.e., -99999).
  • show_missing - Calculate the presence of missing rows/timestamps and show them as missing.
    • true - show presence of missing rows.
  • fill_missing - For estimated missing rows, fill their values in with this string. Default is the text "missing"
  • qc - Impose quality control restrictions on data retrieval. If omitted, all data regardless of QC status will be retrieved.
    • good - get only good data (where internal qc procedures indicate data are good for the parameters you request). Can be used with obtype=O, H or D. Will also include data that has not yet been quality controlled.
    • bad - get only bad data (where internal qc procedures indicate data are bad for the parameters you request). Can be used with obtype=O, H or D. Internal QC procedures are not run for COOP data. For COOP stations, this will return only data with flags matching 2 or 3, according to NCDC.
  • qc_flags - Show internal QC flags, if available.
    • true - show internal, overall QC integer when available. -1=not yet checked; 0=good; 1=probably good; 2=probably bad; 3=bad. This will show nothing if the data being pulled are derived from a higher temporal scale. For example, using this option to show QC integer when pulling hourly data derived from one-minute data will show nothing. If using this flag with COOP data, the raw flags will be shown instead.


EXAMPLES AND DESCRIPTIONS

Station Metadata: For each request, station metadata is returned. Sample station metadata for: station=KRDU:

## CRONOS
## API beta
## State Climate Office of North Carolina
## NC State University
## www.nc-climate.ncsu.edu or 919.515.3056
## Data below may not have been quality controlled. Use data at your own risk.
##
##
## Station metadata...
## Station 1
## ID: KRDU
## Network: ASOS
## Name: Raleigh-Durham Airport
## City,State: Raleigh, NC
## County: Wake County
## Lat,Long: 35.8776389, -78.7874722
## Elevation: 435 ft.
## Supported by: NOAA National Weather Service
## Data begin: 1948-07-01

Parameter metadata: In addition, parameter metadata is returned. Sample parameter metadata for parameter=temp,dew,rh,ws,wd,slp,altimeter:

## Parameter metadata...
## ob: observation date/time EST
## DataAvailability: Ratio of amount of data that was compiled to the amount of data that was expected to have been compiled. Good indicator of data availability for aggregated time steps. (%)
## temp: Air Temperature (C)
## dew: Dewpoint Temperature (C)
## rh: Relative Humidity (%)
## ws: Wind Speed (m/s)
## wd: Wind Direction (degrees)
## slp: Sea Level Pressure (mb)
## altimeter: Altimeter setting (in Hg)

Data: Data is returned, one observation per line, delimited by "|" (pipe). To specify a different delimiter, such as a comma, you may use the "&delimiter=comma" option in the URL string.

  1. Hourly ASOS data for multiple stations - parameters are temperature, dewpoint, and sea level pressure

    http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU,KGSO&start=2009-01-01&end=2009-01-01 03:00:00&obtype=H&parameter=temp,dew,slp&hash=
station|ob|DataAvailability|temp|dew|slp
KGSO|2009-01-01 00:54:00|100|-3.9|-12.8|1025.7
KGSO|2009-01-01 01:54:00|100|-2.8|-13.9|1025.7
KGSO|2009-01-01 02:54:00|100|-3.3|-14.4|1026.4
KRDU|2009-01-01 00:51:00|100|-2.2|-12.8|1025.4
KRDU|2009-01-01 01:51:00|100|-2.2|-12.8|1025.7
KRDU|2009-01-01 02:51:00|100|-3.3|-12.2|1026.1
  1. Daily COOP data for multiple stations - parameters are maximum, minimum, average temperature, and precipitation

    http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=317069,311690&start=2009-01-01&end=2009-01-05&obtype=D&parameter=tempmax,tempmin,tempavg,precip&hash=
station|ob|DataAvailability|tempmax|tempmin|tempavg|precip
311690|2009-01-01|100|6.111|-6.667|-0.278|0
311690|2009-01-02|100|7.222|-2.778|2.222|0.02
311690|2009-01-03|100|8.889|3.889|6.389|0.01
311690|2009-01-04|100|14.444|7.222|10.833|0.51
311690|2009-01-05|100|19.444|11.667|15.5555|0.04
317069|2009-01-01|100|5.556|-5|0.278|0
317069|2009-01-02|100|5.556|-2.778|1.389|0.05
317069|2009-01-03|100|14.444|0|7.222|0
317069|2009-01-04|100|13.333|6.111|9.722|0.62
317069|2009-01-05|100|15.556|11.667|13.6115|0
  1. Daily ASOS data -- note: ASOS data is hourly. Daily extremes and averages are calculated from the hourly observations

    http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU,KGSO,KILM&start=2009-01-01&end=2009-01-03&obtype=D&parameter=tempmax,tempmin,tempavg,precip&hash=
## Parameter metadata...
## ob: observation date/time (EST)
## DataAvailability: Ratio of amount of data that was compiled to the amount of data that was expected to have been compiled. Good indicator of data availability for aggregated time steps. (%)
## tempmax: Daily Max Temperature (C)
## tempmin: Daily Min Temperature (C)
## tempavg: Daily Avg Temperature (C)
## precip: Daily Precipitation (inch)

station|ob|DataAvailability|tempmax|tempmin|tempavg|precip
KGSO|2009-01-01|100.0|4.400000095367432|-6.099999904632568|-1.05|
KGSO|2009-01-02|100.0|6.699999809265137|-2.200000047683716|1.90|0.09
KGSO|2009-01-03|100.0|13.300000190734863|-2.200000047683716|5.12|
KILM|2009-01-01|100.0|7.199999809265137|-2.799999952316284|0.95|
KILM|2009-01-02|100.0|17.799999237060547|-2.799999952316284|8.85|0.00
KILM|2009-01-03|100.0|16.700000762939453|5.599999904632568|10.25|
KRDU|2009-01-01|100.0|5.599999904632568|-5|-0.53|
KRDU|2009-01-02|100.0|5.599999904632568|-2.799999952316284|1.43|0.05
KRDU|2009-01-03|100.0|14.399999618530273|0|5.58|
  1. Minute ECONET data - parameters are temperature, relative humidity

    http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=LAKE&start=2009-01-01&end=2009-01-01 00:15:00&obtype=O&parameter=temp,rh&hash=
station|ob|temp|rh
LAKE|2009-01-01 00:00:00|-1.578|43.89
LAKE|2009-01-01 00:01:00|-1.511|44.49
LAKE|2009-01-01 00:02:00|-1.444|45.23
LAKE|2009-01-01 00:03:00|-1.31|44.56
LAKE|2009-01-01 00:04:00|-1.51|44.56
LAKE|2009-01-01 00:05:00|-1.444|44.36
LAKE|2009-01-01 00:06:00|-1.443|44.56
LAKE|2009-01-01 00:07:00|-1.443|43.43
LAKE|2009-01-01 00:08:00|-1.243|45.09
LAKE|2009-01-01 00:09:00|-1.511|44.49
LAKE|2009-01-01 00:10:00|-1.577|44.76
LAKE|2009-01-01 00:11:00|-1.578|44.96
LAKE|2009-01-01 00:12:00|-1.511|44.76
LAKE|2009-01-01 00:13:00|-1.511|45.36
LAKE|2009-01-01 00:14:00|-1.644|45.09
LAKE|2009-01-01 00:15:00|-1.577|44.03


CODE EXAMPLES

wget/cURL

  • For requests that do not require any manipulation, you may use the widely available cURL or wget utilities that come standard on many (linux) platforms
curl "http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU&obtype=H&parameter=temp,dew,rh,precip,ws,wd,slp,altimeter&start=2010-01-01&end=2010-01-01&hash=" > KRDU_hourly_20100101

wget -O KRDU_hourly_20100101 "http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU&obtype=H&parameter=temp,dew,rh,precip,ws,wd,slp,altimeter&start=2010-01-01&end=2010-01-01&hash="

PHP

  • PHP includes some handy functions for opening files. They can also be used to access URL's.
  • How to use the file() function to read data into an array:
<?php

$data = file("http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU&obtype=H&parameter=temp,dew,rh,precip,ws,wd,slp,altimeter&start=2010-01-01&end=2010-01-01&hash=");

print_r ($data);

?>
  • How to use fopen() to go through each line:
<?php

$handle = fopen("http://www.nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU&obtype=H&parameter=temp,dew,rh,precip,ws,wd,slp,altimeter&start=2010-01-01&end=2010-01-01&hash=","r");

if ($handle) {
    while (!feof($handle)) {
        $buffer = fgets($handle, 4096);
        echo $buffer;
    }
    fclose($handle);
}
?>

Perl

#!/usr/bin/perl

## The following modules are required
## can be found @ cpan
use LWP::UserAgent;
use HTTP::Request;

my $URL = 'http://nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSdata.php?station=KRDU&obtype=H&parameter=temp,dew,rh,precip,ws,wd,slp,altimeter&start=2009-01-09&end=2009-01-19&hash=';

my $agent = LWP::UserAgent->new(env_proxy => 1,keep_alive => 1, timeout => 30);
my $header = HTTP::Request->new(GET => $URL);
my $request = HTTP::Request->new('GET', $URL, $header);
my $response = $agent->request($request);

# Check the outcome of the response
if ($response->is_success){
    print "\nContent:\n";
    print $response->as_string;
}
elsif ($response->is_error){
    print "Error:$URL\n";
    print $response->error_as_HTML;
}

Python


CRONOS INVENTORY

An inventory of stations, with complete metadata, is available. http://www.nc-climate.ncsu.edu/dynamic_scripts/cronos/getCRONOSinventory.php

If no arguments are given, the entire inventory is provided. However, the inventory can be restricted to stations that only meet certain criteria. Arguments can be combined.

Optional inputs

  • state - Two-letter abbreviation of states. This will return only stations in the given states.
    • Can be one or more states, separated by commas
  • network - Network ID. This will return only stations of a certain network type.
    • Can be one or more stations, separated by commas
    • Network types include: ASOS, AWOS, COOP, ECONET, RAWS, CRN, BUOY, COCORAHS
  • station - Station IDs.
    • Can be one or more stations, separated by commas
  • lat_top & lat_bot - Top and bottom latitudes for a bounding box.
    • Use decimal degrees. Northern Hemisphere latitudes are positive.
  • lon_left & lon_right - Left and right longitudes for a bounding box.
    • Use decimal degrees. Western Hemisphere longitudes are negative.
  • distance & lat & lon - Get stations within 'distance' miles of a specific lat/lon coordinate.
    • Use decimal degrees. Western Hemisphere longitudes are negative.
    • Distance is in miles. If omitted from query, distance will default to 100 miles.
  • fips_state - Get stations within a state as defined by the FIPS code.
    • Can be one or more states, separated by commas.
  • fips_county - Get stations within a county as defined by the FIPS code.
    • Can be one or more counties, separated by commas.
    • It is recommended this be used on conjunction with fips_state.
  • substitute_ranking - Show ranking of nearby stations that are best fits for tempmax and tempmin. See details on how the rankings were calculated.
    • Set value to the number of ranks you want to see. To see top 5 ranks, set to 5. Rank 1 is best fit; rank 2 is second best fit and so on.
  • wims - WIMS ID. This will return stations that have a specific WIMS ID.
    • Can be one or more IDs, separated by commas.
    • Not all stations in CRONOS have an assigned WIMS ID.

KNOWN LIMITATIONS & ISSUES

  • Some derived parameters are not yet available (i.e., degree days, wind chill, etc).
  • Climate normals are not yet available.
  • QC - added to the API on May 5, 2011. Bugs may be present.
  • Please send bug reports to the State Climate Office of North Carolina at 919-515-3056 or sco@climate.ncsu.edu