The twfy Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The twfy Reference Manual

This is the twfy Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:42:17 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

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.



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 twfy

Author

James Thompson <james@jamtho.com>

License

BSD-style

Description

TheyWorkForYou API bindings

Dependencies
Source

twfy.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 twfy.asd

Location

twfy.asd

Systems

twfy (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 twfy/package.lisp

Parent

twfy (system)

Location

package.lisp

Packages

twfy


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 twfy/twfy.lisp

Dependency

package.lisp (file)

Parent

twfy (system)

Location

twfy.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 twfy

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *api-key*

API key (register for one at http://www.theyworkforyou.com/api/key)

Package

twfy

Source

twfy.lisp (file)

Special Variable: *decode-response*

If set, and *output-format* is "js", API responses will be decoded from json to lisp objects with cl-json.

Package

twfy

Source

twfy.lisp (file)

Special Variable: *output-format*

Passed in the querystring to control the API response format; values can be "js", "xml", "php", or "rabx".

Package

twfy

Source

twfy.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: convert-url &key URL

Converts a parliament.uk Hansard URL into a TheyWorkForYou one, if possible.

Arguments:

- url (required)
The parliament.uk URL you wish to convert, e.g. http://www.publications.parliament.uk/pa/cm201011/cmhansrd/cm110908/debtext/110908-0002.htm#11090852001644

Package

twfy

Source

twfy.lisp (file)

Function: get-boundary &key NAME

getBoundary function

http://www.theyworkforyou.com/api/getBoundary

Returns KML file for a UK Parliament constituency.

Returns the bounding polygon of the constituency, in KML format (see mapit.mysociety.org for other formats, past constituency boundaries, and so on).

Arguments:

- name
Name of the constituency.

Package

twfy

Source

twfy.lisp (file)

Function: get-comments &key START_DATE END_DATE SEARCH PID PAGE NUM

Fetch comments left on TheyWorkForYou.

With no arguments, returns most recent comments in reverse date order.

Arguments:

- start_date, end_date (optional)
Fetch the comments between two dates (inclusive).

- search (optional)
Fetch the comments that contain this term.

- pid
Fetch the comments made on a particular person ID (MP/Lord).

- page (optional)
Page of results to return.

- num (optional)
Number of results to return.

Package

twfy

Source

twfy.lisp (file)

Function: get-committee &key NAME DATE

Fetch the members of a Select Committee.

We have no information since the 2010 general election, and information before may be inaccurate.

Arguments:

- name (optional)
Fetch the members of the committee that match this name - if more than one committee matches, return their names. If left blank, return all committee names for the date provided (or current date) in the database.

- date (optional)
Return the members of the committee as they were on this date.

Package

twfy

Source

twfy.lisp (file)

Function: get-constituencies &key DATE SEARCH

Fetch a list of UK Parliament constituencies.

Arguments:

Note only one argument can be given at present.

- date (optional)
Fetch the list of constituencies as on this date.

- search (optional)
Fetch the list of constituencies that match this search string.

Package

twfy

Source

twfy.lisp (file)

Function: get-constituency &key NAME POSTCODE

Fetch a UK Parliament constituency.

Arguments:

- name
Fetch the data associated to the constituency with this name.

- postcode
Fetch the constituency with associated information for a given postcode.

Package

twfy

Source

twfy.lisp (file)

Function: get-debates &key TYPE DATE SEARCH PERSON GID ORDER PAGE NUM

Fetch Debates.

This includes Oral Questions.

Arguments:

Note you can only supply one of the following search terms at present.

- type (required)
One of "commons", "westminsterhall", "lords", "scotland", or "northernireland".

- date
Fetch the debates for this date.

- search
Fetch the debates that contain this term.

- person
Fetch the debates by a particular person ID.

- gid
Fetch the speech or debate that matches this GID.

- order (optional, when using search or person)
d for date ordering, r for relevance ordering.

- page (optional, when using search or person)
Page of results to return.

- num (optional, when using search or person)
Number of results to return.

Package

twfy

Source

twfy.lisp (file)

Function: get-geometry &key NAME

Returns geometry information for constituencies.

This currently includes, for Great Britain, the latitude and longitude of the centre point of the bounding box of the constituency, its area in square metres, the bounding box itself and the number of parts in the polygon that makes up the constituency. For Northern Ireland, as we don’t have any better data, it only returns an approximate (estimated by eye) latitude and longitude for the constituency’s centroid.

Arguments:

- name
Name of the constituency.

Package

twfy

Source

twfy.lisp (file)

Function: get-hansard &key SEARCH PERSON ORDER PAGE NUM

Fetch all Hansard.

Arguments:

Note you can only supply one of the following at present.

- search
Fetch the data that contain this term.

- person
Fetch the data by a particular person ID.

- order (optional, when using search or person, defaults to date)
d for date ordering, r for relevance ordering, p for use by person.

- page (optional, when using search or person)
Page of results to return.

- num (optional, when using search or person)
Number of results to return.

Package

twfy

Source

twfy.lisp (file)

Function: get-lord &key ID

Fetch a particular Lord.

Arguments:

- id (optional)
If you know the person ID for the Lord you want, this will return data for that person.

Package

twfy

Source

twfy.lisp (file)

Function: get-lords &key DATE PARTY SEARCH

Fetch a list of Lords.

Arguments:

- date (optional)
Fetch the list of Lords as it was on this date. Note our from date is when the Lord is introduced in Parliament.

- party (optional)
Fetch the list of Lords from the given party.

- search (optional)
Fetch the list of Lords that match this search string in their name.

Package

twfy

Source

twfy.lisp (file)

Function: get-mla &key POSTCODE CONSTITUENCY ID

Fetch a particular MLA.

Arguments:

- postcode (optional)
Fetch the MLAs for a particular postcode.

- constituency (optional)
The name of a constituency.

- id (optional)
If you know the person ID for the member you want (returned from getMLAs or elsewhere), this will return data for that person.

Package

twfy

Source

twfy.lisp (file)

Function: get-mlas &key DATE PARTY SEARCH

Fetch a list of MLAs.

Arguments:

- date (optional)
Fetch the list of MLAs as it was on this date.

- party (optional)
Fetch the list of MLAs from the given party.

- search (optional)
Fetch the list of MLAs that match this search string in their name.

Package

twfy

Source

twfy.lisp (file)

Function: get-mp &key ID CONSTITUENCY POSTCODE ALWAYS_RETURN

Fetch a particular MP.

Arguments:

- postcode (optional)
Fetch the MP for a particular postcode (either the current one, or the most recent one, depending upon the setting of the always_return variable. This will only return their current/ most recent entry in the database, look up by ID to get full history of a person.

- constituency (optional)
The name of a constituency; we will try and work it out from whatever you give us. :) This will only return their current/ most recent entry in the database, look up by ID to get full history of a person.

- id (optional)
If you know the person ID for the member you want (returned from getMPs or elsewhere), this will return data for that person. This will return all database entries for this person, so will include previous elections, party changes, etc.

- always_return (optional)
For the postcode and constituency options, sets whether to always try and return an MP, even if the seat is currently vacant (due to e.g. the death of an MP, or the period before an election when there are no MPs).

Package

twfy

Source

twfy.lisp (file)

Function: get-mp-info &key ID FIELDS

Fetch extra information for a particular person.

Arguments:

- id
The person ID.

- fields (optional)
Which fields you want to return, comma separated (leave blank for all).

Package

twfy

Source

twfy.lisp (file)

Function: get-mps &key DATE PARTY SEARCH

Fetch a list of MPs.

Note that during the period before a general election when there are no MPs, this call will correctly return no results for a default (today) lookup.

Arguments:

- date (optional)
Fetch the list of MPs as it was on this date.

- party (optional)
Fetch the list of MPs from the given party.

- search (optional)
Fetch the list of MPs that match this search string in their name.

Package

twfy

Source

twfy.lisp (file)

Function: get-mps-info &key ID FIELDS

Fetch extra information for particular people.

Arguments:

- id
The person IDs, separated by commas.

- fields (optional)
Which fields you want to return, comma separated (leave blank for all).

Package

twfy

Source

twfy.lisp (file)

Function: get-msp &key POSTCODE CONSTITUENCY ID

Fetch a particular MSP.

Arguments:

- postcode (optional)
Fetch the MSPs for a particular postcode.

- constituency (optional)
The name of a constituency.

- id (optional)
If you know the person ID for the member you want (returned from getMSPs or elsewhere), this will return data for that person.

Package

twfy

Source

twfy.lisp (file)

Function: get-msps &key DATE PARTY SEARCH

Fetch a list of MSPs.

Arguments:

- date (optional)
Fetch the list of MSPs as it was on this date.

- party (optional)
Fetch the list of MSPs from the given party.

- search (optional)
Fetch the list of MSPs that match this search string in their name.

Package

twfy

Source

twfy.lisp (file)

Function: get-person &key ID

Fetch a particular person.

Arguments:

- id
If you know the person ID for the member you want (returned from getMPs or elsewhere), this will return data for that person. This will return all database entries for this person, so will include previous elections, party changes, etc.

Package

twfy

Source

twfy.lisp (file)

Function: get-wms &key DATE SEARCH PERSON GID ORDER PAGE NUM

Fetch Written Ministerial Statements.

Arguments:

Note you can only supply one of the following at present.

- date
Fetch the written ministerial statements for this date.

- search
Fetch the written ministerial statements that contain this term.

- person
Fetch the written ministerial statements by a particular person ID.

- gid
Fetch the written ministerial statement(s) that matches this GID.

- order (optional, when using search or person)
d for date ordering, r for relevance ordering.

- page (optional, when using search or person)
Page of results to return.

- num (optional, when using search or person)
Number of results to return.

Package

twfy

Source

twfy.lisp (file)

Function: get-wrans &key DATE SEARCH PERSON GID ORDER PAGE NUM

Fetch Written Questions/Answers.

Arguments:

Note you can only supply one of the following at present.

- date
Fetch the written answers for this date.

- search
Fetch the written answers that contain this term.

- person
Fetch the written answers by a particular person ID.

- gid
Fetch the written question/answer that matches this GID.

- order (optional, when using search or person)
d for date ordering, r for relevance ordering.

- page (optional, when using search or person)
Page of results to return.

- num (optional, when using search or person)
Number of results to return.

Package

twfy

Source

twfy.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *base-uri*

Root for all twfy api calls

Package

twfy

Source

twfy.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: alist-builder &rest SYMBOLS

Helper for DEFINE-API-COMMAND. Creates an alist of (lower-case-symbol- name-string . symbol-val) pairs, using each member of list SYMBOLS.

Package

twfy

Source

twfy.lisp (file)

Macro: define-api-command FUN-NAME API-FUN-NAME PARAMS-LIST DOCSTRING &key RETURNED-FORMAT

Defines a function FUN-NAME, calling API command (string) API-FUN-NAME, taking optional parameters symbol list PARAMS-LIST, with documentation DOCSTRING. If the API command is only able to return one format, override *OUTPUT-FORMAT* for the defined calls by setting RETURNED-FORMAT to the correct format string.

Package

twfy

Source

twfy.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: api-command-uri FUN

Returns the URI to use for (string) command FUN.

Package

twfy

Source

twfy.lisp (file)

Function: call-api FUN &optional PARAMS

Makes a GET call to the TWFY API, for function named string FUN, with arbitrary query string parameters alist PARAMS. Respects *decode-response*.

Package

twfy

Source

twfy.lisp (file)

Function: clean-alist ALIST

Helper for CALL-API. Returns a copy of ALIST with all pairs having null cdr removed, and all remaining cdr’s changed to strings.

Package

twfy

Source

twfy.lisp (file)

Function: decode-json STR

Helper for CALL-API. Decodes json string STR into symbols, using the SIMPLIFIED-CAMEL-CASE translator.

Package

twfy

Source

twfy.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, twfy.asd: The twfy<dot>asd file
File, Lisp, twfy/package.lisp: The twfy/package<dot>lisp file
File, Lisp, twfy/twfy.lisp: The twfy/twfy<dot>lisp file

L
Lisp File, twfy.asd: The twfy<dot>asd file
Lisp File, twfy/package.lisp: The twfy/package<dot>lisp file
Lisp File, twfy/twfy.lisp: The twfy/twfy<dot>lisp file

T
twfy.asd: The twfy<dot>asd file
twfy/package.lisp: The twfy/package<dot>lisp file
twfy/twfy.lisp: The twfy/twfy<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   F   G   M  
Index Entry  Section

A
alist-builder: Internal macros
api-command-uri: Internal functions

C
call-api: Internal functions
clean-alist: Internal functions
convert-url: Exported functions

D
decode-json: Internal functions
define-api-command: Internal macros

F
Function, api-command-uri: Internal functions
Function, call-api: Internal functions
Function, clean-alist: Internal functions
Function, convert-url: Exported functions
Function, decode-json: Internal functions
Function, get-boundary: Exported functions
Function, get-comments: Exported functions
Function, get-committee: Exported functions
Function, get-constituencies: Exported functions
Function, get-constituency: Exported functions
Function, get-debates: Exported functions
Function, get-geometry: Exported functions
Function, get-hansard: Exported functions
Function, get-lord: Exported functions
Function, get-lords: Exported functions
Function, get-mla: Exported functions
Function, get-mlas: Exported functions
Function, get-mp: Exported functions
Function, get-mp-info: Exported functions
Function, get-mps: Exported functions
Function, get-mps-info: Exported functions
Function, get-msp: Exported functions
Function, get-msps: Exported functions
Function, get-person: Exported functions
Function, get-wms: Exported functions
Function, get-wrans: Exported functions

G
get-boundary: Exported functions
get-comments: Exported functions
get-committee: Exported functions
get-constituencies: Exported functions
get-constituency: Exported functions
get-debates: Exported functions
get-geometry: Exported functions
get-hansard: Exported functions
get-lord: Exported functions
get-lords: Exported functions
get-mla: Exported functions
get-mlas: Exported functions
get-mp: Exported functions
get-mp-info: Exported functions
get-mps: Exported functions
get-mps-info: Exported functions
get-msp: Exported functions
get-msps: Exported functions
get-person: Exported functions
get-wms: Exported functions
get-wrans: Exported functions

M
Macro, alist-builder: Internal macros
Macro, define-api-command: Internal macros

Jump to:   A   C   D   F   G   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*api-key*: Exported special variables
*base-uri*: Internal special variables
*decode-response*: Exported special variables
*output-format*: Exported special variables

S
Special Variable, *api-key*: Exported special variables
Special Variable, *base-uri*: Internal special variables
Special Variable, *decode-response*: Exported special variables
Special Variable, *output-format*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, twfy: The twfy package

S
System, twfy: The twfy system

T
twfy: The twfy system
twfy: The twfy package

Jump to:   P   S   T