[[PageOutline(2-5, Table of Contents, floated)]]
= Web Services =

This page describes the web services and data provided by the main [http://www.transitionnetwork.org/ Transition Network] website and the [http://news.transitionnetwork.org/ Sharing Engine]. They include

 * '''Directory Services:''' Return directories of ContentTypes that can be used to prime or update remote caches and clients. 
 * '''News Services:''' Return news stories for a given location, radius and type.

All these services presently use simple HTTP GET requests and use segments with the URL requested to pass parameters - indeed, they are designed to be as simple as possible as use-cases and plans unfold.

== Initiative Directory Service ==

Returns a list of initiatives with their basic data and geographical coordinate information. See below for an example

==== ALL initiatives ====
 * '''Returns:''' All initiatives in in the directory - see below for format and example output.
 * '''Usage:''' To be used sparingly to prime remote cache of initiative data. Use 7 or 30 day update versions for refreshes. This view is cached for 6 hours to reduce performance impacts on the main site.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/initiatives/all
 * '''Parameters:''' None, only three variations of this view exist - 'all' and updated within 7 or 30 days versions. The last segment of the URL changes for accordingly.


==== Initiatives updated within 30 days ====

As above except:
 * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update less than 7 days in which case use the version below, or more that 30 days in which case get ALL again. View cached for 6 hours.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/initiatives/updated-month


==== Initiatives updated within 7 days ====

As above except:
 * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update is more that 7 days in which case use month variant. View cached for 1 hour.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/initiatives/updated-week


=== Returned fields & sample output ===
'''Fields:''' See ContentTypes for a full description of the fields
 * nid - node id
 * url - directory page on Transition Network.org
 * title
 * updated - timestamp in [http://www.w3.org/TR/NOTE-datetime W3C DTF]
 * initiative_community_types - multi-select option values
 * initiative_type - single-select option value
 * initiative_status - single-select option value
 * initiative_members_count_estimated - formatted number
 * websites - usually one, potentially several URLs representing the initiative 
 * contact_primary_name - formatted string
 * contact_primary_uid - user ID to be used to pull up contact pages on TN.org (thus maintaining privacy)
 * location_city, location_province_name, location_country_name - strings for the address
 * location_latitude, location_longitude - decimal coordinates representing geocoded position of imitative

'''Example output:'''
{{{
{
  "initiatives" : [
    {
      "initiative" : {
        "nid" : "23",
        "url" : "https://www.transitionnetwork.org/initiatives/totnes",
        "title" : "Totnes",
        "updated" : "2011-01-21T06:54:20+0000",
        "initiative_community_types" : {
          "1" : "Town",
          "2" : "Rural"
        },
        "initiative_type" : "Local Initiative",
        "initiative_status" : "Official",
        "initiative_members_count_estimated" : "3,300",
        "websites" : "http://totnes.transitionnetwork.org",
        "contact_primary_name" : "Lou Brown",
        "contact_primary_uid" : "3516",
        "location_city" : "Totnes",
        "location_province_name" : "Devon",
        "location_country_name" : "United Kingdom",
        "location_latitude" : "50.431213",
        "location_longitude" : "-3.685455"
      }
    },
    [... repeats ...]
  ]
}
}}}




== Project Directory Service ==

Broadly similar to the Initiative Directory Service, except returning Project data. See ContentTypes for a proper description of this.

==== ALL Projects ====
 * '''Returns:''' All projects in in the directory - see below for format and example output.
 * '''Usage:''' To be used sparingly to prime remote cache of project data. Use 7 or 30 day update versions for refreshes. This view is cached for 6 hours to reduce performance impacts on the main site.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/all
 * '''Parameters:''' None, only three variations of this view exist - 'all' and updated within 7 or 30 days versions. The last segment of the URL changes for accordingly.


==== Projects updated within 30 days ====

As above except:
 * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update less than 7 days in which case use the version below, or more that 30 days in which case get ALL again. View cached for 6 hours.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/updated-month


==== Projects updated within 7 days ====

As above except:
 * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update is more that 7 days in which case use month variant. View cached for 1 hour.
 * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/updated-week


==== Returned fields & sample output ====
'''Fields:''' See ContentTypes for a full description of the fields
 * nid - node id
 * url - directory page on Transition Network.org
 * title
 * updated - timestamp in [http://www.w3.org/TR/NOTE-datetime W3C DTF]
 * project_start_date - date formatted for display (DD MMM YYYY)
 * project_people_involved - formatted number
 * websites - usually one, potentially several URLs representing the initiative 
 * contact_primary_name - formatted string
 * contact_primary_uid - user ID to be used to pull up contact pages on TN.org (thus maintaining privacy)
 * location_city, location_province_name, location_country_name - strings for the address
 * location_latitude, location_longitude - decimal coordinates representing geocoded position of imitative

'''Example output:'''
{{{
{
  "projects" : [
    {
      "project" : {
        "nid" : "14779",
        "url" : "https://www.transitionnetwork.org/projects/newport-fruit-vegie-swap",
        "title" : "Newport Fruit & Vegie Swap",
        "updated" : "2011-01-24T12:41:14+0000",
        "project_start_date" : "14 Aug 2010",
        "project_people_involved" : "4",
        "websites" : "http://www.facebook.com/pages/Newport-fruit-and-vegie-swap/144892595545635?v=wal...",
        "contact_primary_name" : "Kate Leslie",
        "contact_primary_uid" : "3129",
        "location_city" : "Newport",
        "location_province_name" : "Victoria",
        "location_country_name" : "Australia",
        "location_latitude" : "-37.841581",
        "location_longitude" : "144.874088"
      }
    }
    [... repeats ...]
  ]
}
}}}