The Applied Climate Information System (ACIS) Web Services consists of five types of calls - StnMeta, StnData, MultiStnData, GridDate and General. Each of these calls is documented below. Each call has certain parameters that are required and optional parameters that let you further refine your request.
Web service calls can be made in several ways. Basic calls can be made via http requests from a web browser with the complete call specified in the url. More advanced calls require a JSON object to adequately specify the request. Such requests can be submitted to the ACIS server from most programming languages by specifying the server address and a JSON "params" object. In this document, some of the examples will take the form of a simple url, while others will provide just the "params" object that will be sumitted to the server via a JavaScript POST request. In both cases, results will be displayed in a pop-up dialog window.
The ACIS Query Builder can be a useful tool for learning how the ACIS Web Services calls are constructed and how the returned results are formatted.
The StnMeta web services call returns metadata for a station or stations meeting the specified criteria.
| Key | Description |
|---|---|
| sids | Station identifier(s) and optional id types codes. Can be any of the id types in Table 1. Ambiguous identifiers require the station id type code be appended to the identifier, separated by a space (e.g. BUFthr 9). The value associated with this key can be either a single id or a list of ids. This key cannot be combined with any of the other keys in this table. |
| county | County (FIPS) id. Made up of a 2-digit state and 3-digit county id. List of FIPS codes. |
| climdiv | NCDC Climate Division. Consists of a 2-letter state abbreviation and 2-digit climate division id (e.g. FL01). Map of climate divisions. |
| cwa | NWS County Warning Area. Three-letter forecast office identifier. |
| basin | River basin id. Eight-digit USGS Hydrological Unit Code. |
| state | State postal abbreviation. Two-letter abbreviations. A Wikipedia map or list is available for reference. The 50 states plus territories (AS, GU, MP, PR, VI), freely associated states (FM, MH, PW), and federal district (DC) are available. Note that using DC may be somewhat unreliable because many stations are listed as either MD or VA, rather than DC, in their metadata. |
| bbox | Bounding box. A latitude/longitude bounding box defined in decimal degrees (West, South, East, North) with negative values indicating west longitude and south latitude (e.g. -90.7, 40.5, -88.9, 41.5). |
sids) to further refine your request (see Example 1.5)..
| Code | Type | Description | Example |
|---|---|---|---|
| 1 | WBAN | 5-digit WBAN id | 14742 |
| 2 | COOP | 6-digit COOP id | 304174 |
| 3 | FAA | 3-character FAA id | LAX |
| 4 | WMO | 5-digit WMO id | 72223 |
| 5 | ICAO | 4-character ICAO id | KGRR |
| 6 | GHCN | 11-character GHCN id | USW00003927 |
| 7 | NWSLI | 5-character NWSLI | AURN6 |
| 8 | RCC | RCC local id | 301402 |
| 9 | ThreadEx | 6-character ThreadEx id | HSVthr |
| 10 | CoCoRaHS | 8-character CoCoRaHS id | NYTM0004 |
| Key | Description |
|---|---|
| meta | Metadata items to be returned. A list of one or more of the metadata codes found in Table 2. If not specified, the default items
indicated in Table 2 will be returned. If valid_daterange is specified, elems must also be specified and
an array will be returned containing the valid date range for each variable in the order specified in elems. |
| elems | Elements. A list of one or more of the codes (or Var Majors) found in Table 3. Only stations reporting any of the elements specified will be returned. |
| sdate | Start date (yyyy-mm-dd or yyyymmdd). Beginning of desired date range. Can alternatively be just a year (yyyy) or a year and
month (yyyy-mm). If used, request must also contain edate. Only stations with any data between sdate
and edate will be returned. |
| edate | End date (yyyy-mm-dd or yyyymmdd). End of desired date range. Can alternatively be just a year (yyyy) or a year and
month (yyyy-mm). If used, request must also contain sdate. Only stations with any data between sdate
and edate will be returned. |
| date | Date (yyyy-mm-dd or yyyymmdd). Can be used in place of sdate/edate, if only a single date is adequate to define your request. Can alternatively be just a year (yyyy) or a year and month (yyyy-mm). Only stations with any data for the given date will be returned. |
| output | Type of output (json or csv). The default is json. If meta is specified, json is the only output option. |
| Code | Description |
|---|---|
| name * | Station name |
| state * | 2-letter state abbrev |
| sids * | Array of station ids/types |
| ll * | Longitude and latitude (decimal degrees) |
| elev * | Elevation (feet) |
| uid * | Unified ACIS id |
| county | 5-digit FIPS county id |
| climdiv | 4-character climate division id |
| valid_daterange | Valid date range (by variable) |
| * indicates defaults | |
| Code | Var Major | Description |
|---|---|---|
| maxt | 1 | Maximum temperature (°F) |
| mint | 2 | Minimum temperature (°F) |
| avgt | 43 | Average temperature (°F) |
| obst | 3 | Obs time temperature (°F) |
| pcpn | 4 | Precipitation (inches) |
| snow | 10 | Snowfall (inches) |
| snwd | 11 | Snow depth (inches) |
| 7 | Pan evap (inches) | |
| cdd | 44 | Degree days above base (CDD) (default base 65) |
| hdd | 45 | Degree days below base (HDD) (default base 65) |
| gdd | - | Growing Degree Days (base 50) |
| cddXX | - | Cooling Degree Days; where XX is base temperature |
| hddXX | - | Heating Degree Days; where XX is base temperature |
| gddXX | - | Growing Degree Days; where XX is base temperature |
Degree days can also be specified within an elems
objectwith the keys "name" (or "vX") and "base". | ||
Results from a successful StnMeta call with the output type of "json" will take the form of a JSON object with a single key -
"meta". The value associated with the "meta" key will be an array of objects - one object per station. These station objects will consist
of key/value pairs corresponding to the meta items requested (or defaults if not explicitly specified). If
valid_daterange is returned, the value will be an array of arrays. There will be one array per element requested (in the order
requested). These arrays will consist of the begin and end dates, each in the form yyyy-mm-dd (see Examples 1.2 and 1.5). If ll
is returned, it will be an array containing longitude and latitude in decimals degrees (negative values indicate west longitudes and south
latitudes). If sids is returned, it will be an array of station ids/id types for the various identifiers associated with the
station. The id type codes employed can be found in Table 1.
If an output type of "csv" is requested, the output will be one station per record with the comma-separated values: station id,
name, longitude, latitude and elevation.
Example 1.1 - no elems or dates specified; returns default metadata for all stations in Albany County, NY:
http://data.rcc-acis.org/StnMeta?county=36001
Example 1.2 - elems specified, but no dates specified; returns requested metadata for all stations in Albany County, NY reporting max and/or
min temperature at any time in their period of record:
http://data.rcc-acis.org/StnMeta?county=36001&meta=name,valid_daterange&elems=maxt,mint
Example 1.3 - elems and dates specified; returns requested metadata for all stations in Albany County, NY reporting max and/or
min temperature at any time between Jan 1 and Dec 31, 2009:
http://data.rcc-acis.org/StnMeta?county=36001&meta=name&elems=maxt,mint&sdate=2009-01-01&edate=2009-12-31
Example 1.4 - default station metadata for two stations:
http://data.rcc-acis.org/StnMeta?sids=KBWI,185718&output=csv
Example 1.5 - obtain station name, state and valid date ranges for all stations that are in both the Boston CWA and either CT or RI that
reported max or min temperature on June 21, 2011:
{"state":["CT","RI"],"cwa":"box","elems":["maxt","mint"],"date":"2011-06-21","meta":["name","state","valid_daterange"]}
The StnData web services call returns raw or summarized climate data for a single station for a range of dates.
elems specification can take the form of an array of JSON objects. The following table presents the options that are
available in these object specifications. Only name or vX is required.
| Key | Description | Example | ||||||
|---|---|---|---|---|---|---|---|---|
| name | Variable name using codes from Table 3 above. Do not specify vX or vN when specifying variables
in this way.
| maxt | ||||||
| vX | Var major or var major.minor from Table 3 above. Can be used in place of name.
| 1 or 10.4 | ||||||
| vN | Var minor. Must also specify vX when using this option. Additional documentation forthcoming.
| 4 | ||||||
| base | Base temperature for degree days (in degrees F). Used with name or vX to define base temperature
used for degree day calculations. Base temperature defaults are given in Table 3.
| 40 | ||||||
| interval | Time step of results - "dly" for daily (default), "mly" for monthly, "yly" for yearly. Can also be specified as a list.
Note: interval must be the same for all objects in an elems array.
| mly | ||||||
| duration | Duration of summarization period as specified in Table 4. | mtd | ||||||
| reduce (object) | When reduce is specified as an object, it is required to have the key reduce
and optionally add, n, and/or run_maxmissing.
| {"reduce":"max","add":"date","n":10} | ||||||
| ||||||||
| reduce (string) | As a shortcut, reduce can be specified as a string. The string contains the data summary or reduction
type from Table 5. Other optional keys available in the full reduce object cannot be used in this
abbreviated form.
| cnt_ge_90 | ||||||
| season_start | Only used with duration of "std". Start date of the season-to-date summarization.
Takes the form mm-dd or [mm,dd] for daily data or mm for monthly data.
| 06-20 | ||||||
| add | Codes from Table 7 for one or more additional pieces of information to be appended to results.
Only valid with duration of "dly".
| t,f | ||||||
| normal | NCDC 1981-2010 Normals. Valid options: 1 for the normal or "departure" for the departure from normal. Unavailable for some elements. | 1 | ||||||
| maxmissing | Integer value indicating the number of missing daily values to allow before a reduction is reported as missing. The default is unlimited. | 5 | ||||||
| prec | Integer value indicating the number of decimal places of precision displayed in the results for this element. | 3 | ||||||
| smry (object) | This can be specified as an object or array of objects. Each object is required to have the key reduce
and optionally add and/or n. If the reduce object employs the option n,
smry cannot be used.
| {"reduce":"max","add":"date","n":10} | ||||||
| ||||||||
| smry (string) | As a shortcut, smry can be specified as a string or array of strings. Each string contains a column summary
code from Table 8. Other optional keys available in the full smry object cannot be used in this abbreviated form.
If the reduce object employs the option n, smry cannot be used.
| mean | ||||||
| smry_only | Return only the summary values defined by the smry field. The JSON object returned will only have "meta" and
"smry" fields. Only valid value for this is 1. | 1 | ||||||
| groupby | Groups together days or months of data for a year. This is a list of the form ["year","mm-dd","mm-dd"], where mm-dd are the
starting and ending dates of the period to be grouped together (or they can be just mm for monthly data). A shortcut for
["year","01-01","12-31"] is simply the string "year". Results will be returned with all data between the specified group start
and end dates in a list identified by year (this year is the year associated with the last data value in the list). Dates falling
within the groupby interval, but outside of the overall date range (sdate-edate)
will be filled with missing data. This option cannot be used with an interval of "yly".
| ["year","6","8"] |
| Code | Description | Valid with interval |
|---|---|---|
| dly * | Daily data. | dly |
| mly | Monthly summary; must specify reduce. | mly |
| yly | Yearly summary; must specify reduce. | yly |
| mtd | Month-to-date summary; must specify reduce. | dly |
| ytd | Year-to-date summary; must specify reduce. | dly, mly |
| std | Season-to-date summary; must specify reduce and season_start. | dly, mly |
| integer | Length of period to be analyzed in units specified in interval | dly, mly, yly |
| * indicates default | ||
| Code | Description |
|---|---|
| max | Maximum value for the period |
| min | Minimum value for the period |
| sum | Sum of the values for the period |
| mean | Average of the values for the period |
| stdev | Standard deviation of the values (GridData only) |
| cnt_xx_yyy | Count of number of daily values passing threshold |
| pct_xx_yyy | Percent (integer) of daily values passing threshold |
| fct_xx_yyy | Fraction (float) of daily values passing threshold |
| first_xx_yyy | First occurrence of daily value passing threshold |
| last_xx_yyy | Last occurrence of daily value passing threshold |
| run_xx_yyy | Consecutive daily values passing threshold |
| xx is operator (ge, gt, le, lt, eq, ne) yyy is threshold (integer or floating point) Examples: cnt_ge_0.01, pct_eq_100 |
| Code | Description |
|---|---|
| mcnt | Count of missing values in the reduction period |
| date | Date of occurrence (for max, min, run) |
| value | Value on date of occurrence (for first and last) |
| rmcnt | Count of missing values in the run period (for run only) |
| Code | Description |
|---|---|
| f | Flags |
| t | Time of observation |
| i | Station ID associated with data |
| v | Var minor associated with data (documentation forthcoming) |
| n | Network associated with data (documentation forthcoming) |
| Code | Description |
|---|---|
| max | Maximum value for the column |
| min | Minimum value for the column |
| sum | Sum of values in the column |
| mean | Average of values in the column |
| cnt_xx_yyy | Count of number of values in column passing threshold |
| pct_xx_yyy | Percent (integer) of values in column passing threshold |
| fct_xx_yyy | Fraction (float) of values in columnn passing threshold |
| run_xx_yyy | Consecutive column values passing threshold |
| xx is operator (ge, gt, le, lt, eq, ne) yyy is threshold (integer or floating point) Examples: cnt_ge_0.01, run_le_32 |
| Key | Description |
|---|---|
| meta | Metadata items to be returned. A list of one or more of the metadata codes found in Table 2. If not specified, the default items indicated in Table 2 will be returned. |
| output | Type of output (json or csv). If not specified, default is JSON. CSV is unavailable for some requests, such as those including
meta, add, or smry. |
The results of web services calls can be returned as csv (comma separated values) or JSON objects. In both cases, missing data values are
returned as "M" and trace values of precipitation, snowfall or snow depth are returned as "T". Accumulated values will have an "A" appended
to the value (unless flags are added, in which case the "A" will appear in the flags).
Data returned as csv have the station name as the first record in the results. Subsequent records contain the values, with one record per day for daily data, one record per month for monthly data or one record per year for yearly data. The first value in each record is the date (yyyy-mm-dd for daily, yyyy-mm for monthly, yyyy for yearly) followed by the requested variables in the order specified in the request. Examples 2.1 and 2.2 below return the results in csv for daily and monthly data, respectively.
If "json" is specified as the output format, the results are returned in a JSON object. Each value specified in the
meta array is included as a name/value pair in the "meta" portion of the returned object. If meta was not specified,
the default meta values will be returned.
The data values will be returned in an array of arrays with the key "data". There will be one array per day (month or year, as specified), with the values date (yyyy-mm-dd for daily, yyyy-mm for monthly, yyyy for yearly) followed by the individual data values in the order specified in the request.
If smry was specified, the summary data will be returned as an array of values with the key "smry". If smry_only
is specified, there will be no "data" section in the results.
If the request results in an error, the error message will appear in the return for csv or in a key/value pair in JSON, with the key "error" and the error message as a string value.
Example 2.1 - Daily max and min temperature, precipitation, snowfall and snow depth for Jan 1-10, 2009:
http://data.rcc-acis.org/StnData?sid=304174&sdate=2009-01-01&edate=2009-01-10&elems=1,2,4,10,11&output=csv
Example 2.2 - Monthly highest max temperature and lowest min temperature for Jan-Dec 2008:
http://data.rcc-acis.org/StnData?sid=KCAR&sdate=2008-01&edate=2008-12&elems=mly_max_maxt,mly_min_mint&output=csv
Example 2.3 - Average daily temperature for St. Louis for June 1-30, 2012, first with time of observation and station id added,
then with precision of zero (even/odd rounding):
{"sid":"13994","sdate":"2012-6-1","edate":"2012-6-30","meta":"name","elems":[{"name":"avgt","interval":"dly","duration":"dly","add":"t,i"},{"name":"avgt","interval":"dly","duration":"dly","prec":0}]}
Example 2.4 - Monthly total precipitation for 6/1999-12/2000. First with no limit on number of missing values and second allowing no missing
data in reduction. In each case, report the number of missing values in the month.
{"sid":"302627","sdate":"1999-6","edate":"2000-12","elems":[{"name":"pcpn","interval":"mly","duration":"mly","reduce":{"reduce":"sum","add":"mcnt"}},{"name":"pcpn","interval":"mly","duration":"mly","reduce":{"reduce":"sum","add":"mcnt"},"maxmissing":0}]}
Example 2.5 - Mean monthly average temperature and departure from normal for June 1-25, 2009:
{"sid":"304174", "sdate":"2009-06-25", "edate":"2009-06-25", "meta":["name","state"], "elems":[{"name":"avgt","duration":"mtd","reduce":"mean"},{"name":"avgt","normal":"departure","duration":"mtd","reduce":"mean"}]}
Example 2.6 - Period of record maximum temperatures and date of occurrence for every day of the year:
{"sid":"304174","sdate":"por","edate":"por","meta":["name","state"],"elems":[{"name":"maxt","interval":"dly","duration":"dly","smry":{"reduce":"max","add":"date"},"smry_only":1,"groupby":"year"}]}
Example 2.7 - For each year between 1946 and 1950, find the longest run of days with min temperature <= 32 degrees between July 1 and June 30.
Add the ending date of the run, number of missing values in the entire period and number of missing values in the run to the results. Do this first
allowing no missing days in the run and second allowing up to 2 missing days in the run (notice difference in 1949 in results):
{"sid":"kfar","sdate":"1945-6-30","edate":"1950-6-30","meta":"name","elems":[{"name":"mint","interval":[1,0,0],"duration":"std","season_start":"7-1","reduce":{"reduce":"run_le_32","add":"date,mcnt,rmcnt","n":1}},{"name":"mint","interval":[1,0,0],"duration":"std","season_start":"7-1","reduce":{"reduce":"run_le_32","add":"date,mcnt,rmcnt","n":1,"run_maxmissing":2}}]}
Example 2.8 - Get the date of the last "spring" (July 1-June 30) temperature <= 28 degrees for the years 1991-2000. Also report what the
min temperature was on that date:
{"sid":"118740","sdate":"1991-6-30","edate":"2000-6-30","elems":[{"name":"mint","interval":[1,0,0],"duration":"std","season_start":"7-1","reduce":{"reduce":"last_le_28","add":"value"}}]}
The MultiStnData web services call returns data for multiple stations in an area.
| Key | Description |
|---|---|
| sdate | Start date (yyyy-mm-dd or yyyymmdd). Beginning of desired date range. Can alternatively be just a year (yyyy) or a year and month
(yyyy-mm). If used, must also specify an edate. |
| edate | End date (yyyy-mm-dd or yyyymmdd). End of desired date range. Can alternatively be just a year (yyyy) or a year and month
(yyyy-mm). If used, must also specify an sdate. |
| date | Date (yyyy-mm-dd or yyyymmdd). Can be used in place of sdate/edate, if only a single date is adequate to define your request. Can alternatively be just a year (yyyy) or a year and month (yyyy-mm). |
| elems | Elements. See the discussion of elems and elems objects in the StnData section
above. |
| In addition, one of the following keys defining the area of interest must be specified (can be a list): | |
| county | One of more county FIPS codes (e.g. 09001) |
| climdiv | One of more state/climate division identifiers (e.g. NY09) |
| cwa | One or more NWS County Warning Areas (e.g. BOI) |
| basin | One of more drainage basins (8-digit HUC) (e.g. 01080205) |
| state | One or more 2-letter state postal abbreviations (e.g. ["WA","OR"]) |
| bbox | Bounding box specified in decimal degrees (W,S,E,N) (e.g. [-90, 40, -88, 41]) |
| sids | One or more station ids as found in Table 1 (e.g.["171175","KBTV","14739"]) |
| Key | Description |
|---|---|
| meta | Metadata items to be returned. A list of one or more of the metadata codes found in Table 2. If not specified, the default items indicated in Table 2 will be returned. |
| output | Type of output (json or csv). If not specified, default is JSON. CSV is unavailable for some requests, such as those including
meta, add, smry or a range of dates. |
The results of web services calls can be returned as csv (comma separated values) or JSON objects. In both cases, missing data values
are returned as "M" and trace values of precipitation, snowfall or snow depth are returned as "T". Accumulated values will have an "A"
appended to the value (unless flags are requested, in which case the "A" will appear in the flags).
Data returned as csv have one record per station. Each record contain the meta elements sId, name, longitude, latitude, and elev followed by the requested data elements in the order specified in the request. Examples 3.1 and 3.2 below return the results in csv for a day and a month of data, respectively.
If "json" is specified as the output format, the results are returned in a JSON object. This object has the single keyword "data", which is an array of objects. Each object in the "data" array contains the results for a single station as described in the StnData results section above.
If the request results in an error, the error message will appear in the return for csv or in a key/value pair in JSON, with the key "error" and the error message as a string value.
Example 3.1:
http://data.rcc-acis.org/MultiStnData?state=CT,RI&date=2009-02-02&elems=maxt,mint&output=csv
Example 3.2:
http://data.rcc-acis.org/MultiStnData?climdiv=DE01&date=2011-8&elems=mly_mean_avgt,mly_sum_pcpn&output=csv
Example 3.3 - Monthly year-to-date precipitation departure from normal for all stations in Texas Climate Divison 1 with no missing
data for Jan-Dec 2011:
{"climdiv":"tx01","sdate":"2011-01","edate":"2011-12","meta":"name","elems":[{"name":"pcpn","interval":"mly","duration":"ytd","reduce":"sum","maxmissing":0,"normal":"departure"}]}
Example 3.4 - Annual precipitation totals for all stations in a bounding box for 2008-2010, allowing a maximum of 7 missing days in a
year. Also report number of missing days for each year and summarize these yearly values into a maximum, minimum and mean for the period:
{"bbox":"-102,48,-98,50","sdate":"2008-01","edate":"2010-12","meta":"name,state,ll","elems":[{"name":"pcpn","interval":"yly","duration":"yly","reduce":{"reduce":"sum","add":"mcnt"},"maxmissing":7,"smry":["max","min","mean"]}]}
The GridData web services call returns data (or an image) from a variety of gridded data sets.
| Key | Description |
|---|---|
| grid | Gridded data set. Code for the gridded data set of interest from Table 9. |
| sdate | Start date (yyyy-mm-dd or yyyymmdd). Beginning of desired date range. Can alternatively be just a year (yyyy) or a year and month
(yyyy-mm). If used, request must also contain edate. |
| edate | End date (yyyy-mm-dd or yyyymmdd). End of desired date range. Can alternatively be just a year (yyyy) or a year and month
(yyyy-mm). If used, request must also contain sdate. |
| date | Date (yyyy-mm-dd or yyyymmdd). Can be used in place of sdate/edate, if only a single date is adequate to define your request. Can alternatively be just a year (yyyy) or a year and month (yyyy-mm). |
| elems | Elements. See the discussion of elems and elems objects in the StnData section
above. Available options and differences from the description under StnData are presented below. |
| In addition, one of the following keys must be specified to indicate area of interest: | |
| loc | Location. Longitude and latitude in decimal degrees of a point of interest. Results will contain data for the grid point closest to this location. |
| state | State. One or more 2-letter state postal abbreviations. Results will be returned for a bounding box that encompasses all states in the array. For instance, specifying just ["ME","FL"] will return the entire East Coast. |
| bbox | Bounding box. Bounding box specified in decimal degrees (W,S,E,N) (e.g. [-90, 40, -88, 41]) |
elems specification can take the form of an array of JSON objects. The following table presents the options that are
available for use in GridData. Only name or vX is required.
| Key | Description | Example |
|---|---|---|
| name | See above. | maxt |
| vX | See above. | 1 or 10.4 |
| base | See above. | 40 |
| interval | See above. | mly |
| duration | See above. | mtd |
| reduce | In GridData, this can only be specified as a string (or an object with the single key "reduce"). The string contains the data summary or reduction type from Table 5. | cnt_ge_90 |
| season_start | See above. | 06-20 |
| Gridded normals are not available at this time. | 1 | |
| maxmissing | See above. | 3 |
| smry | In GridData, this can only be specified as a string (or an object with the single key "reduce"). Each string contains a column summary code from Table 8. | mean |
| smry_only | See above. | 1 |
| units | Set units of output data. Valid choices include: degreeF (temperature default), degreeC, degreeK, inch (precipitation default) and mm. | degreeC |
| area_reduce | Area reduction code. Grid data summarization by area as outlined in Table 10. Cannot be used when an image output is requested. | county_max |
| Code | Description | Area | Period |
|---|---|---|---|
| 1 | NRCC Interpolated | US | 1950-present |
| 3 | NRCC Hi-Res | East of Rockies | 2011-present |
| 4-16 | NARCCAP * | US | 1970-2000, 2040-2070 |
| 4: CRCM + NCEP (historical only) 5: CRCM + CCSM 6: CRCM + CGCM3 7: HRM3 + NCEP (historical only) 8: HRM3 + HadCM3 9: MM5I + NCEP (historical only) 10: MM5I + CCSM 11: RCM3 + NCEP (historical only) 12: RCM3 + CGCM3 13: RCM3 + GFDL 14: WRFG + NCEP (historical only) 15: WRFG + CCSM 16: WRFG + CGCM3 | |||
| * Be aware of idiosyncrasies before using this grid set. | |||
| Code | Description |
|---|---|
| aaaa_max | Maximum grid value in area |
| aaaa_min | Minimum grid value in area |
| aaaa_mean | Average of all grid values in the area |
| aaaa_pct_xx_yyy | Percent (integer) of area exceeding threshold |
| aaaa_fct_xx_yyy | Fraction (float) of area exceeding threshold |
| aaaa is area type ("county", "climdiv", "basin", "state") xx is operator (ge, gt, le, lt, eq, ne) yyy is threshold (integer or floating point) |
| Key | Description |
|---|---|
| meta | Metadata items to be returned. Available options are "ll" for latitude and longitude and "elev" for elevation of each grid point. |
| output | Type of output (json or image). Note that this input is case-senstieve. If not specified, default is "json". The option
"image" will return a PNG image; "json" will return a JSON object containing all the grid point data, unless an
image object is specified, in which case a PNG image will be embedded in the returned JSON object. |
| image | Map specifications. This object contains specifications for production of a PNG image. See below. |
image object. Only width or
height is required.
| Key | Description | Default |
|---|---|---|
| info_only | If only information about the map is desired, not the png image, this should be set to "1". If not specified, png image is returned in data portion of JSON object. | - |
| proj | Projection. Currently, "lcc" (Lambert conformal conic) is the only available option. | lcc |
| overlays | List of types of map overlays. Specify "state" for state borders and/or "county" for county borders. Line width and color can also be specified, separated by colons. For example, ["state:2:red","county:1:blue"]. | (no overlays) |
| interp | Type of interpolation. Options are "cspline" for cubic spline or "none" for no interpolation. | cspline |
| cmap | Color map. Definitions from mapplotlib. Note that color map names are case-sensitive. | jet |
| width | Width of png image in pixels. Only width or height should be specified - not both. Other dimension
will be scaled appropriately.
| - |
| height | Height of png image in pixels. Only width or height should be specified - not both. Other dimension
will be scaled appropriately.
| - |
| levels | Contour levels. A list of values to be used as contour levels on the map. | (selected by server) |
If the GridData request is for a single grid point, the results will look much the same as for StnData. Each value specified in the
meta array is included as a name/value pair in the "meta" portion of the returned object. The data values will be returned
in an array of arrays with the key "data". There will be one array per day (month or year, as specified), with the values date (yyyy-mm-dd
for daily, yyyy-mm for monthly, yyyy for yearly) followed by the individual data values in the order specified in the request. If
smry was specified, the summary data will be returned as an array of values with the key "smry". If smry_only
is specified, there will be no "data" section in the results. See Example 4.1.
Otherwise, if "json" is specified as the output format and there is no image object in the request, the results
are again returned in a JSON object much like in StnData. Each item specified in the request's meta array is included as a key
in the "meta" portion of the returned object. The data values are in the portion of the returned object under the key "data". If a
smry was requested, these values in the return will have the key "smry". If no areal reduction was specified (area_reduce),
instead of individual values in the "meta", "data" and "smry" portions of the results, there are arrays of arrays with each of the values
corresponding to an individual grid point. The first level of arrays can be visualized as latitude bands with each of these containing
an array of values for each longitude along the latitude band. See example 4.2.
If "json" is specified as the output format and area_reduce is specified, the result will be a JSON object
with the keys "data" and, if requested, "smry". The "data" section will be an array of arrays. Each array will contain a date and an
object containing key/value pairs representing the area id and the reduced value based on all grid points
in that area. The "smry" section will be an array of objects with the object made up of key/value pairs as in "data". See Example 4.3.
If "json" is specified as the output format and there is an image object in the request, the results will
contain a png image (a map) and information about that image. The keys in the returnded JSON object are: "levels", "cmap", "range", "size"
and "data". The value of "levels" is an array containing the contour levels used on the map. These were either specified in the call or, if
absent, determined by the GridData server. The value of "cmap" (color map) is an array of hexadecimal codes corresponding the the colors
used in the map for the various contour levels. There will be one more cmap value than level, because the first color corresponds to values less
than the first level and the last color is for values greater than the last level. The "range" is an array containing the lowest and
highest individual grid values in the area covered by the map. The "size" is an array containing the width and height of the png image in pixels.
One of these was specified in the request and the other scaled by the png creation routine. The "data" portion of the return is a base64
representation of the png image itself. See Example 4.5. If info_only is specified in the image object, the
"data" portion of the results (containing the png image) is omitted. See Example 4.4.
If "image" is specified as the output format, just the png image (with Content-Type: image/png) will be returned. See Example
4.6.
If the request results in an error, the return will be a key/value pair, with the key "error" and the error message as a string value.
Example 4.1 - For a single grid point, monthly highest maximum temperature by month for Jan-Jul 2012 and highest over the entire
period:
{"loc":"-95.36,29.76","sdate":"2012-1","edate":"2012-7","grid":"3","elems":[{"name":"maxt","interval":"mly","duration":"mly","reduce":"max","smry":"max"}]}
Example 4.2 - For the state of Delaware, retrieve August 2010 precipition total (in millimeters) for each grid point. Include latitude
and longitude of each grid point:
{"state":"de","grid":"1","meta":"ll","elems":[{"name":"pcpn","interval":"mly","duration":"mly","reduce":"sum","units":"mm"}],"date":"2010-8"}
Example 4.3 - Lowest temperature for the winter of 2011-12 (i.e. 12/1/2011-2/29/2012) for each county in Vermont:
{"state":"vt","grid":"3","output":"json","elems":[{"name":"mint","interval":[1,0,0],"duration":"std","season_start":"12-1","reduce":"min","area_reduce":"county_min"}],"date":"2012-2-29"}
Example 4.4 - Retrieve only information about a map of highest maximum temperature in Nebraska during June 2012 (no png):
{"state":"ne","grid":"1","output":"json","date":"2012-6","elems":[{"name":"maxt","interval":"mly","duration":"mly","reduce":"max"}],"image":{"info_only":1,"width":350}}
Example 4.5 - Same as Example 4.4, but this time include map specifications (overlays, contour levels) and also get png image:
{"state":"ne","grid":"1","output":"json","date":"2012-6","elems":[{"name":"maxt","interval":"mly","duration":"mly","reduce":"max"}],"image":{"proj":"lcc","overlays":["county:1:gray","state:2:purple"],"interp":"cspline","width":350,"levels":[90,95,100,105,110]}}
Example 4.6 - Same as Example 4.5, but this time extend the area through Oklahoma and retrieve just the png image:
{"state":"ne,ok","grid":"1","output":"image","date":"2012-6","elems":[{"name":"maxt","interval":"mly","duration":"mly","reduce":"max"}],"image":{"proj":"lcc","overlays":["county:1:gray","state:2:purple"],"interp":"cspline","width":350,"levels":[90,95,100,105,110]}}
The General web services calls returns metadata for a geographic area. The type of geographic area from the "Area" column in Table 11 is appended to the url after the word "General", preceeded by a slash ("/") as shown in the examples below.
| Key | Description |
|---|---|
| state | One or more two-letter state postal abbreviations. A Wikipedia map or list is available for reference. The 50 states plus territories (AS, GU, MP, PR, VI) and federal district (DC) are available. |
| id | Identification number of the area of interest. Types of identifiers for each area are found in Table 11. |
| bbox | Bounding box. A latitude/longitude bounding box defined in decimal degrees (West, South, East, North) with negative values indicating west longitude and south latitude (e.g. -90.7, 40.5, -88.9, 41.5). |
| Area | ID Type | Available Meta Codes |
|---|---|---|
| state | Postal | id, name, bbox, geojson, state |
| county | FIPS | id, name, bbox, geojson, state |
| climdiv | Divison number | id, name, bbox, geojson, state |
| cwa | NWS CWA | id, name, bbox, geojson |
| basin | 8-digit HUC | id, name, bbox, geojson |
| Key | Description |
|---|---|
| meta | A list of types of metadata to be returned. Available codes for each area type are found in Table 11. |
The results of General web services calls are returned as JSON objects with the single key "meta", which is an array of objects.
Each object in the "meta" array contains the results for a single subarea (e.g. climate division). Each item specified in the
meta array is included as a name/value pair. If meta is not specified, the name and area id will be returned.
If "geojson" is included in the meta input array, a GeoJSON object
will be included as part of the returned object with the keyword "geojson". GeoJSON is a format for encoding geographic data
structures. Example 5.3 shows how geojson will appear in the results.
Example 5.1 - Get state, name and bounding box for New York State:
http://data.rcc-acis.org/General/state?state=NY&meta=state,name,bbox
Example 5.2 - Get state, name and id for all counties in a bounding box:
http://data.rcc-acis.org/General/county?bbox=-76,41,-75,42&meta=id,name,state
Example 5.3 - Get name, id and geojson for Nebraska climate division 1:
http://data.rcc-acis.org/General/climdiv?id=NE01&meta=id,name,geojson
Example 5.4 - Get id and name of all CWAs in the state of Louisiana:
http://data.rcc-acis.org/General/cwa?state=LA&meta=id,name
Example 5.5 - Get id and name of all river basins in a bounding box:
http://data.rcc-acis.org/General/basin?bbox=-75,40,-72,42&meta=id,name
Web services calls can be made in Python using urllib and urllib2. The params object can be encoded and supplied as the
"data" arguement in the call. Here is a simple example:
import urllib, urllib2
try :
import json
except ImportError :
import simplejson as json
input_dict = {'sid':'SYRthr 9', 'sdate':'2009-01-01', 'edate':'2009-01-10', 'elems':[{'name':'maxt'}]}
params = urllib.urlencode({'params':json.dumps(input_dict)})
req = urllib2.Request('http://data.rcc-acis.org/StnData', params, {'Accept':'application/json'})
response = urllib2.urlopen(req)
print 'Results as JSON:',response.read()
Results as JSON: {"meta":{"state": "NY", "sids": ["SYRthr 9"], "uid": 32869, "name": "Syracuse Area"},
"data":[["2009-01-01","15"],
["2009-01-02","34"],
["2009-01-03","29"],
["2009-01-04","26"],
["2009-01-05","34"],
["2009-01-06","31"],
["2009-01-07","33"],
["2009-01-08","32"],
["2009-01-09","21"],
["2009-01-10","17"]]}
sids to MultiStnData options. Added evap and updated degree days specifications in Table 3.
Added base to elems object specifications. Added GridData documentation. - kle