Prelude Interactive

See Part 1 if you need some background.  This part is more for web nerds, or people who aren’t afraid of learning some of our arcane rituals and glyphs.

I’m going to assume you’re familiar with and have used REST APIs in the past.  If not, I’m going to make a wild stab at an explanation.  An API is an Application Programming Interface:  An interface to a computer system that you can access using another computer system if you use some rules.  In particular, these “RESTful” APIs use “the web” or HTTP protocol as their interface.  This is a good choice because HTTP is nearly ubiquitous.  The rules are usually what variables and values to put in the URL; for example

http://sites.com/api/?searchTerm=stuff&resultsLimit=50%sortBy=date

The variables are after ? and &, and their corresponding value is after the = sign.  When you request a URL like that, it will return some stuff:  Sometimes a webpage, sometimes an RSS feed, sometimes another format.  The are generally widely accepted ones for which there are already existing tools and code libraries, like RSS, ATOM, RTF, etc.   In this case, they return volunteer opportunities and other ways to give time, money or effort.

Once you have decided to make an API, the rules and formats you choose are critically important.  Do they accurately describe what you are trying to do?  Are they easy to use?  Do they give people the data they need to make useful programs?  Are they well documented?  New formats need to become widely adopted to be useful.  That is a huge challenge.

The rest of this post attempts to compare the formats of Social Actions and All For Good at a high level.

Social Actions

Social Actions currently has two formats published for different purposes.

Search API

The first is their search API, documented thus:

http://www.socialactions.com/developers/api

The parameters are fairly simple, allowing you to filter by search terms, action types, action sources, and how recent they are.  I think the search logic around “all or any” and “excluded action sources” could be a little cleaner, or maybe incorporate a cool search term parser that would let you “group some terms” together and -filter -others.  You know what though?  In these cases it’s often better to give developers fewer tools and keep it simple.  We used the API to make Social Actions Tuner and had no complaints.

The API returns, for each action:  title, description, site & url, action type, location, and the date created.  The descriptions can be quite long, in some cases, and the location data (last time I checked) can be messy and unreliable.  This brings up an important point for later exploration:  What can either aggregator can do about the quality of the data passing through their systems?

Open Actions

Open Actions attempts to give nonprofits/NGOs a simple, universal way to publish their needs.  Open Actions content can be pulled in to the Social Actions API (or All For Good’s, in theory), can be understood by an appropriately endowed web spider, and can be easily updated at the source.  An example of this would be a donation drive:  the open actions article would describe the cause, the need, tax/501c info, as well as their progress towards the goal.

You know how RSS/ATOM make it really easy to publish a “feed” that various services on the web (Google Reader, Technorati, etc) can consume?  That is what Open Actions wants to do for donations, volunteer opportunities, and other types of actions.  As far as I know it was the first format of its kind to be published, and a great first step.

Update:  They reminded me about the Open Actions Wiki, and in particular the Brainstorming page where new fields are planned.

All For Good

Google guy Adam Sah sent me a key to the All For Good API a few days ago, and I ran some sample queries and read through their documentation.

Search API

This document describes how to search for and retrieve things:

http://www.allforgood.org/docs/api.html

The parameters you can use to filter the results are similar to those of the Social Actions API.  All For Good additionally has date/time and location filters – hopefully they are doing a good job extracting that information from their sources.  Social Actions additionally can filter by action type (because AFG is focused on only volunteer opportunities).  There are a few other minor differences, but nothing to write home about.

Search Results Format & Elements (Footprint)

In order to view the HTML documentation for this, I clicked a link in the Elements section, then clicked another one thinking I’d get rendered HTML, then finally saved the file to my desktop and re-opened it.  This is way too cumbersome!  Maybe I missed something, but nevertheless sent them some feedback.

Once you can actually view it, the documentation describes a well designed, sophisticated XML schema composed of four major stand-alone objects:  FeedInfo, Organization, VolunteerOpportunity, and Review.  These can interlink, and allow for the construction of complex, meaningful, and useful structures that very thoroughly describe the state of a volunteer opportunity.  The results that are actually returned to you by the API aren’t exactly in the same format, and it isn’t entirely clear whether the data sources deliver their data in this format, or what rules govern the translation.

Compared to Social Actions’ Open Actions format, the Footprint XML format is much more substantial.

• I like that EIN and Guidestar IDs are present. These are United States centric, but they can be ignored and other ID systems can be substituted.
• I think that describing the relationship between the (potentially) several different organizations involved in an opportunity is interesting.
• “volunteersNeeded” and “rsvpCount” are similar to Social Actions’ “type”, “amount”, “completed”, “numberOfContributors”; if used, these allow the sources to do a better job keeping would-be volunteers updated.
• The “audienceTags” and “categoryTags” sections are a great leap forward in matching people to actions, rather than always matching actions to people.
• Ratings – fantastic!   Or is it?  This has some significant implications for the volunteer manager.

Synopsis

Please note this is just a first pass.  I have not dug deeply into either Open Actions or Footprint, nor have I built any apps using them.

• The Social Actions and All For Good search APIs are roughly equivalent.  Social Actions is about more than just volunteering, and All For Good offers a better way to filter for relevant actions by time range.
• Both Open Actions and Footprint aim to help organizations publish and maintain structured data.  Footprint is far more complex and powerful.
• The search APIs are barely accessible to someone who is not a web programmer.  Open Actions and especially Footprint are probably very difficult to wrap your head around if you aren’t technical – this creates a huge opportunity to make better tools for the non-technical volunteer manager.  Better, clearer, simpler documentation must be created for different audiences.
• These formats are exciting to #nptech nerds, but probably nobody else.  They have a long way to go towards adoption.
• These efforts alone are not going to change the world, and finding volunteers is only one small part of the challenge.