Pledges API

The pledges API was developed for the Science Museum exhibition Does flying cost the Earth?. In the exhibition, and on the exhibition's website, visitors are able to make a pledge, and also to enter some optional demographic information.

The API exposes the data generated from these pledges.

Contents

  1. Making a request
  2. Methods
    1. Pledges
    2. Participants
    3. Recent activity
  3. Usage policy

Making a request

This API follows a REST design pattern. Each type of request has its own URL, and requests should be made using the appropriate method (usually GET).

The URLs for the Pledge API all start with http://api.sciencemuseum.org.uk/pledges/.

Some methods may have optional parameters, which should be specified as a query string in the usual URL manner.

Where methods have different display formats available (eg XML or JSON), you can specify a preferred format using the HTTP Accept: header.

There is currently no need for an API key to make a request.

Methods

There are currently three methods available for the pledges API. More will be added over time.

Pledges

This method returns a list of all the available pledges, along with their unique IDs. The number of times that each pledge has been made is also shown.

The URL for this method is http://api.sciencemuseum.org.uk/pledges/pledges/. It must be called using a GET request.

Example response:

<greenflying>
   <pledges>
      <pledge id="1" pledges_made="238">I pledge to not fly at all this year.</pledge>
      <pledge id="2" pledges_made="274">I pledge to only take one flight this year.</pledge>
      ...
   </pledges>
</greenflying>

Participants

This method returns the total number of people who have made a pledge (or pledges) so far.

The URL for this method is http://api.sciencemuseum.org.uk/pledges/participants/. It must be called using a GET request.

Example response:

<greenflying>
   <participants count="811" />
</greenflying>

Recent activity

This method returns a summary of the most recently made pledges, including demographic information (if available) and which pledges each person made.

The URL for this method is http://api.sciencemuseum.org.uk/pledges/recent_activity/. It must be called using a GET request.

Example response:

<greenflying>
   <participants maximum="100" returned="100">
      <participant id="1157" participated_at="2008-05-22T14:47Z" on_gallery="1" initials="DB" country_id="24">
         <pledges_made>
            <pledge_made id="2"/>
            <pledge_made id="3"/>
         </pledges_made>
      </participant>
      <participant id="1156" participated_at="2008-05-22T13:42Z" on_gallery="1" gender="F" age="16">
         <pledges_made>
            <pledge_made id="9"/>
         </pledges_made>
      </participant>
      ...
   </participants
</greenflying>

The response format should be self explanitory, however some of the values refer to other API methods. The following table gives more details:

NodeAttributeExample valueNotes
participantsmaximum100The maximum number of participants in the results set. This can be set using the maximum=50 request parameter. The highest number allowed, and default, is 100.
participantsreturned100The actual number of participants in the results set.
participantid1151Unique id. Always returned.
participantparticipated_at2008-05-22T14:47ZThe time and date that the pledges were made. Returned in ISO 8601 format, in UTC. Always returned.
participanton_gallery1 or 0Whether the pledges were made in the exhibition space, or online. Boolean. Always returned.
participantinitialsFRThe initials of the participant. Can be one or two characters in length. Optional, returned only if supplied.
participantcountry_id25The participant's home country. The country name can be discovered using the Countries API. Optional, returned only if supplied.
participantgenderM or FThe participant's gender. M is "male", F is "female" (obviously). Optional, returned only if supplied.
participantage35The participant's age. Minimum is 1, maximum is 117 (currently the oldest person alive). Optional, returned only if supplied.
pledge_madeid5A pledge made by the participant. Multiple pledges are returned as multiple <pledge_made> elements. At least one pledge must be made by each participant. The name of the pledge referenced can be found using the Pledges method.

Usage policy

Requests should be limited to one per minute.

The data is made available on an 'as is' basis, and the Science Museum makes no guarantee of its reliability (indeed, the number of 117 year old participants suggests that people do lie!). The pledge data should not be taken as representative of Science Museum visitors or the population as a whole.