TheyWorkForYou

Menu

TheyWorkForYou API

Overview

Welcome to TheyWorkForYou's API section. The API (Application Programming Interface) is a way of querying our database for information.

To use the API you need an API key, and you may need a license from us.

The documentation for each individual API function is linked from this page: you can read what each function does, and test it out, without needing an API key or to write any code.

Terms of usage

Low volume, charitable use of the API 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. All other use requires a licence, as a contribution towards the costs of providing this service. Please email us at enquiries@mysociety.org if your usage is likely to fall into the non-free bracket: unlicensed users may be blocked without warning.

Pricing

£500 per year for up to 50,000 calls (free for charitable usage)
£1,000 per year for up to 100,000 calls
£2,000 per year for up to 200,000 calls
£2,500 per year for up to 300,000 calls
£3,000 per year for up to 500,000 calls

In addition, we offer a 50% discount on the above rates for charitable usage.

Credits

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.

Technical documentation

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.

Bindings

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

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

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 mailing list to discuss things.

Example

  • Hansard prettifier - drag this bookmarklet to your bookmarks bar, or bookmark it. Then if you ever find yourself on the official site, clicking this will try and take you to the equivalent page on TheyWorkForYou. (Tested in IE, Firefox, Opera.)

API Functions