twfy: A package for accessing TheyWorkForYou

Description

twfy is an R wrapper around the API of TheyWorkForYou, a parliamentary monitoring site that scrapes and repackages Hansard (the UK's parliamentary record) and augments it with information from the Register of Members' Interests, election results, and voting records to provide a unified source of information about UK legislators and their activities. <http://www.theyworkforyou.com> for details.

Details

twfy functions currently mirror the structure and naming scheme of the API as documented at http://theyworkforyou.com/api/. While the package attempts where possible to provide more detail on structure of the API's return values, this is not guaranteed to be correct and the link above should be your primary source of documentation.

Call the API directly

Description

All the other functions call this one - it's exported only for debugging purposes - so use them instead.

Usage

call_api(endpoint, ...)

Arguments

Details

If you're really curious about implementation, read on. Each API function introspects to see what its function name is, bundles up its named arguments, and calls this function with them. Consequently, aside from a bit of argument checking and/or return value massaging, every function is implemented exactly the same way.

Value

Response content, as unserialized by jsonlite::fromJSON

Convert URL

Description

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

Usage

convertURL(url)

Arguments

Value

A one row data.frame with columns gid and url.

Examples

## Not run: 

site <- "http://www.publications.parliament.uk"
page <- "/pa/cm201212/cmhansrd/cm120418/debtext/120418-0001.htm"
in_page <- "#12041847002086"
address <- paste0(site, page, in_page)

res <- convertURL(address)
names(res) # gid, url

## End(Not run)

Get constituency boundary information as KML

Description

Get constituency boundary information as KML

Usage

getBoundary(name)

Arguments

Value

A character vector full of KML (an XML dialect)

Get comments left on TheyWorkForYou

Description

Get comments left on TheyWorkForYou

Usage

getComments(start_date = NULL, end_date = NULL, search = NULL,
  pid = NULL, page = NULL, num = NULL)

Arguments

Value

A list containing data.frames with columns

• comment_idComment identifier

• user_idUser identifier

• epobject_id

• bodyText of comment

• posteddate and time posted

• major

• gid

• firstnameCommenter's first name

• lastnameCommenter's last name

• urlURL of the comment

• useurlURL endpoint for commenter

Get members of a Parliamentary Select Committee

Description

If name is not specified, all committees and their members are returned.

Usage

getCommittee(name = NULL, date = NULL)

Arguments

Details

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

Value

A data.frame of committee members, and also committees if name is not specified.

Get constituency names

Description

Get constituency names

Usage

getConstituencies(date = NULL, search = NULL)

Arguments

Value

a data.frame with single column name containing constituency names

Get information for a constituency

Description

Get information for a constituency

Usage

getConstituency(name = NULL, postcode = NULL)

Arguments

Value

A data.frame with columns

• nameConstituency name

• pa_idConstituency identifier

• bbc_constituency_idBBC numeric identifier

• guardian_election_resultsURL for election results

• guardian_idGuardian numeric identifier

• guardian_nameGuardian name identifier

Get information about parliamentary debates

Description

Get information about parliamentary debates

Usage

getDebates(type = c("commons", "westminsterhall", "lords", "scotland",
  "northernireland"), date = NULL, search = NULL, person = NULL,
  gid = NULL, order = c("d", "r"), page = NULL, num = NULL)

Arguments

Value

A complex data.frame of debate information. Documentation is somewhat lacking, and many columns contain data.frames so you'll have to dig around.

Return geometry information for a constituency

Description

From TheyWorkForYou: "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 meters, 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."

Usage

getGeometry(name)

Arguments

Value

A data.frame with columns

• parts number of connected parts of the constituency

• area area in square meters

• min_lat minimum latitude in the constituency

• centre_lat latitude of the central point of the constituency

• max_lat maximum latitude in the constituency

• min_long minimum longitude in the constituency

• centre_long longitude of the central point of the constituency

• max_long maximum longitude in the constituency

• srid_n

• min_e

• centre_e

• max_e

• min_n

• centre_n

• max_n

Search Hansard

Description

This needs much more documentation.

Usage

getHansard(search = NULL, person = NULL, order = c("d", "r"),
  page = NULL, num = NULL)

Arguments

Value

Search results

Get information about a Lord

Description

Get information about a Lord

Usage

getLord(id)

Arguments

Value

a data.frame with columns

• member_id Member identifier

• house Which chamber 1: The House of Commons, 2: The House of Lords.

• constituency Constituency represented

• party Party

• entered_house Date when entered the House of Lords

• left_house Date when left the House of Lords or 9999-12-31 if still in office

• entered_reason Why they entered

• left_reason Why they left

• person_id Person identifier

• lastupdate Date TheyWorkForYou updated this information

• title Title, e.g. 'Baroness'

• given_name First names

• family_name Family name

• lordofname Location associated with title

• full_name First names then family name

Get information about Lords

Description

Get information about Lords

Usage

getLords(date = NULL, party = NULL, search = NULL)

Arguments

Value

A data.frame with columns

• member_id Member identifier, dependent on position

• person_id Person identifier

• name Name of Lord

• party Party

• office NULL if no offices held, or a list with one element: a data.frame with column headings:

  • dept The committee or commission name

  • position Job role, e.g. Member or Leader,

  • from_date Date tenure in office began

  • to_date Date tenure in office ended, or 9999-12-31 if still in office

Get information on a Member of the Legislative Assembly (Northern Ireland)

Description

Get information on a Member of the Legislative Assembly (Northern Ireland)

Usage

getMLA(id = NULL, postcode = NULL, constituency = NULL,
  always_return = NULL)

Arguments

Value

a data.frame with rows representing the MLA's spells in the Assembly and columns

• member_id Member identifier for each spell in the Assembly

• house 1: House of Commons, 2: House of Lords, 3: Legislative Assembly (NI), 4: Scottish Parliament

• constituency Constituency represented

• party Party

• entered_house Date MP entered Parliament

• left_house Date MP left Parliament, or 9999-12-31 if still in place

• entered_reason Reason MP entered, e.g. general_election

• left_reason Reason MP left, e.g. general_election_standing

• person_id Person identifier

• lastupdate When TheyWorkForYou last updated this information

• title Title, if any

• given_name First name

• family_name Family name

• full_name First name and family name

• url URL path relative to TheyWorkForYou's hostname

• image URL path to jpg relative to TheyWorkForYou's hostname

• image_height Image height in pixels

• image_width Image width in pixels

Get information on Members of the Legislative Assembly (Northern Ireland)

Description

Get information on Members of the Legislative Assembly (Northern Ireland)

Usage

getMLAs(date = NULL, party = NULL, search = NULL)

Arguments

Value

A data.frame with columns

• member_id Member identifier for each spell in the Legislative Assembly

• person_id Person identifier

• name Full name of MLA

• party Party represented

• constituency Name of MLA's constituency

Get information about a Member of Parliament

Description

Returns

Usage

getMP(id = NULL, postcode = NULL, constituency = NULL,
  always_return = NULL)

Arguments

Value

a data.frame with rows representing the MP's spells in Parliament and columns

• member_id Member identifier for each spell in parliament

• house 1: House of Commons, 2: House of Lords, 3: Legislative Assembly (NI), 4: Scottish Parliament

• constituency Constituency represented

• party Party

• entered_house Date MP entered Parliament

• left_house Date MP left Parliament

• entered_reason Reason MP entered, e.g. general_election

• left_reason Reason MP left, e.g. general_election_standing

• person_id Person identifier

• lastupdate When TheyWorkForYou last updated this information

• title Title, if any

• given_name First name

• family_name Family name

• full_name First name and family name

• url URL path relative to TheyWorkForYou's hostname

• image URL path to jpg relative to TheyWorkForYou's hostname

• image_height Image height in pixels

• image_width Image width in pixels

Get more information about a Member of Parliament

Description

Unless you want all the four hundred or so fields available about an MP you should probably specify the ones you want in a comma-separated string to fields.

Usage

getMPInfo(id, fields = NULL)

Arguments

Details

Note that unlike other functions in this package the result is a list

Value

a list

Get information about Members of Parliament

Description

Get information about Members of Parliament

Usage

getMPs(date = NULL, party = NULL, search = NULL)

Arguments

Value

a data.frame with columns

• member_id Member identifier

• person_id Person identifier

• name MP's first names then family name

• party Party

• constituency Constituency represented

• office NULL if no offices held, or a list with one element: a data.frame with column headings:

  • dept The committee or commission name

  • position Role, e.g. Member,

  • from_date Date tenure in office began

  • to_date Date tenure in office ended, or 9999-12-31 if still in office

or an empty list if parliament is dissolved.

Get more information about a Member of Parliament

Description

Get more information about a Member of Parliament

Usage

getMPsInfo(ids, fields = NULL)

Arguments

Value

A list of list of MP information

Get information on a Member of the Scottish Parliament

Description

Get information on a Member of the Scottish Parliament

Usage

getMSP(id = NULL, postcode = NULL, constituency = NULL,
  always_return = NULL)

Arguments

Value

a data.frame with rows representing the MP's spells in Parliament and columns

• member_id Member identifier for each spell in parliament

• house 1: House of Commons, 2: House of Lords, 3: Legislative Assembly (NI), 4: Scottish Parliament

• constituency Constituency represented

• party Party

• entered_house Date MP entered Parliament

• left_house Date MP left Parliament, or 9999-12-31 if still in place

• entered_reason Reason MP entered, e.g. general_election

• left_reason Reason MP left, e.g. general_election_standing

• person_id Person identifier

• lastupdate When TheyWorkForYou last updated this information

• title Title, if any

• given_name First name

• family_name Family name

• full_name First name and family name

• url URL path relative to TheyWorkForYou's hostname

• image URL path to jpg relative to TheyWorkForYou's hostname

• image_height Image height in pixels

• image_width Image width in pixels

Get information about Members of the Scottish Parliament

Description

Get information about Members of the Scottish Parliament

Usage

getMSPs(date = NULL, party = NULL, search = NULL)

Arguments

Value

A data.frame with columns

• member_id Member identifier for each spell in the Scottish parliament

• person_id Person identifier

• name Full name of MSP

• party Party represented

• constituency Name of MSP's constituency

Get information about a person

Description

Get information about a person

Usage

getPerson(id)

Arguments

Value

a data.frame with rows representing the person's spells in the whatever legislative body they are members of, with columns

• member_id Member identifier for each spell in the Assembly

• house 1: House of Commons, 2: House of Lords, 3: Legislative Assembly (NI), 4: Scottish Parliament

• constituency Constituency represented

• party Party (in that spell)

• entered_house Date MP entered Parliament

• left_house Date MP left Parliament, or 9999-12-31 if still in place

• entered_reason Reason MP entered, e.g. general_election

• left_reason Reason MP left, e.g. general_election_standing

• person_id Person identifier

• lastupdate When TheyWorkForYou last updated this information

• title Title, if any

• given_name First name

• family_name Family name

• full_name First name and family name

Get written ministerial responses

Description

Get written ministerial responses

Usage

getWMS(date = NULL, search = NULL, person = NULL, gid = NULL,
  order = c("d", "r"), page = NULL, num = NULL)

Arguments

Value

A list of information about written ministerial responses

Get written answers to questions

Description

The output of this function needs documentation.

Usage

getWrans(date = NULL, search = NULL, person = NULL, gid = NULL,
  order = c("d", "r"), page = NULL, num = NULL)

Arguments

Value

A data.frame with two columns

• entry a data.frame

• subs a data.frame

. The entry data.frame has columns

• epobject_id

• htype

• gid

• hpos

• section_id

• subsection_id

• hdate

• htime

• source_url

• major

• minor

• video_status

• colnum

• body

. subs is a list containing data.frames with all the columns in entry and in addition

• excerpt

• listurl

• commentsurl

• totalcomments

• comment

Get the API key

Description

Get the current API key or request it if not present. When you provide a key it will be stored as a local environment variable TWFY_API_KEY and also in your ~/.Renviron, making it available for all subsequent R sessions.

Usage

get_api_key()

Details

API keys can be requested at http://theyworkforyou.com/api/key.

Value

The current API key

Set the API key

Description

This function manually sets or resets the API key. It is mostly useful for updating your key as all API function calls will ask for a key and store it locally and in ~/.Renviron any time they do not find one.

Usage

set_api_key(api_key)

Arguments

Value

Nothing