parliament-api

Typed TypeScript client for the UK Parliament APIs.

Covers three public APIs:

Members API — MPs, Lords, parties, constituencies
Questions & Statements API — Written questions, written statements, daily reports
Hansard API — Debates, divisions, contributions, search

Install

npm install parliament-api

Requires Node.js 18+ (uses native fetch).

Usage

import { ParliamentAPI, House } from 'parliament-api';

const api = new ParliamentAPI();

// Search current MPs
const mps = await api.members.search({ house: House.Commons, isCurrentMember: true });

// Get a specific member
const member = await api.members.getById(4514);
console.log(member.value.nameDisplayAs); // "Sir Keir Starmer"

// Search written questions
const questions = await api.questions.searchWrittenQuestions({
  askingMemberId: 4514,
  tabledWhenFrom: '2025-01-01',
});
console.log(questions.totalResults);
console.log(questions.results[0].value.heading);

// Search Hansard
const hansard = await api.hansard.search({
  searchTerm: 'climate change',
  house: 'Commons',
});
console.log(hansard.TotalContributions);

// Auto-paginate through all results
for await (const page of api.members.searchAll({ house: House.Commons, isCurrentMember: true })) {
  for (const mp of page) {
    console.log(mp.value.nameDisplayAs);
  }
}

Configuration

const api = new ParliamentAPI({
  concurrency: 10,  // max concurrent requests (default: 5)
  retries: 5,       // retry attempts on 429/5xx (default: 3)
  retryDelay: 2000, // base delay in ms for backoff (default: 1000)
});

You can also use individual clients directly:

import { MembersClient, QuestionsClient, HansardClient } from 'parliament-api';

const members = new MembersClient({ concurrency: 10 });
const questions = new QuestionsClient();
const hansard = new HansardClient();

API Reference

`api.members`

Method	Description
`search(params)`	Search current MPs/Lords
`searchHistorical(params)`	Search former members
`searchAll(params)`	Auto-paginating search (async generator)
`getById(id)`	Single member details
`getBiography(id)`	Career history, posts, committees
`getContact(id)`	Contact details
`getContributionSummary(id, params)`	Activity breakdown
`getEdms(id, params)`	Early Day Motions
`getExperience(id)`	Member experience
`getFocus(id)`	Policy interest areas
`getLatestElectionResult(id)`	Election result + majority
`getRegisteredInterests(id)`	Financial interests
`getStaff(id)`	Staff list
`getSynopsis(id)`	Member synopsis
`getVoting(id, params)`	Voting record
`getWrittenQuestions(id, params)`	Written questions
`getPortraitUrl(id)`	Portrait image URL
`getThumbnailUrl(id)`	Thumbnail image URL
`getGovernmentPosts()`	Government posts + holders
`getOppositionPosts()`	Opposition posts + holders
`getSpokespersons()`	Spokespersons
`getActiveParties(house)`	Active parties
`getStateOfTheParties(house, date)`	Party seat counts
`searchConstituencies(params)`	Search constituencies
`getConstituency(id)`	Constituency details
`getConstituencyElectionResults(id)`	Election results

`api.questions`

Method	Description
`searchWrittenQuestions(params)`	Search written questions
`searchAllWrittenQuestions(params)`	Auto-paginating search (async generator)
`getWrittenQuestion(id)`	Single written question
`searchWrittenStatements(params)`	Search written statements
`searchAllWrittenStatements(params)`	Auto-paginating search (async generator)
`getWrittenStatement(id)`	Single written statement
`getDailyReports(params)`	Daily report listings

`api.hansard`

Method	Description
`search(params)`	Full-text search across Hansard
`searchDebates(params)`	Search debates (paginated)
`searchDivisions(params)`	Search divisions (paginated)
`searchMembers(params)`	Search members
`getDebate(id)`	Full debate with contributions
`getDebateSpeakers(id)`	Speaker list for debate
`getDebateDivisions(id)`	Divisions in debate
`getMemberDebateContributions(id)`	Member's debate contributions

Response shapes

The Members API and Questions API wrap responses differently:

// Members API: items in PaginatedResponse
const mps = await api.members.search({ house: House.Commons });
mps.items       // MemberApiItem<Member>[]
mps.totalResults // number

// Questions API: results in QuestionsApiResponse
const qs = await api.questions.searchWrittenQuestions({ askingMemberId: 4514 });
qs.results      // MemberApiItem<WrittenQuestion>[]
qs.totalResults // number

// Individual items are wrapped in { value, links }
const member = await api.members.getById(4514);
member.value // Member
member.links // Link[]

// Hansard API: flat response with PascalCase fields
const h = await api.hansard.search({ searchTerm: 'climate' });
h.TotalContributions // number
h.Contributions      // HansardContribution[]
h.Debates            // HansardDebateSummary[]

License

MIT