Help Topics

• Contact Us
• API Notices & Information
• API Arguments
• API Examples

Contact Us

Report bugs or issues at https://github.com/ncsco/api-help/issues

Questions? Email the NC State Climate Office at help@climate.ncsu.edu

API Notices and Information

• hash: User Hash Code
  Required Argument
  Unique string assigned by the State Climate Office that identifies each user. You may lookup your hash by logging in here.
  To use, add the following line to URL: &hash=
  
  
• loc: Location
  Required Argument
  Conditions to limit stations in the format "key=value1[,value2,]". Multiple key-value pairs may be joined with a semicolon (;) to require all conditions. Use double pipes (||) to act as an OR clause.
  Default value: location=LAKE
  Examples: "LAKE" OR "location=LAKE" OR "state=NC;type=ECONET"
  To use, add the following line to URL: &loc=location=LAKE
  
  
• var: Variables
  Required Argument
  Specifies the desired variables requested, seperated by commas. Go to the list of parameters
  Default value: temp2m,precip1m
  To use, add the following line to URL: &var=temp2m,precip1m
  
  
• start: Datetime Start
  Required Argument
  Start date and time of the chosen period. Valid formats follow those used for PHP's strtotime function. View the PHP date format syntax.
  Examples: "8am -1week" OR "2016-10-01"
  To use, add the following line to URL: &start=
  
  
• end: Datetime End
  Required Argument
  End date and time of the chosen period. Valid formats follow those used for PHP's strtotime function. View the PHP date format syntax.
  Examples: "now" OR "5pm" OR "2016-10-10"
  To use, add the following line to URL: &end=
  
  
• int: Time Period Interval
  Time interval (or frequency) to request the data from. Can be "any", "all", or any valid time string that follows PHP's strtotime function. View the PHP Datetime format codes.
  Default value: any
  Examples: "any" OR "all" OR "1 day" OR "12 hour" OR "1 hour"
  To use, add the following line to URL: &int=any
  
  
• obtype: Observation Type
  Limits the data to use the desired observation types. Values are in a comma delimited list. In the output, a plus sign indicates multiple obtypes were used
  Default value: D,H,O
  Options:
  • D: Daily
  • H: Hourly
  • O: Minute
  • S: Special
  Examples: "H" OR "H,S"
  To use, add the following line to URL: &obtype=D,H,O
  
  
• output: Output Format
  Format of the data output from the API.
  Default value: html
  Options:
  • chart: Chart: Web-Based Interactive Chart using Highcharts. Includes options to export graphic.
  • csv: CSV (Default: Wide): Comma delimited text output (Wide form, multiple parameters per row)
  • csv_long: CSV (Long): Comma delimited text output (Long form, one parameter per row)
  • csv_wide: CSV (Wide): Comma delimited text output (Wide form, multiple parameters per row)
  • geojson: GeoJSON: Geographical Javascript Object Notation
  • html: HTML: Web-viewable output (HTML5)
  • json: JSON: Javascript Object Notation
  • leaflet: Leaflet: A web-based map based on Leaflet. Includes map layers and a table output
  • map: Map: Web-Based Interactive Map using Highmaps. Includes options to export graphic.
  • xls: XLS: Microsoft Excel format
  To use, add the following line to URL: &output=html
  
  
• agg_int: Aggregation Period Interval (if set)
  Aggregation Time interval (or frequency) to request the data from. Can be "hour", "day", "week", "month" or "year". Note that the attributes starting with "agg_" will need to be used
  To use, add the following line to URL: &agg_int=
  
  
• agg_stat: Aggregation Period Statistic (if set, requires agg_int)
  Aggregation Statistic Used. Choose either "sum", "min", "max" or "avg"
  To use, add the following line to URL: &agg_stat=
  
  
• loc_date_limit: Limit Locations Only Within Dates
  Limit locations to only those with period of records that overlap with the user defined start and end dates ? 1=Yes, limit. 0=No, show all stations.
  Default value: no
  Your value:
  To use, add the following line to URL: &loc_date_limit=no
  
  
• type: Data Type
  Type of data is output? Either 'data' (default) or 'meta'
  Default value: data
  Options:
  • data: data
  • meta: meta
  • :
  To use, add the following line to URL: &type=data
  
  
• missing: Missing Value
  Value to assign to any missing values.
  Default value: MV
  To use, add the following line to URL: &missing=MV
  
  
• qcfail: Value Fails QC
  Value to assign to any data that fails quality control
  Default value: QCF
  To use, add the following line to URL: &qcfail=QCF
  
  
• na: Not Available
  Value to assign to any attribute that is not available
  Default value: NA
  To use, add the following line to URL: &na=NA
  
  
• na_agg: Aggregation Statistic Not Set
  Value to assign to any data that is not available due to the agg_int value being set
  Default value: NO_AGG_STAT
  To use, add the following line to URL: &na_agg=NO_AGG_STAT
  
  
• attr: Variable Attributes
  For each parameter, determine what attributes to output. Format is a comma-seperated list. Only used for CSV and HTML output.
  Default value: location,datetime,var,value,unit,location,datetime,score,paramtype,obtime,obtype,obnum,obavail,value_accum,pdstart,pdend,obmin,obmax
  Options:
  • location: Location of data
  • datetime: Datetime of observation
  • timezone: Timezone of observation
  • var: Requested Variable
  • name: Name of variable
  • value: Value of variable
  • value_accum: Accumulated value of numeric Variable over entire request (increasing with time)
  • unit: Unit of value
  • score: Quality Control score of value
  • flag: Flag of value
  • nettype: Network Type Code
  • vartype: Variable Type code
  • paramtype: Parameter Type code
  • obtype: Observation Type Code
  • obnum: Number of observations used
  • obavail: Total number of observations available in the interval period
  • agg_int: Aggregation Interval Used
  • agg_stat: Aggregation statistic used. Only valid when agg_int is set.
  • agg_num: Aggregated number of values. Only valid when agg_int is set.
  • agg_max: Aggregated maximum value of Numeric Variable.Only valid when agg_int is set.
  • agg_min: Aggregated minimum value of Numeric Variable. Only valid when agg_int is set.
  • agg_avg: Aggregated average value of Numeric Variable. Only valid when agg_int is set.
  • agg_sum: Aggregated summed value of Numeric Variable. Only valid when agg_int is set.
  • agg_accum: Aggregated accumulated value of Numeric Variable. Only valid when agg_int is set.
  • obtime: Time of observation
  • height: Height of value
  • obmin: Minimum observation datetime used in value within interval period
  • obmax: Maximum observation datetime used in value within interval period
  • pdstart: Starting observation datetime allowed in interval period
  • pdend: Ending observation datetime allowed in interval period
  • diff_sec: Difference in seconds between observation time and valid datetime
  Examples: "location,datetime,var,value,unit,score,nettype,paramtype,obtype,obsincl" OR "var,value,unit,value_accum"
  To use, add the following line to URL: &attr=location,datetime,var,value,unit,location,datetime,score,paramtype,obtime,obtype,obnum,obavail,value_accum,pdstart,pdend,obmin,obmax
  
  
• attr_delim: Attributes Delimiter
  Character to use between different attributes in a variable's output. Only used for CSV output.
  Default value: ;
  To use, add the following line to URL: &attr_delim=;
  
  
• multi_delim: Multivalue Delimiter
  Character to use between multiple values in a single value field.
  Default value: +
  To use, add the following line to URL: &multi_delim=+
  
  
• cols_delim: Column Delimiter
  Character to use between different columns in the output. Only used for CSV or HTML output.
  Default value: ,
  To use, add the following line to URL: &cols_delim=,
  
  
• rows_delim: Row Delimiter
  Character to use between different rows in the output. HTML defaults to "<br/>\n".
  Default value: \r\n
  To use, add the following line to URL: &rows_delim=\r\n
  
  
• dry_run: Dry Run Mode
  Estimate the number of data points without pulling data 1=Yes, 0=No (Default 0)
  Default value: 0
  Your value:
  To use, add the following line to URL: &dry_run=0
  
  
• metadata: Metadata Output
  Display metadata in output? True displays, false does not. Only used for CSV or HTML output.
  Default value: yes
  To use, add the following line to URL: &metadata=yes
  
  
• data_limit: Data Limit
  Restricts the data to show only the "first" or "last" datetime. Default is none (no restrictions)
  Default value: none
  Options:
  • first: first
  • last: last
  • none: none
  To use, add the following line to URL: &data_limit=none
  
  
• date_restrict: Datetime Restriction
  Restricts the output based on datetime criteria. Default is none
  Default value: none
  Options:
  • first: first
  • last: last
  • recent: recent
  • none: none
  To use, add the following line to URL: &date_restrict=none
  
  
• qclimit: Quality Control Limit
  Sets the maximum quality control (QC) score for values in the output. QC scores range from -1 (not available), 0 (good value), 1 (likely good value), 2 (likely bad value), or 3 (bad value). A quality control limit of 1 (default) includes only data with QC scores of -1, 0, and 1
  Default value: 1
  Options:
  • -1: Unavailable
  • 0: Good
  • 1: Likely Good
  • 2: Likely Bad
  • 3: Bad
  To use, add the following line to URL: &qclimit=1
  
  
• date_partial: Show Partial Datetime Periods
  Show partial datetime periods? If true, show additional interval(s) that extend (but include) your end datetime, Example: If you request data every 3 minutes 12:00 to 12:05, setting to true will show data at 12:00, 12:03, and 12:06. Setting false would only show 12:00 and 12:03. Default is False
  Default value: no
  Your value:
  To use, add the following line to URL: &date_partial=no
  
  
• order: Data Output Order
  Order of the keys of the data, or how the information will be arranged. Options are "location,datetime" (default) or "datetime,location"
  Default value: location,datetime
  Options:
  • location,datetime: location,datetime
  • datetime,location: datetime,location
  To use, add the following line to URL: &order=location,datetime
  
  
• debug: Debug Mode
  Show detailed information about the API process? 1=Yes, 0=No. Use with caution.
  Default value: no
  Your value:
  To use, add the following line to URL: &debug=no
  
  
• sql_debug: SQL Debug Mode
  Show detailed SQL information about the API SQL commands? 1=Yes, 0=No. Use with caution.
  Default value: 0
  Your value:
  To use, add the following line to URL: &sql_debug=0
  
  
• timefmt: Time Format
  Output time format. Valid formats follow those used for PHP's Supported Date Formats. View the PHP Datetime format codes.
  Default value: auto
  To use, add the following line to URL: &timefmt=auto
  
  
• timezone: Timezone
  Timezone to output the data in. Valid formats follow those used for MySQL's Supported Timezones.
  Default value: US/Eastern
  Options:
  • US/Alaska: US/Alaska
  • US/Central: US/Central
  • US/Eastern: US/Eastern
  • US/Hawaii: US/Hawaii
  • US/Mountain: US/Mountain
  • US/Pacific: US/Pacific
  • UTC: UTC
  To use, add the following line to URL: &timezone=US/Eastern
  
  
• info_start: Information Line Prepend
  Character to use to start every line of information output, not include data or metadata. Only used for CSV or HTML output.
  Default value: ##
  To use, add the following line to URL: &info_start=##
  
  
• metadata_start: Metadata Line Prepend
  Character to use to start every line of metadata output. Only used for CSV or HTML output.
  Default value: ##
  To use, add the following line to URL: &metadata_start=##
  
  
• outfile: Output File Name
  Filename of the output.
  To use, add the following line to URL: &outfile=
  
  
• map_height: Map Height
  Height (in pixels) of map output. Only used when map is the output format.
  Default value: 550px
  To use, add the following line to URL: &map_height=550px
  
  
• map_width: Map Width
  Width (in pixels) of map output. Only used when map is the output format.
  Default value: 1500px
  To use, add the following line to URL: &map_width=1500px
  
  
• map_var: Variable on Map
  Labels each point on a map with the chosen variable (Defaults to location ID). Only used when map is the output format. Go to the list of parameters
  Default value: location
  To use, add the following line to URL: &map_var=location
  
  

API Examples