Social Actions Open API

This is here with the intent to do a first pass description of some basic API features. In particular it should describe the features that are necessary to implement the first round of Social Actions Labs applications.

Search JSON API

REST requests for search results in JSON format are submitted to http://search.socialactions.com/actions.json. Available parameters are:

• q – (required) the search query
• DEPRECATED action_type – currently one of “Affinity Group”, “Group Fundraiser”, “Micro-credit Loan”, “Petition”, or “Pledged Action”. Default is to not filter based on action type.
• action_types – a comma separated list of action_type ids desired in the search results. Default is to show all types in the results. The following ids map to the following action types:
  • 1 = Group Fundraiser
  • 2 = Campaign
  • 3 = Pledged Action
  • 4 = Event
  • 5 = Affinity Group
  • 6 = Volunteer
  • 7 = Micro-credit Loan
  • 8 = Petition
• exclude_action_types – a comma separated list of action_type ids that are not desired in the search results. Default is to show all types in the results. See list above for id to action_type mapping. WARNING: you can not specify exclude_action_types and action_types in the same request, this will result in a 400 status (bad request) error.
• created – return results creaed in the last created days. legal values are [30 14 7 2 1 all]. “all” means do not filter based on date created. Default is 7.
• sites – comma separated list of aggregated site IDs to return results for. Currently the best way to get the ID is to look at the values for the sites[] field on the advanced search form on search.socialactions.com. (currently this is a database ID - it could be good to consider whether we should expose this implementation detail) Default is to not filter based on site.
• match – legal values “any” or “all”. Whether to return results which match all the terms in the search query or results which match any of the terms. Default: all
• limit – number of results to return. Default: 10
• order – how to order the results. Initial legal values are “relevance” and “created_at”. Default: relevance.

An example request URL might look like:
http://search.socialactions.com/actions.json?q=burma&created=7&sites=104...

Results are returned as JSON with the following fields:

• “title” – title of the action
• “description” – description of the action. Currently can include HTML - we should discuss normalizing this field.
• “site” – a hash containing keys (“name” and “url”) and values which contain info about the site this action came from
• “url” – Source URL of the action on the source site
• DEPRECATED “action_type” – type of action as described above
• “action_type” – a hash containing keys (“name” and “id”) designating the action_type and its corresponding id
• “location” – free-form text location of the action (we’ll want to formalize this better as the micro-format comes together)
  “created_at” – Timestamp this item was published if available. Otherwise the timestamp it was first aggregated. Format: “2008/08/01 16:26:04 -0400”

Obviously we’ll be adding many more fields here soon, but it doesn’t make sense to go into too much detail before the micro-format firms up some more. There are already discrepancies between this format and the fields described in the initial micro-format documents which we should be aware of (and will need to fix).