legco: R bindings for the Hong Kong Legislative Council API

Provides functions to fetch data from the Hong Kong Legislative Council API.

Details

Most functions of this package correspond to the data endpoints of the API. It is therefore necessary to understand the structure of the API in order to extract the data needed. Please refer to the vignettes for more details.

This package supports five databases of the LegCo API: Bills, Hansard, Meeting Attendance, Meeting Schedule and Voting Result. It is essential to understand what data these databases store in order to utilise the API effectively. Please refer to the vignettes and the API documentations for more details (links in ‘See Also’).

API Limits

The LegCo API does not have a specified rate limit, but by experience the limit is approximately 1000 requests per IP per hour. When the rate limit is reached, the server will return an empty json.

LegCo's API server also has a node count limit of 100 nodes per request, which can be translated as 20 filtering conditions per request in most cases in meaningful term. This package automatically blocks requests that exceed the node count.

It is common for the connection to the LegCo API to experience SSL error from time to time, especially during repeated requests. This can usually be resolved simply by retrying. This package automatically retries the request once when an SSL error occurs.

Another common problem is that the LegCo API sometimes returns an empty json file when it is not supposed to. Again, this can usually be resolved by retrying. This package automatically retries the request once to make sure that an invalid search query or rate limit is not the cause of the problem.

Functions

Generic function:

legco_api: Generic LegCo API

Functions of the Bills database:

all_bills: All Bills discussed in LegCo

Functions of the Meeting Attendance Database:

attendance: Attendance of members

Functions of the Voting Result Database:

voting_record: Voting record in LegCo meetings

Functions of the Hansard database:

hansard: Hansard files
legco_section_type: Section code
subjects: Subjects speakers: Speakers in the council, including members, government officials and secretariat staff
rundown: Rundown (Paragraphs in hansard)
questions: Questions raised by members
bills: Bills
motions: Motions
petitions: Petitions
addresses: Addresses made by members or government officials when presenting papers to the Council
statements: Statements made by government officials
voting_results: Results of votes in council meetings
summoning_bells: Instances of summoning bells being rung

Functions of the Meeting Schedule Database:

term: LegCo terms
session: LegCo sessions
committee: LegCo committees
membership: Membership of LegCo committees
member: LegCo members
member_term: Terms served by LegCo members
meeting: Meetings of LegCo committees
meeting_committee: Committees of LegCo meetings

Complementary Functions:

search_committee: Search LegCo committees
search_member: Search LegCo members
search_voting_record: Search Voting Record in LegCo meetings
search_question: Search full text of question put to the government by LegCo members

Notes

In addition to the standard function names, each function in this package has a wrapper where the name is prefixed with legco_. For example, both speakers() and legco_speakers() will return the same result. This is because function names are taken from the data endpoints provided by the API on, which nonetheless are often not very informative and could clash with functions in other packages (e.g. speakers() is not a term unique to LegCo).

Disclaimer

This package is not officially related to or endorsed by the Legislative Council of Hong Kong.

The Legislative Council of Hong Kong is the copyright owner of data retrieved from its open data API.

Author

Elgar Teo (elgarteo@connect.hku.hk)