Legal statutes

Current text of laws and regulations, one dataset per official source. Authentication, errors and conventions are on the overview; scope, licensing and attribution are explained on Legal data.

Datasets

These ten ids can be passed as dataset. Which of them have data is on the datasets page; in GET /v1/datasets their path is /v1/legal/statutes/instruments?dataset={id}.

Dataset id	instrument_id prefix
`legal.statutes.tw_moj`	`TW:MOJ:`
`legal.statutes.jp_egov`	`JP:EGOV:`
`legal.statutes.uk_legislation`	`UK:LEG:`
`legal.statutes.ca_laws`	`CA:JUSTICE:`
`legal.statutes.eu_eurlex`	`EU:EURLEX:`
`legal.statutes.us_ecfr`	`US:ECFR:`
`legal.statutes.de_gii`	`DE:GII:`
`legal.statutes.au_federal`	`AU:FEDERAL:`
`legal.statutes.sg_sso`	`SG:SSO:`
`legal.statutes.cn_flk`	`CN:FLK:`

Instrument ids

An instrument_id is {JURISDICTION}:{SOURCE}:{native_id}, with a :lang suffix on additional language versions (TW:MOJ:A0000001:en). The native id can contain / (UK:LEG:ukpga/2020/1). In a path you may write it raw or percent-encoded; both reach the same record. An id of the wrong shape is 400; a well-formed id that does not exist is 404.

List laws

`GET /v1/legal/statutes/instruments`

Returns records without their provisions or foreword, ordered by instrument_id. All filters are optional and combine with AND.

Parameter	Meaning
`dataset`	One of the ten dataset ids above; anything else is 400.
`jurisdiction`	Two capital letters: `TW`, `JP`, `UK`, `CA`, `EU`, `US`, `DE`, `AU`, `CN`, `SG`.
`language`	Exact match, for example `zh-Hant`, `en`, `ja`.
`kind`	`act`, `regulation`, `order`, `treaty`, `other`.
`status`	`in_force`, `repealed`, `abandoned`, `withdrawn`.
`q`	Title contains this text (case-insensitive, 1 to 200 characters). A catalogue filter, not full-text search.
`updated_since`	`YYYY-MM-DD` (00:00 UTC) or an RFC 3339 time. Records updated at or after it. Write `+` as `%2B`, or use `Z`.
`include_removed`	`true` to include laws the source no longer lists. Combine with `updated_since` to track removals.
`limit`, `cursor`	1 to 200 per page, default 50. Pass the previous `next_cursor` back unchanged; it is `null` on the last page.

curl -H "Authorization: Bearer $AGGRE_API_KEY" \
  "https://api.aggre.org/v1/legal/statutes/instruments?jurisdiction=TW&language=en&kind=act&q=copyright&limit=5"

Each record has: instrument_id, dataset_id, jurisdiction, source, native_id, language, kind, level, title, title_alt, status, promulgated_on, effective_on, modified_on, url, extra, content_hash, record_id, license, attribution, restricted, first_seen_at, fetched_at, updated_at and removed_on. Dates are YYYY-MM-DD; times are RFC 3339.

Read one law

`GET /v1/legal/statutes/instruments/{instrument_id}`

The record plus foreword, provision_count, provisions (each with seq, kind, number, heading, text, content_hash) and attachments (seq, file_name, file_url), read in one consistent snapshot. This route takes no query parameters.

At most 5000 provisions come back. For a longer law provisions_truncated is true and next_from_seq is where to continue with the provisions route.
A law the source stopped listing still answers 200, with removed_on set and a meta.message saying the content is the last text seen.

curl -H "Authorization: Bearer $AGGRE_API_KEY" \
  "https://api.aggre.org/v1/legal/statutes/instruments/UK:LEG:ukpga/2020/1"

Read provisions

`GET /v1/legal/statutes/instruments/{instrument_id}/provisions`

Parameters: from_seq (0 or more, default 0) or cursor (not both), number (exact article number as written, such as 15-1) and limit (1 to 1000, default 500). The response has next_cursor and next_from_seq, both set while more remain. A from_seq past the end answers 200 with an empty list and meta.status = "empty".

curl -H "Authorization: Bearer $AGGRE_API_KEY" \
  "https://api.aggre.org/v1/legal/statutes/instruments/TW:MOJ:A0000001:en/provisions?limit=100"

meta: restricted, attribution, licences

Beyond the common fields, statute responses add meta.restricted (true if any returned law is restricted), meta.attribution and meta.licenses (sorted, de-duplicated texts of the returned laws). Provision rows do not carry these fields; for them, read meta. If a response is restricted you must show the attribution it names and tell your users to check the source for the latest version. Details and caveats: licensing and attribution.

Errors specific to these routes

503 store_unavailable when the statute store is not configured or the query fails. There are no new error codes. Unknown or repeated parameters, a bad cursor, or a cursor from another route are 400 invalid_request.