Works and expressions
Listing and fetching works and expressions.
Two important concepts that are an essential part of the API are works and expressions.
- A Work is a piece of legislation, such as an act, regulation or by-law. A work may be amended over time and may even have its title changed. A work is uniquely identified by a work FRBR URI which never changes.
- An Expression is a version of a Work in specific language at a particular point in time. A work can have many expressions, usually one for each official language and amendment. An expression is uniquely identified by its own expression FRBR URI, which is derived from the work's FRBR URI.
An example of a work is the South African Employment Equity Amendment Act, 2013 (Act 55 of 1998) with unique work FRBR URI
/akn/za/act/1998/55. This act has been amended a number of times since it was first passed. Each amended version (also called a point in time) is a unique expression of the work.The English expression of the work, as it was amended on 17 January 2014, is uniquely identified by the expression FRBR URI
/act/1998/55/eng@2014-01-17. You can see that this is built from the work's URI, with a language code eng and the expression date 2014-01-17 included.When fetching details from the API, you are always fetching details for a particular expression of the work. The expression will also include information related to the expression's work, such as the work's FRBR URI and publication information. Even if you don't specific a particular date for the expression, the API will return the latest expression applicable for the date of the request.
The API supports the language and date aspects defined in the Akoma Ntoso naming convention standard.
get
https://api.laws.africa
/v2/akn/:country/.:format
List works for a place
Supported content types: JSON, PDF, ePub, zip
get
https://api.laws.africa
/v2/:frbr-uri.:format
A single expression
Supported content types: JSON, HTML, PDF, ePub, zip
The fields of the work and expression endpoints are described in the table below.
Field | Description | Type |
amendments | List of amendments that have been applied to create this expression of the work. | |
as_at_date | Date up to which this work is known to be up-to-date. | ISO8601 |
assent_date | Date when the work was assented to. | ISO8601 |
content_url | URL of the full content of the work. | URL |
country | ISO 3166-1 alpha-2 country code that this work is applicable to. | String |
created_at | Timestamp of when the work was first created. | ISO8601 |
draft | Is this a draft work or is it available in the public API? | Boolean |
expression_date | Date of this expression of the work. | ISO8601 |
commencement_date | Date on which this work commences. | ISO8601 |
commencing_work | Details of the work which commenced this work, if any. | Object |
commencements | Details of the commencements which apply to this work. | |
expression_frbr_uri | FRBR URI of this expression of this work. | String |
frbr_uri | FRBR URI for this work. | String |
id | Unique ID of this work. | Integer |
language | Three letter ISO-639-2 language code for this expression of the work. | String |
links | A description of links to other formats of this expression that are available through the API. | Array |
locality | The code of the locality within the country. | String |
nature | The nature of this work, normally "act". | String |
number | Number of this work with its year, or some other unique way of identifying it within the year. | String |
parent_work | The parent of this work. For subsidiary legislation, this is the principal legislation. | Object |
points_in_time | Points in time that are available for this work. | |
publication_date | Date of original publication of the work. | ISO8601 |
publication_name | Name of the publication in which the work was originally published. | String |
publication_number | Number of the publication in which the work was originally published. | String |
repeal | Description of the repeal of this work, if it has been repealed. | See below |
subtype | Subtype code of the work. | String |
title | Short title of the work, in the appropriate language. | String |
updated_at | Timestamp of when the work was last updated. | ISO8601 |
url | URL for fetching details of this work. | URL |
year | Year of the work. | Stri |
The fields of the
amendments property of the response are described below. These are the amendments that have been applied to produce this particular expression.Field | Description | Type |
amending_title | Title of the amending work | String |
amending_uri | Work FRBR URI of the amending work | String |
date | Date on which the amendment takes place | ISO8601 |
The items in the
commencements property describe the various commencements that apply to this work, and are the same for all expressions.In most cases, either the work is not commenced or a single work commences all of the work's provisions. In some edge cases, different provisions commence at different times and these objects describe those events.
In some extreme cases, the work that performed the commencement, or the commencement date, might not be known.
Field | Description | Type |
commencing_title | Title of the commencing work (optional) | String |
commencing_frbr_uri | FRBR URI of the commencing work (optional) | String |
date | Date of the commencement event (optional) | ISO8601 |
main | Is this considered the primary or main commencement event? This is usually the event that commences the bulk of the work. | Boolean |
all_provisions | Does this event commence all provisions? If this is true, there will only be one of these commencement objects. | Boolean |
provisions | A list of IDs of the provisions that are commenced by this event. This is always empty if all_provisions is true. | List |
The fields of the
points_in_time property of the response are described below. These are all the available points in time available for this work.Field | Description | Type |
date | Date of the point-in-time for which expressions are available | ISO8601 |
expressions | A list of expressions for this work available at this point in time | List |
url | The API URL to fetch information on the expression | URL |
language | Three-letter language code of the language of the expression | String |
expression_frbr_uri | Unique Expression FRBR URI for this expression | String |
expression_date | Date of this expression | ISO8601 |
title | Title of the work, appropriate for the expression in the expression's language) | String |
Works may be amended and change over time. You can fetch different amended versions of a work by specifying the language and date in the FRBR URI of the request.
The available points in time of a work are listed in the
points_in_time field of the JSON description of the work. Each point in time includes a date and a list of expressions available at that date, one for each available language.To fetch the very first expression of a work, use
frbr-uri/:language@, for example: /akn/za/act/1998/5/eng@.To fetch a specific point in time, use
frbr-uri/:language@:date, for example: /akn/za/act/1998/5/eng@2014-01-17.To fetch the most recent point in time at or before a specific date, use
frbr-uri/:language::date, for example /akn/za/act/1998/5/eng:2014-01-17. The
.format part of the FRBR URI is placed after the @YYYY-MM-DD part.If you use
@ to specify a particular date and the API doesn't have a version at exactly that date, it will return a 404 response. If you need the expression of the work closest to a particular date, use : instead. Date Format | Meaning | Example Expression FRBR URI |
@ | Very first expression of a work. | /akn/za/act/1998/55/eng@ |
@YYYY-MM-DD | Expression at the specific date. | /akn/za/act/1998/55/eng@2014-01-17 |
:YYYY-MM-DD | Most recent expression at or before a date. | /akn/za/act/1998/55/eng:2015-01-01 |
(none) | The most recent expression at or before today's date. Equivalent to using : with today's date. | /akn/za/act/1998/55/eng |