Introduction

The PARFAIT APIs are a set of web APIs that provide methods for concise weather data or RSS feed data to be imported or consumed when the raw data from the provider is larger than allowed to be imported and processed by the recipient, when the recipient can't handle the data format from the provider, or when the recipient wants some simple data already processed out.

The five APIs are: Current Weather , ESPN News , NASA News , Reuters News and Weather Forecast.

The Programmable part of the PARFAIT acronym comes form the fact that unlike most APIs which can only return their payload data with the same data elements and structure every time, the PARFAIT APIs are programmable so that the user can more precisly define what is returned from the API. This allows the API to respond with a smaller payload that more closely matches the user's needs. The size issue was especially true for Second Life (a virtual world) at the time the Current Weather API was first developed in 2010. It is assumed that since virtual worlds have many constraints around processing live external data, this will be the primary use. However, due to the ability of these APIs to preprocess and return more specific subsets of the providers data, it is expected that there will be some use in other 'real' world situations as the Internet of Things becomes a larger part of peoples lives. In Second Life I used these calls to create various weather related objects that would display live observed real world data as well as broadcast the current weather and forecast information to others in the region. I have also created a digital weather clock with live temperature and news crawls using an old 2x20 Point Of Sale display and a Raspberry Pi.

With the exception of the Current Weather Single Element request which returns a single text string, the returned data is in a multi-delimited format. All APIs except the Current API have the data divided into layer sections by the section delimiter: the pipe character '|'. Each section is then divided into layer segments by the segment delimiter: the tilde character '~'. Each segment is then divided into individual data elements by the element delimiter: the asterisk character '*'. This allows the use of layered string splits to retrieve any required piece of information. Each section is identified by the first element of the first segment, each segment is identified by it's first element, and each element is identified by it's position in the segment.

The ability to parse XML is no longer required. Also, since any element is always in the same position in the final arrays, there is no longer any need for sending both a key and it's value (as you have to with XML), shortening the size of the returned data.

Example

Calling for a 3 day forecast with with 'head', 'low and 'high' layers will return something like this:

hd*ParfaitAPI*http://parfait.snarkybox.com/*forecast*33.94*-118.4*3***head,low,high*20171015*0146*2601:140:8205:ba20:5135:4e20:e7b5:1828*2017.10.08.24~|lo*00*Tonight*http://forecast.weather.gov/newimages/medium/nskc.png*Clear*61*Minimum*Fahrenheit*0~lo*01*Sunday*http://forecast.weather.gov/newimages/medium/few.png*Sunny*91*Maximum*Fahrenheit*0~lo*02*Sunday Night*http://forecast.weather.gov/newimages/medium/nfew.png*Mostly Clear*63*Minimum*Fahrenheit*0~|hi*00*2017-10-14T22:00:00-07:00*Clear, with a low around 61. West southwest wind around 5 mph becoming northeast in the evening.~hi*01*2017-10-15T06:00:00-07:00*Sunny, with a high near 91. Northeast wind 5 to 10 mph becoming west in the afternoon.~hi*02*2017-10-15T18:00:00-07:00*Mostly clear, with a low around 63. West northwest wind 5 to 10 mph becoming north northeast in the evening.~|

This is three sections, one for each layer requested, with the sections delimited with a '|' character. By the use of a split operation, it breaks down to this:

hd*ParfaitAPI*http://parfait.snarkybox.com/*forecast*33.94*-118.4*3***head,low,high*20171015*0146*2601:140:8205:ba20:5135:4e20:e7b5:1828*2017.10.08.24~|

and

lo*00*Tonight*http://forecast.weather.gov/newimages/medium/nskc.png*Clear*61*Minimum*Fahrenheit*0~lo*01*Sunday*http://forecast.weather.gov/newimages/medium/few.png*Sunny*91*Maximum*Fahrenheit*0~lo*02*Sunday Night*http://forecast.weather.gov/newimages/medium/nfew.png*Mostly Clear*63*Minimum*Fahrenheit*0~|

and

hi*00*2017-10-14T22:00:00-07:00*Clear, with a low around 61. West southwest wind around 5 mph becoming northeast in the evening.~hi*01*2017-10-15T06:00:00-07:00*Sunny, with a high near 91. Northeast wind 5 to 10 mph becoming west in the afternoon.~hi*02*2017-10-15T18:00:00-07:00*Mostly clear, with a low around 63. West northwest wind 5 to 10 mph becoming north northeast in the evening.~|

Examining the 'lo' section, it is three segments (one for each day), with the segments delimited with a '~' character. By the use of a split operation, it breaks down to this:

lo*00*Tonight*http://forecast.weather.gov/newimages/medium/nskc.png*Clear*61*Minimum*Fahrenheit*0~

and

lo*01*Sunday*http://forecast.weather.gov/newimages/medium/few.png*Sunny*91*Maximum*Fahrenheit*0~

and

lo*02*Sunday Night*http://forecast.weather.gov/newimages/medium/nfew.png*Mostly Clear*63*Minimum*Fahrenheit*0~

From here, another split operation on each of the segments using the '*' character will allow for the selection of an individual element.

To determine which segment you want to look at you can test against the first two characters of each segment to find its identifier code. The following table shows what layers are available for each of the APIs.

layer name layer code Current Weather ESPN News NASA News Reuters News Weather Forecast
Head hd X X X X X
Metadata mt X X X X X
Other ot   X   X  
Low lo X X X X X
High hi X X X X X
Extra ex X        
Water wa X        
Hazard hz         X
Error er X X X X X