New Zealand Legislation API (v0)

This API provides progammatic access to New Zealand legislation. It is currently "Version Zero" of an API, which has been developed to provide an opportunity for developers to test and provide feedback which will inform future enhancement and refinement.

The functionality of the API is intended to match that of the site search on the Legislation Website, and is strongly influenced by the FRBR model.

This API is based on a three-tier conceptual model of works, versions, and formats.

A work is the highest level, and represents the concept of an enduring standalone piece of legislation, that may have multiple versions. Each work has a work_id. Examples of works are:

• New Zealand Bill of Rights Act 1990, act_public_1990_109
• Natural and Built Environment Bill, bill_government_2022_186
• Microwave Ovens Regulations 1982, secondary-legislation_pco-drafted_1982_221

One level below a work is a version. Each work can have one or more versions. Each consolidation of an Act is a new version, as is each stage of a Bill. A version is equivilant to an expression in the FRBR model. Each version has a version_id. Examples of versions are:

• The version of the New Zealand Bill of Rights Act 1990 as at 30 August 2022, act_public_1990_109_en_2022-08-30
• The second reading version of the Natural and Built Environment Bill as reported from the Environment Committee on 27 June 2023, bill_government_2022_186_en_2023-06-27
• The version of the Microwave Ovens Regulations 1982 as at 1 July 2023, secondary-legislation_pco-drafted_1982_221_en_2013-07-01

One level below a version is a format. Each version of each work will have multiple formats, such as the source XML file, a PDF file, or an HTML page. Some versions will have formats that other versions don't have, such as the as enacted versions of some Acts which have also have a format providing a scan of the original printed Act. A format is equivilant to a manifestation in the FRBR model.

This API does not include an equivilant of the fourth level in the FRBR model, 'Item', which would generally be the concrete example of a specific format of a version, i.e. an XML file saved on a particular drive, or a PDF file printed on sheets of paper.

The structure of work_id and version_id identifiers used by this API is shared with the URLs of the Legislation website. They are constructed from six segments:

1. type — Kind of legislation. Must be one of: act, bill, secondary-legislation, amendment-paper.

2. subtype — Sub-classification of that type. Allowed values depend on type:

   • Acts: public, imperial, local, private, provincial
   • Bills: government, local, members, private
   • Secondary legislation: agency-drafted, pco-drafted
   • Amendment papers: government, members

3. date — Year. Must be four digits (YYYY). May be prefixed with ~ when the value is ephemeral.

4. number — Legislation number or identifier. Must match: digits. May have followed by a single letter (deduplication), optionally followed by a hyphen and letter (e.g. bill split: 96-B). May be prefixed with ~ when ephemeral.

5. language — Language. Currently only en is used.

6. version_date — Date identifying the version in time. Must be YYYY-MM-DD. May be prefixed with ~ when ephemeral. May have a suffix of one or more deduplication letters (e.g. A, B, AB, BA, 2023-12-31B) when multiple versions share the same base date.

A version_id is all six segments, and a work_id is the first four segments, each joined together with underscore characters.

Ephemeral segments

For some agency-published secondary legislation harvested from agency websites through the pilot secondary legislation service, we do not have sufficient data to construct a permanent identifier. In these cases, we use fallback values to calculate 'ephemeral' identifiers.

For example, if we do not know the commencement date of a piece of secondary legislation, we cannot determine the correct value for the version_date segment, and will fall back to using the date the record was harvested from the agency website.

To indicate that these values are not final, and may change if we get better data for the record in the future, they are prefixed with a ~ character. Any identifiers which contain ~ characters may change in the future.

Website URLs for legislation follow the same pattern as the identifiers described above:

https://www.legislation.govt.nz/{type}/{subtype}/{date}/{number}/{language}/{version_date}/

The website uses latest as an alias value in the version_date segment, which always resolves to the most recent version of a work.

Formats

Responses to API queries include links to versions in their available formats. These can also be constructed directly by manipulating URLs, for example:

• https://www.legislation.govt.nz/act/public/1990/109/en/2022-08-30/: HTML page of the New Zealand Bill of Rights Act 1990 as at 30 August 2022
• https://www.legislation.govt.nz/act/public/1990/109/en/2022-08-30.pdf/: PDF of the New Zealand Bill of Rights Act 1990 as at 30 August 2022
• https://www.legislation.govt.nz/act/public/1990/109/en/2022-08-30.xml/: XML source of the New Zealand Bill of Rights Act 1990 as at 30 August 2022

For legislation and secondary legislation drafted by the PCO; html, pdf, and xml formats are available.

For as enacted versions of pre-2008 Acts that have been converted from scans of the original printed volumes, an additional format of pdf_original_scan is available which contains the scanned PDF.

For agency drafted secondary legislation harvested through the pilot secondary legislation service, HTML or PDF formats may be available, but this will vary from record to record, and links may point to agency websites which do not follow the URL patterns described above.

Each API key has a default rate limit of 10,000 requests per day, with the quota resetting at midnight NZ local time.

Requests sent after this rate limit has been reached will receive a response with HTTP status code 429, Too Many Requests.

The rate limit is communicated using the X-RateLimit response headers, which have values of:

• X-RateLimit-Limit: number of requests permitted per period.
• X-RateLimit-Remaining: number of requests remaining in the current period.
• X-RateLimit-Reset: Unix timestamp of the UTC time at which the period ends and the quota resets.

In addition to these per-key rate limits, there is a burst limit of no more than 2,000 requests permitted from any single IP address in any five minute period. Requests sent after this limit is reached will receive a response with HTTP status code 403 Forbidden. Once a further five minutes have elapsed, further requests from that IP address will be permitted.