TheyWorkForYou - Common Lisp bindings
Common Lisp bindings for the TheyWorkForYou API (UK political data).
These are really just for my use at the moment, so have a few rough edges.
Official API docs are here: http://www.theyworkforyou.com/api/
System depends on:
Each API command has a corresponding exported function, taking as keyword
parameters the API command's querystring parameters. The name mapping is
pretty obvious: getMP -> get-mp, getMPsInfo -> get-mps-info, etc.
Note that some arguments are required by the API, but the code here doesn't
force their inclusion, so the first error is seen in the API response.
TODO: raise an error locally, and don't send the request.
Set *API-KEY* to your personal key before making requests - you can
register for one here: http://www.theyworkforyou.com/api/key.
TWFY lets you request output in a variety of formats: js, xml, php, rabx.
Change *OUTPUT-FORMAT* (string) to set this. By default you just get a
string containing the response, however...
If set to "js" (the default), setting *DECODE-RESPONSE* to non-null (T by
default) will have the response parsed to native Lisp structures with CL-JSON.
Symbol naming is done with CL-JSON:SIMPLIFIED-CAMEL-CASE-TO-LISP.
TODO: similar parsing for xml.
None of this applies to the function GET-BOUNDARY, which always returns kml
as a string.
The raw _Web_ documentation is stored in these functions' docstrings. As said
above, there's a direct correspondence between API and keyword params, so
it's perfectly usable.
Docs source: http://www.theyworkforyou.com/api/ (again).
Currently, all dates have to be expressed as a string, as are parsed on the
server: "YYYY-MM-DD" seems the right way.
TODO: Come up with a better system.
(setq twfy:*api-key* "xxxxx")
(twfy:get-mps :search "cameron")
-> (((:MEMBER_ID . "40665") (:PERSON_ID . "10777") (:NAME . "David Cameron")
(:PARTY . "Conservative") (:CONSTITUENCY . "Witney")
((:DEPT . "") (:POSITION . "Prime Minister") (:FROM_DATE . "2010-05-11")
(:TO_DATE . "9999-12-31")))))
Obviously thanks to mySociety for building and running TheyWorkForYou
(source: https://github.com/mysociety/theyworkforyou), which is great.
Also to Andrew Baxter (rhinocratic) for writing Clojure bindings; doubtless
reading his first made the job of writing these much easier.
All code is under the MIT license.
The API documentation inside calls to DEFINE-API-COMMAND is derived from
TheyWorkForYou code, which is licensed under the following terms:
Copyright (c) 2003-2004, FaxYourMP Ltd where not otherwise marked
Copyright (c) 2003-2004, various as marked in individual files
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of FaxYourMP Ltd nor the names of its contributors nor
the name TheyWorkForYou may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.