| Title: | Access Open Data from the Finnish 'Finlex' Legislative Database |
|---|---|
| Description: | Provides functions to retrieve and structure Finnish legislative data made available through the 'Finlex' Open Data API (<https://www.finlex.fi/en/open-data>). Functions cover retrieval of statute catalogues, statute titles, structured statute metadata, and cross-references between amending and amended statutes, returned as tidy tibbles for further analysis. |
| Authors: | Kristian Vepsäläinen [aut, cre] |
| Maintainer: | Kristian Vepsäläinen <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-07-23 10:57:40 UTC |
| Source: | https://github.com/kristianvepsalainen/finlex |
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.
flx_download_statutes( start_year = 1987, end_year = as.integer(format(Sys.Date(), "%Y")), categories = c("new-statute", "amending-statute", "repealing-statute"), quiet = FALSE )flx_download_statutes( start_year = 1987, end_year = as.integer(format(Sys.Date(), "%Y")), categories = c("new-statute", "amending-statute", "repealing-statute"), quiet = FALSE )
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 |
quiet |
Logical. If |
A tibble::tibble() with one row per statute and the columns:
The Akoma Ntoso URI identifying the statute.
Year of the statute, as an integer.
Statute number within that year, as an integer.
One of "NewStatute", "Amendment", "Repeal".
Returns a zero-row tibble with the same columns if nothing matches.
flx_download_statutes( start_year = 2023, end_year = 2023, categories = "new-statute" )flx_download_statutes( start_year = 2023, end_year = 2023, categories = "new-statute" )
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.
flx_get_affected(year, number)flx_get_affected(year, number)
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 |
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".
A tibble::tibble() with the columns:
Year of the amending/repealing statute, as supplied.
Number of the amending/repealing statute, as supplied.
One of "ok" (at least one affected statute found),
"no_affected" (statute found, but no affected-document
references present), "not_found", or "error".
URI of the affected statute, or NA.
Year of the affected statute, or NA.
Number of the affected statute, or NA.
# 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))# 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))
Retrieves the consolidated version of a statute – the text as
currently in force, with all amendments merged in – split into one
row per section (Finnish: pykala). This complements flx_get_text(),
which returns the statute's original, as-enacted text.
flx_get_consolidated_text(year, number)flx_get_consolidated_text(year, number)
year |
Integer vector. Year(s) of the statute(s) as originally enacted. The consolidated version shares the same year/number as the original statute – it is a different rendering of the same legal work, not a separate document. |
number |
Integer vector. Number(s) of the statute(s) within that
year. Recycled against |
Not every statute has a consolidated version available – for example,
very recent statutes that have never been amended, or statutes outside
the API's consolidation coverage, will return status = "not_found".
A tibble with one row per section (or one row with NA
section fields if the statute has no sections, has no consolidated
version, was not found, or an error occurred) and the columns:
year, number, status (one of "ok", "no_sections",
"not_found", or "error"), section_index, section_id,
heading, and text.
flx_get_consolidated_text(year = 1992, number = 1535) # Tuloverolakiflx_get_consolidated_text(year = 1992, number = 1535) # Tuloverolaki
Retrieves a document from the generic document endpoint of the Finlex
Open Data API (/akn/fi/doc/...), which covers document types that are
not part of the Statute Book of Finland: treaties, government
proposals, authority regulations, and certain collective agreements.
flx_get_doc(doc_type, year, number)flx_get_doc(doc_type, year, number)
doc_type |
Character, length 1. One of |
year |
Integer vector. Year(s) of the document(s). |
number |
Character or integer vector. Number(s) of the
document(s) within that year. Recycled against |
Unlike flx_get_text(), this function does not split the document
into sections. The document types covered here (treaties, government
proposals, agreements) do not share a consistent internal structure
the way statutes do, so the full body text is returned as a single
block.
Some documents, particularly older ones, have never been digitised as
machine-readable text and exist only as a scanned or original PDF. For
these, status is "pdf_only", text is NA, and pdf_url points
to the PDF so the content is still reachable.
Two document types available in the underlying API are intentionally
not covered by this function: "treaty-metadata" (a lighter
reference record rather than a full document) and
"legal-literature-references" (an index of literature discussing
case law, not the case law itself). Both likely need bespoke handling
and may be added in a future version.
A tibble::tibble() with one row per document and the
columns:
As supplied.
As supplied.
As supplied.
One of "ok", "pdf_only" (the document exists but
has no machine-readable text, only a scanned/original PDF),
"not_found", or "error".
The document's official title.
Date the document was issued, as a Date.
The full body text of the document, or NA if only a
PDF is available.
URL of the document's PDF version. Populated for
both "ok" and "pdf_only" statuses.
flx_get_doc( doc_type = "authority-regulation", year = 1996, number = 32082 )flx_get_doc( doc_type = "authority-regulation", year = 1996, number = 32082 )
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.
flx_get_metadata(year, number)flx_get_metadata(year, number)
year |
Integer vector. Year(s) of the statute(s). |
number |
Integer vector. Number(s) of the statute(s) within that
year. Recycled against |
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.
A tibble::tibble() with one row per (year, number) pair and
the columns:
As supplied.
As supplied.
One of "ok", "not_found", or "error".
Date the statute was issued, as a Date.
The statute's official title.
Integer. Number of section elements found in the
Akoma Ntoso document — a rough, purely structural proxy for
statute length.
flx_get_metadata(year = 1992, number = 1535) # Tuloverolakiflx_get_metadata(year = 1992, number = 1535) # Tuloverolaki
Retrieves the body text of a Finnish statute from the Finlex Open Data
API, split into one row per section (pykälä). This complements
flx_get_metadata(), which only reports the number of sections; this
function returns their actual content.
flx_get_text(year, number)flx_get_text(year, number)
year |
Integer vector. Year(s) of the statute(s). |
number |
Integer vector. Number(s) of the statute(s) within that
year. Recycled against |
Statutes can be long. Calling this function for many statutes at once
will be slow and will retrieve a large amount of text — consider
narrowing down to the statutes you actually need (for example with
flx_download_statutes() or flx_get_metadata()) before calling this
function.
A tibble::tibble() with one row per section (or one row with
NA section fields if the statute has no sections, was not found, or
an error occurred) and the columns:
Year of the statute, as supplied.
Number of the statute, as supplied.
One of "ok", "no_sections" (statute found, but
contains no section elements — for example a very short
decision), "not_found", or "error".
Integer. The section's position within the statute (1-based), in document order.
Character. The section's Akoma Ntoso eId
attribute, if present (for example "sec_1").
Character. The section heading, if present.
Character. The full text of the section, including its heading.
flx_get_text(year = 1992, number = 1535) # Tuloverolaki, all sectionsflx_get_text(year = 1992, number = 1535) # Tuloverolaki, all sections
Retrieves the official title of one or more Finnish statutes from the Finlex Open Data API, given each statute's year and number.
flx_get_title(year, number)flx_get_title(year, number)
year |
Integer vector. Year(s) of the statute(s). |
number |
Integer vector. Number(s) of the statute(s) within that
year. Recycled against |
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.
A tibble::tibble() with one row per (year, number) pair and
the columns:
As supplied.
As supplied.
One of "ok", "not_found", or "error".
The statute's official title, or NA if unavailable.
flx_get_title(year = 1992, number = 1535) # Tuloverolaki flx_get_title(year = c(1992, 1993), number = c(1535, 1501))flx_get_title(year = 1992, number = 1535) # Tuloverolaki flx_get_title(year = c(1992, 1993), number = c(1535, 1501))