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:
- Drakma
- CL-JSON


Basic usage
-----------

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.


Output formats
--------------

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.


Documentation
-------------

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


Dates
-----

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.


Example session
---------------

(ql:quickload 'twfy)
(setq twfy:*api-key* "xxxxx")

(twfy:get-mps :search "cameron")

-> (((:MEMBER_ID . "40665") (:PERSON_ID . "10777") (:NAME . "David Cameron")
     (:PARTY . "Conservative") (:CONSTITUENCY . "Witney")
     (:OFFICE
      ((:DEPT . "") (:POSITION . "Prime Minister") (:FROM_DATE . "2010-05-11")
       (:TO_DATE . "9999-12-31")))))

	   
Thanks
------

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.


License
-------

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.