Help for the Current Weather API

version 2017.01.06.22


Test Mode 1

The parameter 'test' by itself parrots that value back. This can be used to verify that you are able to successfully connect to the API.

Example Link:

http://parfait.snarkybox.com/current.php?test=true

What that link returns will look like this:

true


Test Mode 2

Adding the parameter 'icao' will dump the full data array converted from the XML sent by NOAA, plus parrot back a table of all the possible parameters and their current values. The values for the 'icao' parameter can be found at the NWS website. Any observing station call sign recognized by NWS and reporting data can be used. The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&test=true

What that link returns will look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet href="latest_ob.xsl" type="text/xsl"?>
<current_observation xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" xsi:noNamespaceSchemaLocation="http://www.weather.gov/view/current_observation.xsd">
  <credit>NOAA's National Weather Service</credit>
  <credit_URL>http://weather.gov/</credit_URL>
  <image>
    <url>http://weather.gov/images/xml_logo.gif</url>
    <title>NOAA's National Weather Service</title>
    <link>http://weather.gov</link>
  </image>
  <suggested_pickup>15 minutes after the hour</suggested_pickup>
  <suggested_pickup_period>60</suggested_pickup_period>
  <location>Los Angeles Intl Airport, CA</location>
  <station_id>KLAX</station_id>
  <latitude>33.94</latitude>
  <longitude>-118.4</longitude>
  <observation_time>Last Updated on Dec 27 2013, 9:53 pm PST</observation_time>
  <observation_time_rfc822>Fri, 27 Dec 2013 21:53:00 -0800</observation_time_rfc822>
  <weather>Mostly Cloudy</weather>
  <temperature_string>64.0 F (17.8 C)</temperature_string>
  <temp_f>64.0</temp_f>
  <temp_c>17.8</temp_c>
  <relative_humidity>40</relative_humidity>
  <wind_string>Calm</wind_string>
  <wind_dir>North</wind_dir>
  <wind_degrees>0</wind_degrees>
  <wind_mph>0.0</wind_mph>
  <wind_kt>0</wind_kt>
  <pressure_string>1017.9 mb</pressure_string>
  <pressure_mb>1017.9</pressure_mb>
  <pressure_in>30.07</pressure_in>
  <dewpoint_string>39.0 F (3.9 C)</dewpoint_string>
  <dewpoint_f>39.0</dewpoint_f>
  <dewpoint_c>3.9</dewpoint_c>
  <visibility_mi>10.00</visibility_mi>
  <icon_url_base>http://forecast.weather.gov/images/wtf/small/</icon_url_base>
  <two_day_history_url>http://www.weather.gov/data/obhistory/KLAX.html</two_day_history_url>
  <icon_url_name>nbkn.png</icon_url_name>
  <ob_url>http://www.weather.gov/data/METAR/KLAX.1.txt</ob_url>
  <disclaimer_url>http://weather.gov/disclaimer.html</disclaimer_url>
  <copyright_url>http://weather.gov/disclaimer.html</copyright_url>
  <privacy_policy_url>http://weather.gov/notice.html</privacy_policy_url>
</current_observation>

http://w1.weather.gov/xml/current_obs/KLAX.xml

icao datum title capsule layer test version
KLAX         true 2017.01.06.22

 


Single Datum Retrieval

Using the 'icao' and the 'datum' parameters together will retrieve a single weather element. The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

The value of 'datum' is constructed from the array dump, with a comma between each value.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&datum=current_observation,temp_f

What that link returns will look like this:

54.0


Capsule Retrieval

Using the 'icao', 'title' and the 'capsule' parameters together will retrieve an extremely brief current weather report. The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

There are two main purposes for these parameters. First is to provide a nearly display ready string for an application, in my case a weather clock that I made from a Point of Sale display unit that is only 2x20 characters. Second is to provide an extremely simple HTML web page showing the current weather. The 'title' parameter allows you set custom text you want as the title when you are creating HTML output. The 'capsule' parameter is further divided into data chunks that describe what and how you want the data displayed.

Basic Data Chunks:

Nine basic data chunks are available: Temperature, Wind Direction and Speed, Wind Chill or Heat Index, Percent Humidity, Air Pressure, Dew Point, Visibility, Spacing and New Line. The method used to create the capsule is to send a comma delimited string with the codes for each chunk, in the order that the chunks should be returned. Please see the chart below for a complete listing of the codes available. For example, if a string containing the temperature, wind, wind chill / heat index and humidity was desired, the value for the capsule parameter would be sent like this: 'capsule=t,w,f,h'. Each Basic Data Chunk is four or six characters in length, with left justification (with the exception of the Wind Direction and Speed chunk which is always center justified around the '@' symbol). The special chunk Spacing allows a section anywhere of any length. Simply repeat the code 's' as many times as desired. If you wish to include a new line in HTML format ("<br>") you can insert the data chunk 'n'.

There are a few modifiers available to give greater control. If right rather then left justification is desired, an 'r' can be added to the code for that chunk. If metric units are desired, an 'm' can be added to the code for that chunk. A nautical modifier, 'k', is available for the Wind Direction and Speed chunk which will return the speed in Knots.

BASIC
CHUNK
CODE SAMPLE LENGTH DEFAULT
UOM
METRIC
MODIFIER
METRIC
UOM
NAUTICAL
MODIFIER
NAUTICAL
UOM
RIGHT JUSTIFY
MODIFIER
Air
Pressure
p 29.9P_ 6 Inches
of Hg
m Millibars     r
Dew
Point
d 64*DP_ 6 Fahrenheit m Celsius     r
New Line n                
Percent
Humidity
h 40%_ 4 Percent         r
Spacing s _ Variable            
Temperature t 82*_ 4 Fahrenheit m Celsius     r
Visibility v 10.5V_ 6 Miles m Kilometers     r
Wind Chill or
Heat Index
f 15*WC_
81*HI_
6 Fahrenheit m Celsius     r
Wind Direction
and Speed
w NW@15_ 6 MPH m KPH k Knots  

Notes:

Extended Data Chunks:

Three extended data chunks are also available: Location, Observation Time, Weather String, Weather String Title and Icon URL Text.

There is one modifier for the Location chunk. If you add 'c', this will display the Station ID.

There are three modifiers for the Observation Time chunk. If you add 'm', this will display the Observation Time in the RFC822 format. If you add 'k', this will display the Observation Time in the format of 'Y-m-d H:i' If you add 'c', this will display the Observation Time in the format of 'h:i a T'. NOTE: These are variable width output, unlike the Basic Data Chunks.

There are six modifiers for the Weather String chunk. If you add 'c', this will display the Temperature String. If you add 'e', this will display the Wind String. If you add 'k', this will display the Pressure String. If you add 'm', this will display the Dewpoint String. If you add 'r', this will display the Relative Humidity String. If you add '|', this will display the Wind Chill or Heat Index String.

There are six modifiers for the Weather String Title chunk. If you add 'c', this will display the Temperature Title. If you add 'e', this will display the Wind Title. If you add 'k', this will display the Pressure Title. If you add 'm', this will display the Dewpoint Title. If you add 'r', this will display the Relative Humidity Title. If you add '|', this will display the Wind Chill or Heat Index Title.

There are two modifiers for the Icon URL Text chunk. If you add 'm', this will get the 'medium' sized URL. If you add 'k', this will get the 'large' sized URL.

EXTENDED
CHUNK
CODE SAMPLE FORMAT
MODIFIER
MODIFIER
RESULT
FORMAT
MODIFIER
MODIFIER
RESULT
FORMAT
MODIFIER
MODIFIER
RESULT
FORMAT
MODIFIER
MODIFIER
RESULT
FORMAT
MODIFIER
MODIFIER
RESULT
FORMAT
MODIFIER
MODIFIER
RESULT
Location l Los Angeles, Los Angeles International Airport, CA c KLAX                    
Observation
Time
o Last Updated on Feb 13 2016, 5:53 pm PST m Sat, 13 Feb 2016 17:53:00 -0800 k 2016-02-13 17:53 c 5:53 pm PST            
Weather
String
i Mostly Cloudy c 41.0 F (5.0 C) e South at 13.8 MPH (12 KT) k 1019.0 mb m 27.0 F (-2.8 C) r 43% | 16 F (-9 C)
Weather
String
Title
^ Current Observations c Temperature e Wind Speed k Pressure m Dewpoint r Relative Humidity | Wind Chill
Icon URL
Text
< http://forecast.weather.gov/images/wtf/small/few.png m http://forecast.weather.gov/images/wtf/medium/few.png k http://forecast.weather.gov/images/wtf/large/few.png                

Replace Chunks:

Because different display units like the one I used have different character encodings, the degree symbol and space character are not sent, but rather the symbols '*' and underscore are sent in their place. They will need to to be replaced by you in your application with the characters you want to actually be displayed. If, for your purposes, the characters for degree and space can be sent as a numeric HTML Entity, then you can globally replace them in the capsule output.

Use the 'y' Replace chunk to specify the numeric ASCII code you want for the degree symbol. The chunk would look like 'y176' if you wanted "&#176;" sent in the capsule wherever the degree symbol would be displayed.

Use the 'z' Replace chunk to specify the numeric ASCII code you want for the space symbol. If you want to force any spaces to be non-breaking spaces, add a modifier of 'k'. Numeric HTML Entity codes can be found here: http://ascii-code.com/

REPLACE
CHUNK
CODE SAMPLE
CHUNNK
INPUT
RESULT
OUTPUT
SPACE
MODIFIER
RESULT
OUTPUT
Degree Symbol y 82*_ y176 82&176;_    
Space Symbol z 82*_ z43 82*&43; k 82*&nbsp;

HTML Chunks:

The capsule can be further modified to create an HTML web page. You could use this on it own, maybe as a browser shortcut, or you can embed it in an iframe in your own web page as a widget. Simply use an HTML chunk of 'x'. This will create a simple HTML5 web page with a simple table. Four modifiers, 'c', 'r', 'k', 'm' and 'e' can be used with this chunk. The weather text alignment defaults to left, so adding 'r' will set it to the right. Sending 'c' will set it to be centered. The table alignment defaults to left, so adding 'e' will set it to be centered. If you don't want a full HTML web page, but only want just the table and it's contents, add the 'k' modifier. If you don't want the generated CSS style because you want to provide your own, add the 'm' modifier. Please note, if you use the 'k' or 'm' modifiers, there will be no CSS style applied to the table or image. You will need to supply that yourself.

The HTML chunk 'a' will display a header row. By default this will display the location. This chunk has four modifiers, 'r', 'c', 'm' and 'k'. Adding the modifier of 'r' will display the Station ID. Adding the modifier of 'c' will display the Observation Time. If you add 'm', this will display the Observation Time in the RFC822 format. If you add 'k', this will display the Observation Time in the format of 'Y-m-d H:i'.

The HTML chunk 'u' will allow this web page to be automatically refreshed. Add the HTML chunk of 'u' with the number of seconds: 'u300' will refresh every five minutes.

The HTML chunk 'g' will add a current conditions image. This chunk also has a position modifier. By default the image will be shown to the left of the text. If you add 'r' to the HTML chunk, then the image will be placed on the right of the text. If you want the image to be displayed at a different size, add the number of pixels to the HTML chunk. 'gr64' will display an image to the right of the text whose width and height have been set to be 64 pixels. If for some reason the image to be displayed has not been provided by NOAA, then the NOAA logo will be displayed instead.

The HTML chunk of 'b' will define the border of the table. It is a fifteen digit number consisting of five, three digit sub-numbers assigned by position. The first three are the RGB colors in decimal format, next is the number of pixels for the border size and last is the code for the style. For example: b153051255005006 will create a border style = "border-color: rgb(153,51,255); border-width: 5px; border-style: ridge;". Please see the table below for the Border Style and their code values.

The HTML chunk 'q' is used to select the color of the backgrounds for the page and table. It is a eighteen digit number consisting of six, three digit sub-numbers assigned by position. The first three numbers are the RGB colors in decimal format for the table background. The second three numbers are the RGB colors in decimal format for the page background. For example: q153204255 will set the table's style = "background-color: rgb(153,204,255);".

The HTML chunk 'j' is used to set the width of the weather text and the height of the table. It is a six digit number consisting of two, three digit sub-numbers assigned by position. These are the width and height, respectively, in decimal format. For example: j100200 will set the weather text's style = "width: 100px;" and the table's style = "height: 200px;". NOTE: Most browsers will automatically expand the table to fit it's contents. Since the width is required if you also want to set the height, any width smaller than ten is set to ten. The same goes for the height.

HTML
CHUNK
CODE RIGHT ALIGN
MODIFIER
CENTER ALIGN
MODIFIER
TABLE ONLY
MODIFIER
NO STYLE
MODIFIER
TABLE CENTER
ALIGN MODIFIER
STATION ID
MODIFIER
OBSERVATION
MODIFIER
OBSERVATION
RFC822 MODIFIER
OBSERVATION
SHORT MODIFIER
TITLE
MODIFIER
HTML
Output
x r c k m e          
Header
Row
a           r c m k e
Page
Refresh
u                    
Show
Image
g r                  
Table
Border
b                    
Table
Background
q                    
Table Size j                    

BORDER
STYLE
CODE
dotted 001
dashed 002
solid 003
double 004
groove 005
ridge 006
inset 007
outset 008

First Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&capsule=t,w,ssss,fr,hr

What that link returns will look like this:

82*_NW@5_______81*HI_40%

Second Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&capsule=i,n,t,w,n,f,hr,y176,z32,xc,ae,g60,b153051255005006,q153204255,j100001&title=My%20Weather%20Capsule

What that link returns will look like this:

KDCA Current Weather


Complete Data Retrieval, Header

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=head' will return a header information line.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&layer=head

What that link returns will look like this:

hd*ParfaitAPI*http://parfait.snarkybox.com/*current****KLAX**head*20160213*1237*2601:140:8202:cd8f:d9f9:8824:128e:eb05*2016.02.12.17~

Element Names:

hd00 hd01 hd02 hd03 hd04 hd05 hd06 hd07 hd08 hd09
layer_code API identification API URL "current" NULL NULL NULL icao parameter NULL layer parameter
token string anyURI token NULL NULL NULL token NULL token

hd10 hd11 hd12 hd13
date of request (CCYYMMDD) time of request (HHMM) Remote IP Address parfait version
token token token token

 


Complete Data Retrieval, Meta Data

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=meta' will retrieve current weather meta data.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&layer=meta

What that link returns will look like this:

mt*NOAA's National Weather Service*http://weather.gov/*15 minutes after the hour*60***http://www.weather.gov/data/obhistory/KLAX.html*http://www.weather.gov/data/METAR/KLAX.1.txt*http://weather.gov/disclaimer.html*http://weather.gov/disclaimer.html*http://weather.gov/notice.html~

Field Names:

mt00 mt01 mt02 mt03 mt04 mt05 mt06 mt07 mt08 mt09
layer_code credit credit_URL suggested_pickup suggested_pickup_period icon_url_base icon_name two_day_history_url ob_url disclaimer_url
token token anyURI token integer anyURI anyURI anyURI anyURI anyURI

mt10 mt11
copyright_url privacy_policy_url
anyURI anyURI

 


Complete Data Retrieval, Low Verbosity

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=low' will retrieve the current weather data as simply as possible

Example Link:.

http://parfait.snarkybox.com/current.php?icao=klax&layer=low

What that link returns will look like this:

lo*KLAX*Sat, 13 Feb 2016 08:53:00 -0800*Patches Fog*58.0*14.4*93*0*0.0*0*55.9*13.3*****6.00*~

Element Names:

lo00 lo01 lo02 lo03 lo04 lo05 lo06 lo07 lo08 lo09
layer_code station_id observation_time_rfc822 weather temp_f temp_c relative_humidity wind_degrees wind_mph wind_kt
token token token token decimal decimal integer integer decimal decimal

lo10 lo11 lo12 lo13 lo14 lo15 lo16 lo17
dewpoint_f dewpoint_c heat_index_f heat_index_c windchill_f windchill_c visibility_mi icon_url_name
decimal decimal integer integer integer integer decimal anyURI

 


Complete Data Retrieval, High Verbosity

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=high' will retrieve the current weather data in a semi-structured natural language format.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&layer=high

What that link returns will look like this:

hi*Los Angeles, Los Angeles International Airport, CA*Last Updated on Feb 13 2016, 8:53 am PST*Patches Fog*58.0 F (14.4 C)*93*Calm*55.9 F (13.3 C)***6.00*~

Field Names:

hi00 hi01 hi02 hi03 hi04 hi05 hi06 hi07 hi08 hi09
layer_code location observation_time weather temperature_string relative_humidity wind_string dewpoint_string heat_index_string windchill_string
token token token token token integer token token token token

hi10 hi11
visibility_mi icon_url_name
decimal anyURI

 


Complete Data Retrieval, Extra Data

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=extra' will retrieve extra current weather data.

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&layer=extra

What that link returns will look like this:

ex*33.93806*-118.38889****1019.4 mb*1019.4*30.11**~

Field Names:

ex00 ex01 ex02 ex03 ex04 ex05 ex06 ex07 ex08 ex09
layer_code latitude longitude elevation wind_gust_mph wind_gust_kt pressure_string pressure_mb pressure_in pressure_tendency_mb
token string string intger decimal decimal token decimal decimal decimal

ex10
pressure_tendency_in
decimal

 


Complete Data Retrieval, Water Data

Using the 'icao' and 'layer' parameters together will retrieve a '*' delimited, '~' line terminated segment of weather elements.  The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

'layer=water' will retrieve the current weather data as it relates to locations on or very near water.

Example Link:

http://parfait.snarkybox.com/current.php?icao=46061&layer=water

What that link returns will look like this:

wa*44.1*6.7*2.5*8.20*10*6.8*Southeast*******~

Field Names:

wa00 wa01 wa02 wa03 wa04 wa05 wa06 wa07 wa08 wa09
layer_code water_temp_f water_temp_c wave_height_m wave_height_ft dominant_period_sec average_period_sec mean_wave_dir tide_ft steepness
token decimal decimal decimal decimal integer decimal string decimal string

wa10 wa11 wa12 wa13 wa14
water_column_height surf_height_ft swell_dir swell_degrees swell_period
decimal string string integer string

 


Complete Data Retrieval, Combinations

Multiple 'layer' parameters can be sent by simply putting a comma between them: 'layer=low,extra' or layer=low,water,meta'. This results in all of the segments requested being returned in the same line, so you would first split them by a tilde. The first element of each segment is the layer_code, so inspecting the first two characters will tell you which segment you're working with. Splitting each of these segments by an asterisk will get each of the elements. The value of 'icao' for the weather observation stations can be found here: http://www.nws.noaa.gov/tg/siteloc.php.

NOTE: the order in which the layer strings occur does not affect the output order. 'layer=low,meta' will have the same result as 'layer=meta,low'. The output order is always: Header, Meta, Low, High, Extra, Water

Example Link:

http://parfait.snarkybox.com/current.php?icao=klax&layer=head,low,high,extra,water,meta

What that link returns will look like this:

hd*ParfaitAPI*http://parfait.snarkybox.com/*current****KLAX**head,low,high,extra,water,meta*20160213*1239*2601:140:8202:cd8f:d9f9:8824:128e:eb05*2016.02.12.17~mt*NOAA's National Weather Service*http://weather.gov/*15 minutes after the hour*60***http://www.weather.gov/data/obhistory/KLAX.html*http://www.weather.gov/data/METAR/KLAX.1.txt*http://weather.gov/disclaimer.html*http://weather.gov/disclaimer.html*http://weather.gov/notice.html~lo*KLAX*Sat, 13 Feb 2016 08:53:00 -0800*Patches Fog*58.0*14.4*93*0*0.0*0*55.9*13.3*****6.00*~hi*Los Angeles, Los Angeles International Airport, CA*Last Updated on Feb 13 2016, 8:53 am PST*Patches Fog*58.0 F (14.4 C)*93*Calm*55.9 F (13.3 C)***6.00*~ex*33.93806*-118.38889****1019.4 mb*1019.4*30.11**~wa**************~

 


Error Messages

Should you accidentally use the API incorrectly or if the API didn't return any data from it's source feed, you may see one of two errors.

Missing API Parameters

If the API is unhappy about not being passed the appropriate parameters, you will see this message:

er*Missing API Parameters*It appears you have tried to access the API without passing all required parameters.*http://parfait.snarkybox.com/reuters.php*http://parfait.snarkybox.com/help-reuters.php~

No Data Returned

If for some reason the source feed didn't return any data to PARFAIT, you will see this message:

er*No Data Returned*It appears that no data was returned from the feed using the parameters you entered into the API.*http://parfait.snarkybox.com/reuters.php?feed=topneews&layer=low&items=3*http://parfait.snarkybox.com/help-reuters.php~

Field Names:

er00 er01 er02 er03 er04
layer_code error description source link help file link
token string string anyURI anyURI