TheyWorkForYou API

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 to get an API key.

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.

Important note: Politicians’ contact details can’t be obtained via this API. If that’s what you’re looking for, see EveryPolitician instead. APIs and datasets for other mySociety services can be found on our data portal, data.mysociety.org.

Pricing

£20 per month for 1,000 calls per month (free for charitable usage)
£50 per month for 5,000 calls
£100 per month for 10,000 calls
£300 per month for unlimited calls

In addition, we offer a 50% discount on the above rates for charitable usage. This means direct use by registered charities, or individuals pursuing a non-profit project on an unpaid basis.

Please read our full terms of usage, including licence and attribution requirements.

To use the API you need to get an API key.

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.

https://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.
json. JSON data.
js. A JavaScript object, with data in ISO-8859-1. 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)
Node (thanks to Ivan Fraixedes)
Perl (thanks to Spiros Denaxas)
PHP (thanks to Ruben Arakelyan)
Python (thanks to Paul Doran)
R (thanks to Will Lowe)
Ruby (thanks to Bruce Williams and Martin Owen)

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.)