Package 'twfy'

Title: Drive the API for TheyWorkForYou
Description: 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. See <http://www.theyworkforyou.com> for details.
Authors: Will Lowe [aut, cre]
Maintainer: Will Lowe <[email protected]>
License: GPL-3
Version: 0.1.1
Built: 2024-11-22 03:05:32 UTC
Source: https://github.com/conjugateprior/twfy

Help Index

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

endpoint

Function name e.g. 'getConstituencies'
...

endpoint's (often optional) named 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

url

url you want to convert

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

Get constituency boundary information as KML

Description

Get constituency boundary information as KML

Usage

getBoundary(name)

Arguments

name

Name of constituency

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

start_date

Beginning date
end_date

End date
search

A search string
pid

A person identifier
page

which page of results to provide. Defaults to first page
num

Number of results to return

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

name

Name of the committee. Partial names will be matched.
date

Date for which the committee membership is required

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

date

Date for which constituency names are required
search

Search string

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

name

Name of constituency
postcode

A postcode

One of name or postcode is required.

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

type

location of the debate. Defaults to the House of Commons
date

Date on which debates are required
search

A search string
person

A person identifier to specify which speaker's contributions are required
gid

A speech/debate identifier to restrict to a particular debate
order

whether to order results by date or relevance. Defaults to date
page

which page of results to provide. Defaults to first page
num

Number of results to return

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

name

Name of constituency

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

search

A search string
person

A person identifier
order

whether to order results by date or relevance. Defaults to date
page

which page of results to provide. Defaults to first page
num

Number of results to return

Value

Search results

Get information about a Lord

Description

Get information about a Lord

Usage

getLord(id)

Arguments

id

Person identifier

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

date

ISO-style date, e.g. "1990-01-02", to compile a list of Lords for
party

Restrict list to Lords in this party
search

A search term

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

id

A MLA identifier
postcode

A postcode, which specifies a region represented by the MLA
constituency

Name of a constituency
always_return

whether to try to return an MP even if the seat is vacant or it before an election

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

date

The date for which the MLAs are required
party

Restrict MLAs to those in a party
search

A search string

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

id

An MP identifier
postcode

A postcode, used to identify a constituency and thereby an MP
constituency

Name of a constituency
always_return

whether to try to return an MP even if the seat is vacant or it before an election

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

id

An MP identifier
fields

A comma separated character vector of field names

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

date

Date for which the MP list is constructed
party

Restrict to MPs in this party
search

A search string

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(id, fields = NULL)

Arguments

id

A character vector of comma-separated MP identifiers
fields

A comma separated character vector of field names

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

id

Person identifier
postcode

A postcode, which specifies the constituency whose MSP is required
constituency

Name of a constituency
always_return

whether to try to return an MP even if the seat is vacant or it before an election

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

date

The date for which the MSPs are required
party

Restrict MSPs to those in a party
search

A search string

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

id

A person identifier

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

date

Date for which responses are required
search

A search string
person

A person identifier to specify which minister provided the answers
gid

A response identifier to return
order

whether to order results by date or relevance. Defaults to date
page

which page of results to provide. Defaults to first page
num

Number of results to return

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

date

Date for which answers are required
search

A search string
person

A person identifier to specify who provided the answers
gid

A written question and answer identifier to return
order

whether to order results by date or relevance. Defaults to date
page

which page of results to provide. Defaults to first page
num

Number of results to return

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

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

api_key

a new API key

Value

Nothing

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.