PARFAIT Logo

PARFAIT APIs

Programmable APIs Reducing Feeds And Information Threads
version 2017.10.08.24

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 size issue was especially true for Second Life (a virtual world) at the time the Current API was first developed in 2011. 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 Datum and Capsule requests which return 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 or JSON 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 or JSON), 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. The full specification for the data returned by each of the different layers is fully explained in the help files (help-current.php, help-forecast.php, help-reuters.php, help-nasa.php and help-espn.php).

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 API Forecast API ReutersAPI NASA API ESPN API
head hd X X X X X
meta 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

 

More Information

To learn how to retrieve Current weather observations, refer to the documentation here: help-current.php.

To learn how to retrieve ESPN news feeds, refer to the documentation here: help-espn.php.

To learn how to retrieve weather Forecast information, refer to the documentation here: help-forecast.php.

To learn how to retrieve NASA news feeds, refer to the documentation here: help-nasa.php.

To learn how to retrieve Reuters news feeds, refer to the documentation here: help-reuters.php.

For more information or assistance with this website, please e-mail me: Mike@OmegaTower.com.

The ESPN news feeds are courtesy of ESPN.
The NASA news feeds are courtesy of NASA.
The weather data is courtesy of NOAA's National Weather Service.
The Reuters news feeds are courtesy of Reuters.com.

 

Version Notes

2017.10.08.24

2017.10.07.23

2017.01.06.22

2016.11.10.21

2016.10.30.20

2016.03.19.19

2016.03.09.18

2016.02.12.17

2015.07.28.16

2015.07.23.15

2015.04.08.14

2014.12.10.13

2014.11.16.12

2014.11.15.11

2014.11.08.10

2014.11.05.09

2013.12.29.08

2013.12.28.07

2013.09.27.06

2013.09.25.05

2013.09.11.04

2013.09.08.03

2013.09.06.02

2013.08.14.01