General

Introduction

This document sets out how to access and use the API that has been created as part of LDAPP for the Lawmaker application.

The API gives access to documents that are held in the PDR (public document repository) within Lawmaker. 

The API currently gives access to:

• Scottish Bills that have been marked as "published".

• Scottish Acts that have been marked as "submitted to TNA".

• Amendment lists for Scottish Bills that have been marked as "published".

• UK Bills that have been marked as "published".

• UK Acts that have been marked as "submitted to TNA".

• UK Amendments lists that have been marked as "published".

• Individual amendments to Scottish and UK Bills that were in a published amendment list or have been marked for publication separately.

• SIs and SSIs that have been marked as "submitted to TNA".

Documentation

Following the link above for Staging in a browser will give you access to the Swagger documentation for the API endpoints that have been implemented.

The relevant APIs are "LDAPP: Published Document Repository" and "session".

Access to the Swagger documentation requires a separate username and password from your user account. The password will be periodically updated.

Documentation on the modelling of the XML documents can be found here: https://ldapp.teratext.leidos.com.au/doku.php?id=modelling

Accessing the API

The API is accessible at {baseURL}/pdr, i.e.:

• Staging - https://lawmaker.staging.legislation.gov.uk/pdr

• Production - https://lawmaker.legislation.gov.uk/pdr

Access to the api on Production is limited by an IP allow list.

All requests must be made by authenticated users. Contact Lawmaker support if you require access.

Before the api can be accessed programmatically using a new api user account, you will need to access the hosted UI to change the temporary password.

To access the hosted UI use the following links:

• Staging environment - https://lawmaker-test-pdr.auth.eu-west-1.amazoncognito.com/login?client_id=70l4pd50m318e2t7uqirmqk74f&response_type=code&scope=email+openid+phone+profile&redirect_uri=https://lawmaker.staging.legislation.gov.uk/pdr

• Prod environment - https://lawmaker-pdr.auth.eu-west-1.amazoncognito.com/login?client_id=54i2s1m3ls8ffmjg6dcv8bjpsu&response_type=code&scope=email+openid+phone+profile&redirect_uri=https://lawmaker.legislation.gov.uk/pdr

Document permissions

Access to specific documents on the PDR is restricted by group membership. An api user will only be able to obtain a document or get a query response including metadata about a document if the user belongs to the group matching the organisation that published the document. For example, an api user must be a member of the HoC and HoL groups to be able to view all documents published by the UK Parliament. 

Access to the api: login endpoint

Before you can retrieve information, you need to login (POST https://lawmaker.staging.legislation.gov.uk/pdr/login), specifying a username, password and the docspace "LEGI_PDR" (ignore Swagger's suggestion that the docspace is not needed). The operation will return a x-auth token which is needed for all subsequent requests.

(In Swagger, the login operation is under "session" - one you have the x-auth token, click on "Authorize" button at top of page and enter token there to have it passed through automatically with any other swagger requests.)

Using the endpoints to retrieve information about legislation held in the PDR

The Swagger documentation of the endpoints is fairly comprehensive but the following points are worth mentioning.

Querying the PDR and obtaining metadata about projects, documents and amendments

List of the ID, title and type of each project that contain published documents

Where:

• types - comma separated list of project types to be included. Project type is determined by  the //bill[@name] attribute of the primary document in the project e.g.

  • sppubb for a Scottish Parliament public Bill,

  • spprib for a Scottish Parliament private bill,

  • asp for Act of the Scottish Parliament

  • ukpubb for a UK Parliament Bill

  • ukprib for a UK private bill,

  • ukpga for a UK act

• text= text to filter on project title (filter parameter is optional) Note: As with search within the application, you need to provide an entire word when searching. Eg. filtering by "crim" will not return "Criminal Justice (Scotland) Bill" but filtering by "criminal" will.

Examples

• To return all UK bill/Act projects: https://lawmaker.legislation.gov.uk/pdr/ids?doctypes=ukpubb,ukprib,ukhybb,ukpga

• To return all Scottish Bill/Act projects: https://lawmaker.legislation.gov.uk/pdr/ids?doctypes=sppubb,spprib,sphybb,asp

• To return all UK public Bills with "Finance" in their title: https://lawmaker.legislation.gov.uk/pdr/ids?doctypes=ukpubb&filter=Finance

Response

This will return JSON data including project title, project ID and type

List all documents in a particular project (not including individual amendments)

Where:

• projectId - project identifier of the form SPxxxxxx for Scottish Bill/Act projects, UKxxxxxx for UK Bill/Act projects (and SIxxxxxx for SI/SSIs)

Response

This will return a JSON object containing the URIs of all bill, act and amendment list document versions for the project ID you supply. In relation to each document, the following are provided:

• label: the version label (used to form the URI, e.g. "intro" for the as introduced version)

• stage: the stage the document belongs to. For Bills this will be the rubric that appears on the first page, e.g. "As introduced" or "As amended in committee"; for amendment lists it is the stage as in "Stage 2" or "Committee stage". Note this is only populated for documents published since around May 2021

• publicationDate: date of publication on the PDR

• title: the title of the project containing the document (effectively the title of the last published version of the Bill)

• docType: the document type (e.g. "sppubb" or "ukpubb" for a public Bill, "spdaily" for a daily list, "hcmarsh" for a house of commons marshalled list

• house: the chamber responsible for publishing the document, either HC (House of Commons), HL (House of Lords) or SP (Scottish Parliament) 

List all amendments in a particular project

Where:

• projectId - project identifier of the form SPxxxxxx for Scottish Bill projects, UKxxxxxx for UK Bill projects

Response

This will return a JSON object containing the URIs of, and additional metadata about, all amendments available on the PDR for the project ID you supply. In relation to each amendment, the following are provided:

• URI: the URI of the amendment which can be used to obtain the full XML of the amendment - see below

• Amendment number: the official number of the amendment or, if none, the unique ID assigned to the amendment (known as a "Dnumber")

• Stage: the parliamentary stage to which the amendment belongs

• Affected document: the URI of the Bill which is being amended

• Type: the amendment type (from this the House can be derived). Possible types:

  • spamnd - Scottish Parliament amendment

  • hlamnd - House of Lords amendment

  • hcamnd - House of Commons amendment

  • hcppmotion - House of Commons ping pong motion

  • hlppmotion - House of Lords ping pong motion

List of all unique version labels of published documents in the PDR

Where:

• types - comma separated list of project types to be included. Project type is determined by  the //bill[@name] attribute of the primary document in the project e.g.

  • sppubb for a Scottish Parliament public Bill,

  • spprib for a Scottish Parliament private bill,

  • asp for Act of the Scottish Parliament

  • ukpubb for a UK Parliament Bill

  • ukprib for a UK private bill,

  • ukpga for a UK act

Examples

• To return all unique version labels for UK bill/Act documents: https://lawmaker.legislation.gov.uk/pdr/version?doctypes=ukpubb,ukprib,ukhybb,ukpga

• To return all Scottish Bill/Act document versions: https://lawmaker.legislation.gov.uk/pdr/versions?doctypes=sppubb,spprib,sphybb,asp

Response

This will return JSON data including the version label and the version description. Note it only provides the version labels and descriptions for Bills and Acts - it doesn't include amendment lists.

List of all unique stages of published documents in the PDR (including amendment lists)

Where:

• types - comma separated list of project types to be included. Project type is determined by  the //bill[@name] attribute of the primary document in the project e.g.

  • sppubb for a Scottish Parliament public Bill,

  • spprib for a Scottish Parliament private bill,

  • asp for Act of the Scottish Parliament

  • ukpubb for a UK Parliament Bill

  • ukprib for a UK private bill,

  • ukpga for a UK act

Response

This will return JSON data including the unique stages at which documents (Bills, Acts and amendment lists) have been published.

List of all unique document types of published documents in the PDR

Response

This will return as JSON data a list of all document types currently within the PDR.

Obtaining specific legislative documents from the API

Bills and Acts

The API currently supports two main ways of specifying the legislation you are interested in:

• using the projectID - a "project" in the LDAPP system contains all the document versions, amendments and amendment lists relating to a single Bill

• using the official numeric identifiers attached to published Bills/Acts (i.e. session/year/number values)

The pattern for project ID based requests for Bills and Acts is:

Where:

• projectId - project identifier of the form SPxxxxxx for Scottish Bill/Act projects, UKxxxxxx for UK Bill/Act projects (and SIxxxxxx for SI/SSIs)

• docLabel - bill for Bills, act for Acts

• version - the version label for the Bill/Act

  • For Bills this relates to the rubric shown under the title e.g. introd - "[As introduced]", stage2 - "[As amended at Stage 2]", stage3 - "[as amended at Stage 3], custom_stage - "[custom stage]"

  • for Acts this will be enacted

• manifestation - the API supports 3 possible manifestations. The first two relate to actual manifestations stored within the PDR; the third is generated in response to a request.

  • xml - this is the primary source of the document in Akoma Ntoso xml - see https://ldapp.teratext.leidos.com.au/doku.php?id=modelling

  • pdf - this is static version of the PDF generated from the xml by the LDAPP system prior to publication

  • zip - this is a zip file containing the XML, PDF and and images associated with the XML file (equivalent to what is available from the "download XML" function from within Lawmaker).

Examples using project ID based requests

• pdr/SP000370/bill - returns a list of all Bill versions in the project SP000370

• pdr/UK000370/act - returns a list of Act versions in the project UK000370

• pdr/SP000370/bill@introd/xml - returns the XML of the as-introduced version

• pdr/SP000370/act@enacted/zip - returns a zip file containing the Act version XML, PDF and associated images 
  
  

The pattern for official identifier requests for Bills is:

Where:

• docType - the type of document, in the //bill[@name] attribute e.g.

  • sppubb for a Scottish Parliament public Bill,

  • ukpubb for a UK Parliament Bill

• chamber - the parliamentary chamber which published the Bill

  • SP - Scottish Parliament

  • HC - House of Commons

  • HL - House of Lords

• sessionNo - numeric component of session number

  • For Scottish Bills it will just be the session number as is, e.g. "5"

  • In the UK, the forward slash between the Parliament and session is encoded as an underscore instead, e.g. for "58/2" enter "58_2"

• billNo - numeric component of Bill number, e.g. "27"

• manifestation - as above
  
  

The pattern for official identifier requests for Acts is:

Where:

• docType - the type of act document in //act[name] attribute e.g.

  • asp for an Act of the Scottish Parliament,

  • ukpga for a UK Act

• year - Act year e.g. "2020"

• number - numeric component of Act number, e.g. "13"

• manifestation - as above

Response

In each case above, the response will depend on the manifestation selected. It will either return an XML document, a PDF or a zip file.

Amendment lists

The pattern for project ID based requests for amendment lists is:

Where:

• projectId, docLabel and version are as above

• amendListType is type of amendment list, e.g.

  • spdaily - Scottish daily list

  • spmarsh - Scottish marshalled list

  • spgroup - Scottish grounpings list

  • hcmarsh - Commons marshalled list

  • hcproceed - Commons proceedings

  • hldaily - Lords daily/supplementary sheet

  • hlmarsh - Lords marshalled list

  • cloa - Consolidated list of amendments (ping pong)

• date is the date the list was published

• manifestation is as above

The pattern for official session/number based requests for amendment lists is:

Where:

• docType, chamber, sessionNo, billNo - as above

• amendListType is type of amendment list, e.g.

  • spdaily - Scottish daily list

  • spmarsh - Scottish marshalled list

  • spgroup - Scottish groupings list

  • hcmarsh - Commons marshalled list

  • hcproceed - Commons proceedings

  • cloa - Consolidated list of amendments (Ping Pong)

• date is the date the list was published

• manifestation - as above

Response

In each case above, the response will depend on the manifestation selected. It will either return an XML document, a PDF or a zip file.

Individual amendments

The pattern for requests for an individual amendment is:

Where:

• projectId is the project ID

• version is the bill version that the amendment relates to (the first part of an individual amendment URI is essentially the URI of the Bill to which the amendment relates)

• stage is the parliamentary stage at which the amendment is being considered (with underscores instead of spaces), e.g. "stage_2", "committee_stage"

• num is the amendment number or, if it has none, the ID assigned to the amendment (unique within the project and known as a "Dnumber")

• manifestation is as above but presently only the XML manifestation is supported

Response

This returns an XML document consisting of a complete amendment with metadata.

SI/SSIs

Because SIs/SSIs won't have a number until after they have left the Lawmaker system in most cases, the current API for SI/SSIs relies on the project ID and a version number to identify SIs

The pattern for project ID based requests for an SI or SSI is:

Where:

• projectId - project identifier of the form  SIxxxxxx for SI/SSIs

• docType  - the docType of the SI/SSI, e.g. uksi, ukdsi, ssi, sdsi etc.

• version - the version identifier for the SI. As versions of the same SI/SSI are placed on the PDR they are assigned consecutive version numbers, e.g. 1, 2, 3 etc.

• manifestation - the API supports 3 possible manifestations. The first two relate to actual manifestations stored within the PDR; the third is generated in response to a request.

  • xml - this is the primary source of the document in Akoma Ntoso xml - see https://ldapp.teratext.leidos.com.au/doku.php?id=modelling

  • pdf - this is static version of the PDF generated from the xml by the LDAPP system prior to publication

  • zip - this is a zip file containing the XML, PDF and and images associated with the XML file (broadly equivalent to what is available from the "download XML" function from within Lawmaker).

Response

The response will depend on the manifestation selected. It will either return an XML document, a PDF or a zip file.

Examples using project ID based requests

• pdr/SI000102/uksi@3/zip - returns a zip file containing the 3rd version of the made SI in this project put on the PDR