Package 'finlex'

Download the catalogue of Finnish statutes

Description

Retrieves the list of Finnish statutes (Finnish: säädökset) published via the Finlex Open Data REST API (https://www.finlex.fi/en/open-data), for a given range of years and statute categories. Only the Finnish-language (fin) version of each statute is returned.

Usage

flx_download_statutes(
  start_year = 1987,
  end_year = as.integer(format(Sys.Date(), "%Y")),
  categories = c("new-statute", "amending-statute", "repealing-statute"),
  quiet = FALSE
)

Arguments

start_year	Integer. First year to include. The Finlex Open Data API currently starts from 1987.
end_year	Integer. Last year to include. Defaults to the current year.
categories	Character vector. One or more of "new-statute", "amending-statute", "repealing-statute". Defaults to all three.
quiet	Logical. If FALSE (the default), prints one progress message per year processed.

Value

A tibble::tibble() with one row per statute and the columns:

akn_uri

The Akoma Ntoso URI identifying the statute.

year

Year of the statute, as an integer.

number

Statute number within that year, as an integer.

statute_type

One of "NewStatute", "Amendment", "Repeal".

Returns a zero-row tibble with the same columns if nothing matches.

Examples

flx_download_statutes(
  start_year = 2023,
  end_year   = 2023,
  categories = "new-statute"
)

---

Get statutes affected by an amending or repealing statute

Description

For a given amending or repealing statute, retrieves the statute(s) it affects (the affectedDocument references in the Akoma Ntoso document). A single amending statute can affect more than one target statute (for example, an omnibus act amending several other acts), in which case one row is returned per affected target.

Usage

flx_get_affected(year, number)

Arguments

year	Integer vector. Year(s) of the amending/repealing statute(s).
number	Integer vector. Number(s) of the statute(s) within that year. Recycled against year if shorter.

Details

This function does not check whether the supplied statute is actually an amendment or repeal; it simply looks for affectedDocument references in whatever statute is requested. New statutes will typically return status = "no_affected".

Value

A tibble::tibble() with the columns:

source_year

Year of the amending/repealing statute, as supplied.

source_number

Number of the amending/repealing statute, as supplied.

status

One of "ok" (at least one affected statute found), "no_affected" (statute found, but no affected-document references present), "not_found", or "error".

target_href

URI of the affected statute, or NA.

target_year

Year of the affected statute, or NA.

target_number

Number of the affected statute, or NA.

Examples

# Look up affected statutes for a known amending statute
flx_download_statutes(
  start_year = 2023, end_year = 2023,
  categories = "amending-statute"
) |>
  head(1) |>
  with(flx_get_affected(year, number))

---

Get structured metadata for one or more Finnish statutes

Description

Retrieves core bibliographic metadata for one or more Finnish statutes from the Finlex Open Data API: the date of issue, the official title, and the number of sections (Finnish: pykälät) in the statute text.

Usage

flx_get_metadata(year, number)

Arguments

year	Integer vector. Year(s) of the statute(s).
number	Integer vector. Number(s) of the statute(s) within that year. Recycled against year if shorter.

Details

This function intentionally returns only raw, directly observed fields. Any derived classification (for example, grouping statutes into categories such as "Act", "Decree", or "Decision" based on title patterns) is left to a separate function, since that involves methodological choices rather than data retrieval.

Value

A tibble::tibble() with one row per ⁠(year, number)⁠ pair and the columns:

year

As supplied.

number

As supplied.

status

One of "ok", "not_found", or "error".

date_issued

Date the statute was issued, as a Date.

title

The statute's official title.

n_sections

Integer. Number of section elements found in the Akoma Ntoso document — a rough, purely structural proxy for statute length.

Examples

flx_get_metadata(year = 1992, number = 1535) # Tuloverolaki

---

Get the title of one or more Finnish statutes

Description

Retrieves the official title of one or more Finnish statutes from the Finlex Open Data API, given each statute's year and number.

Usage

flx_get_title(year, number)

Arguments

year	Integer vector. Year(s) of the statute(s).
number	Integer vector. Number(s) of the statute(s) within that year. Recycled against year if shorter.

Details

Not every statute in Finnish legal history is available through the Finlex Open Data API (very old statutes in particular are not covered). When a statute cannot be found, status is set to "not_found" rather than raising an error, so that vectorized calls complete even when some statutes are missing.

Value

A tibble::tibble() with one row per ⁠(year, number)⁠ pair and the columns:

year

As supplied.

number

As supplied.

status

One of "ok", "not_found", or "error".

title

The statute's official title, or NA if unavailable.

Examples

flx_get_title(year = 1992, number = 1535) # Tuloverolaki
flx_get_title(year = c(1992, 1993), number = c(1535, 1501))

---