Common Lisp Package: TWFY

README:

FUNCTION

Public

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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.

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.

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.

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.

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.

Private

API-COMMAND-URI (FUN)

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

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

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.

DECODE-JSON (STR)

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

MACRO

Private

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.

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.

VARIABLE

Public

*API-KEY*

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

*DECODE-RESPONSE*

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

*OUTPUT-FORMAT*

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

Private

*BASE-URI*

Root for all twfy api calls