TheyWorkForYou API

Welcome to TheyWorkForYou's API section, where you can learn how to query our database for information.

Overview

  1. Get an API key.
  2. All requests are made by GETting a particular URL with a number of parameters. key is required; output is optional, and defaults to js.

http://www.theyworkforyou.com/api/function?key=key&output=output&other_variables

The current version of the API is 1.0.0. If we make changes to the API functions, we'll increase the version number and make it an argument so you can still use the old version.

Outputs

The output argument can take any of the following values:

  • xml. XML. The root element is twfy.
  • php. Serialized PHP, that can be turned back into useful information with the unserialize() command. Quite useful in Python as well, using PHPUnserialize.
  • js. A JavaScript object. You can provide a callback function with the callback variable, and then that function will be called with the data as its argument.
  • rabx. "RPC over Anything But XML".

Errors

If there's an error, either in the arguments provided or in trying to perform the request, this is returned as a top-level error string, ie. in XML it returns <twfy><error>ERROR</error></twfy>; in JS {"error":"ERROR"}; and in PHP and RABX a serialised array containing one entry with key error.

Usage and Licensing

Low volume, charitable use of the API service itself is free. This means direct use by registered charities, or individuals pursuing a non-profit project on an unpaid basis, with a volume of up to 50,000 calls per year. Please email us at commercial@mysociety.org for all other use. If you are using the API for a charitable purpose and are unsure of the likely volume please contact us in advance by emailing commercial@mysociety.org.

Parliamentary material (that's data returned from getDebates, getWrans, and getWMS) may be reused under the terms of the Open Parliament Licence. Our own data – lists of MPs, Lords, constituencies and so on – is available under the Creative Commons Attribution-ShareAlike license version 2.5.

Please credit us by linking to TheyWorkForYou with wording such as "Data service provided by TheyWorkForYou" on the page where the data is used. This attribution is optional if you've paid for use of the service.

Bindings

These help you interface with the API more easily in a particular language:

  • Ruby (thanks to Bruce Williams and Martin Owen)
  • Perl (thanks to Spiros Denaxas)
  • PHP (thanks to Ruben Arakelyan)
  • Python (thanks to Paul Doran)
  • ASP.net (thanks to Ruben Arakelyan)
  • Java (thanks to Mitch Kent)
  • Clojure (thanks to Andrew Baxter)
  • Common Lisp (thanks to James Thompson)

If anyone wishes to write bindings for the API in any language, please do so, let us know and we'll link to it here. You might want to join our public developer mailing list to discuss things.

Examples

API Functions

  • convertURL
    Converts a parliament.uk Hansard URL into a TheyWorkForYou one, if possible
  • getConstituency
    Searches for a UK Parliament constituency and returns details
  • getConstituencies
    Returns list of UK Parliament constituencies
  • getPerson
    Returns main details for a person
  • getMP
    Returns main details for an MP
  • getMPInfo
    Returns extra information for a person
  • getMPsInfo
    Returns extra information for one or more people
  • getMPs
    Returns list of MPs
  • getLord
    Returns details for a Lord
  • getLords
    Returns list of Lords
  • getMLA
    Returns details for an MLA
  • getMLAs
    Returns list of MLAs
  • getMSP
    Returns details for an MSP
  • getMSPs
    Returns list of MSPs
  • getGeometry
    Returns centre, bounding box of UK Parliament constituencies
  • getBoundary
    Returns boundary polygon of UK Parliament constituency
  • getCommittee
    Returns members of Select Committee
  • getDebates
    Returns Debates (either Commons, Westminster Hall, or Lords)
  • getWrans
    Returns Written Answers
  • getWMS
    Returns Written Ministerial Statements
  • getHansard
    Returns any of the above
  • getComments
    Returns comments
  • postComment - not written yet
    Posts a comment - needs authentication!