fagfunksjoner.api package

Submodules

fagfunksjoner.api.statistikkregisteret module

class Contact(name, contact_id, phone, cellphone, email, initials, changed)

Bases: object

Represents a contact with various attributes.

Parameters:

  • name (Name)

  • contact_id (str)

  • phone (str)

  • cellphone (str)

  • email (str)

  • initials (str)

  • changed (str | datetime | None)

name

A list of LangText objects representing names.

contact_id

The contact ID.

phone

The contact’s phone number.

cellphone

The contact’s cellphonee number.

email

The contact’s email address.

initials

The contact’s initials.

changed

The last modified timestamp.

cellphone: str
changed: str | datetime | None
contact_id: str
email: str
initials: str
name: Name
phone: str
exception FuturePublishingError

Bases: Exception

Missing expected publishing at a future time.

class LangText(lang, text, name)

Bases: object

Represents a text with a language attribute.

Parameters:

  • lang (str)

  • text (None | str)

  • name (None)

lang

The language code.

text

The text in the specified language.

name

Unused attribute, kept for compatibility.

lang: str
name: None
text: None | str
class MultiplePublishings(publishings, amount, date)

Bases: object

Contains multiple statistics, like when getting all the data in the API.

Parameters:
amount: int
date: str
publishings: list[StatisticPublishingShort]
class Name(name_lang)

Bases: object

Represents a list of LangText objects.

Parameters:

name_lang (list[LangText])

name_lang

A list of LangText objects.

name_lang: list[LangText]
class Owningsection(name, section_id)

Bases: object

Represents an ownership section with various attributes.

Parameters:

  • name (list[LangText])

  • section_id (str)

name

A list of LangText objects representing names.

section_id

The section ID.

name: list[LangText]
section_id: str
class PublishingSpecifics(name, publish_id, statistic, variant, status, is_period, period_from, period_until, precision, time, has_changed, desk_flow, time_changed, is_cancelled, revision, title)

Bases: object

Hold specific information about each publishing.

Parameters:

  • name (str)

  • publish_id (str)

  • statistic (str)

  • variant (str)

  • status (str)

  • is_period (bool)

  • period_from (datetime)

  • period_until (datetime)

  • precision (str)

  • time (datetime)

  • has_changed (bool)

  • desk_flow (str)

  • time_changed (datetime)

  • is_cancelled (bool)

  • revision (str)

  • title (str)

desk_flow: str
has_changed: bool
is_cancelled: bool
is_period: bool
name: str
period_from: datetime
period_until: datetime
precision: str
publish_id: str
revision: str
statistic: str
status: str
time: datetime
time_changed: datetime
title: str
variant: str
class SinglePublishing(name, short_name, old_subjectcodes, firstpublishing, status, owningsection, contacts, triggerwords, variants, regional_levels, continuation, publish_id, default_lang, approved, changed, desk_flow, dir_flow, created_date, annual_reporting, start_year, changes, publishings)

Bases: object

Represents a single publishing entry with various attributes.

Parameters:

  • name (Name | str)

  • short_name (str)

  • old_subjectcodes (str | None)

  • firstpublishing (str)

  • status (str)

  • owningsection (Owningsection)

  • contacts (list[Contact] | None)

  • triggerwords (dict[str, list[dict[str, str]]] | None)

  • variants (list[Variant] | list[str])

  • regional_levels (list[str])

  • continuation (dict[str, bool] | None)

  • publish_id (str)

  • default_lang (str)

  • approved (str | None)

  • changed (str | list[str] | None)

  • desk_flow (str | None)

  • dir_flow (str | None)

  • created_date (datetime | None)

  • annual_reporting (bool | None)

  • start_year (str | None)

  • changes (list[str] | None)

  • publishings (MultiplePublishings | None)

name

The name details.

short_name

The short name.

old_subjectcodes

The old subject codes.

firstpublishing

The first publication date.

status

The status code.

owningsection

The ownership section.

contacts

A list of contacts.

triggerwords

A dictionary of trigger words.

variants

A list of variants.

regional_levels

A list of regional levels.

continuation

A dictionary of continuation information.

publish_id

The ID of the publishing entry.

default_lang

The default language code.

approved

Approval status.

changed

The last modified date.

desk_flow

Desk flow status.

dir_flow

Directory flow status.

created_date

Creation date.

annual_reporting

True if annual reporting, False otherwise.

start_year

Start year.

changes

List of changes.

publishings

List of publishings.

annual_reporting: bool | None
approved: str | None
changed: str | list[str] | None
changes: list[str] | None
contacts: list[Contact] | None
continuation: dict[str, bool] | None
created_date: datetime | None
default_lang: str
desk_flow: str | None
dir_flow: str | None
firstpublishing: str
name: Name | str
old_subjectcodes: str | None
owningsection: Owningsection
publish_id: str
publishings: MultiplePublishings | None
regional_levels: list[str]
short_name: str
start_year: str | None
status: str
triggerwords: dict[str, list[dict[str, str]]] | None
variants: list[Variant] | list[str]
class StatisticPublishingShort(stat_id, short_name, variant, desk_flow, time_changed, specifics)

Bases: object

Top-level metadata for a specific statistical product.

Parameters:

  • stat_id (str)

  • short_name (str | None)

  • variant (str)

  • desk_flow (str)

  • time_changed (datetime)

  • specifics (None | PublishingSpecifics)

desk_flow: str
short_name: str | None
specifics: None | PublishingSpecifics
stat_id: str
time_changed: datetime
variant: str
class Variant(name, variant_id, revision, ceased, detail_level, detail_level_en, frequency)

Bases: object

Represents a variant with various attributes.

Parameters:

  • name (str)

  • variant_id (str)

  • revision (str)

  • ceased (str)

  • detail_level (str)

  • detail_level_en (str)

  • frequency (str)

name

The name of the variant.

variant_id

The variant ID.

revision

The revision of the variant.

ceased

Whether the variant is discontinued.

detail_level

Detailed level information.

detail_level_en

Detailed level information in English.

frequency

The frequency of the variant.

ceased: str
detail_level: str
detail_level_en: str
frequency: str
name: str
revision: str
variant_id: str
etree_to_dict(t)

Convert an XML-tree to a python dictionary.

Parameters:

t (Element) – The XML element to convert.

Returns:

The python dictionary that has been converted to.

Return type:

dict[str, Any]

find_latest_publishing(shortname='trosamf')

Find the date of the latest publishing of the statistical product.

Parameters:

shortname (str) – The shortname to find the latest publishing for. Defaults to “trosamf”.

Returns:

data about the specific publishing. Or None if nothing is found.

Return type:

StatisticPublishingShort | None

find_publishings(shortname='trosamf', get_publishing_specifics=True)

Get the publishings for a specific shortcode.

Parameters:

  • shortname (str) – The shortcode to look for in the API among the publishings. Defaults to “trosamf”.

  • get_publishing_specifics (bool) – Looks up more info about each of the publishings found. Defaults to True.

Returns:

A datastructure with the found metadata about the statistics.

Return type:

MultiplePublishings

find_stat_shortcode(shortcode_or_id='trosamf', get_singles=True, get_publishings=True, get_publishing_specifics=True)

Find the data for a statistical product by searching by its shortname.

Parameters:

  • shortcode_or_id (str) – The shortname for the statistical product. Defaults to “trosamf”.

  • get_singles (bool) – Get more single data. Defaults to True.

  • get_publishings (bool) – Get more publishing data. Defaults to True.

  • get_publishing_specifics (bool) – Get the specific publishings data as well. Defaults to True.

Returns:

A data structure containing the found data on the product.

Return type:

list[dict[str, Any]]

get_contacts()

Get all the contacts from the API.

Returns:

Each of the contacts in a list.

Return type:

list[Contacts]

get_singles_publishings(stat, shortcode_or_id='trosamf', get_singles=True, get_publishings=True, get_publishing_specifics=True)

Find the data for a statistical product by searching by its shortname.

Parameters:

  • stat (dict[str, Any]) – A single stat from the register.

  • shortcode_or_id (str) – The shortname for the statistical product. Defaults to “trosamf”.

  • get_singles (bool) – Get more single data. Defaults to True.

  • get_publishings (bool) – Get more publishing data. Defaults to True.

  • get_publishing_specifics (bool) – Get the specific publishings data as well. Defaults to True.

Returns:

A data structure containing the found data on the product.

Return type:

list[dict[str, Any]]

get_statistics_register()

Get the overview of all the statistical products from the API.

Warning: this may take a little time to fetch.

Returns:

The summary of all the products.

Return type:

dict[str, Any]

handle_children(children, t)

Handle children in the etree.

Parameters:

  • children (list[Element]) – The children to treat.

  • t (Element) – The XML element to convert.

Returns:

The python dictionary of the children part.

Return type:

dict[str, Any]

kwargs_specifics(nested)

Map fields in specifics to kwargs for the dataclass.

Parameters:

nested (dict[str, Any]) – The XML-datastructure to map.

Returns:

Cleaned up data-structure

Return type:

dict[str, Any]

parse_contact_single(entry)

Parses a dictionary entry into a Contact object.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed Kontakt object.

Return type:

Contact

parse_contacts(t)

Parse the content of contacts into Contact dataclasses.

Parameters:

t (Element) – The xml-element to look for contacts in.

Returns:

The parsed data inserted into the dataclasses.

Return type:

list[Contact]

parse_data_single(root)

Parses the root dictionary into a SinglePublishing object.

Parameters:

root (dict[str, Any]) – The root dictionary to parse.

Returns:

The parsed SinglePublishing object.

Return type:

SinglePublishing

parse_eierseksjon_single(entry)

Parses a dictionary entry into an Owningsection object.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed Owningsection object.

Return type:

Owningsection

parse_lang_text_single(entry)

Parses a dictionary entry into a LangText object.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed LangText object.

Return type:

LangText

parse_name_single(entry)

Parses a dictionary entry into a Name object.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed Name object.

Return type:

Name

parse_single_stat_from_englishjson(stat)

Insert data-parts from the english json endpoint into SinglePublishing object.

Parameters:

stat (dict[str, Any]) – The datapart that represents the statistic.

Returns:

A SinglePublishing object with inserted data.

Return type:

SinglePublishing

parse_triggerord_single(entry)

Parses a dictionary entry into a trigger word dictionary.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed trigger word dictionary.

Return type:

dict

parse_variant_single(entry)

Parses a dictionary entry into a Variant object.

Parameters:

entry (dict[str, Any]) – The dictionary entry to parse.

Returns:

The parsed Variant object.

Return type:

Variant

raise_on_missing_future_publish(shortname, raise_error=True)

Check the next time the product should be published. Possibly raising an error.

Parameters:

  • shortname (str) – The shortname for the statistical product to look for.

  • raise_error (bool) – Set to False, if you just want to log that statistical product has no future publishings.

Returns:

Time until next publishing.

Return type:

datetime.timedelta

sections_publishings(section_code, include_ceased=False, get_publishings=True, get_publishing_specifics=True)

Get the publishings for a specific owning section at statistics norway.

Parameters:

  • section_code (str | int) – The three digit numeric code for the section.

  • include_ceased (bool) – Set to True if you want to include statistical products that have ceased publiscation. Defaults to False.

  • get_publishings (bool) – Get more data about all the publishings. Defaults to True.

  • get_publishing_specifics (bool) – Get more data about every single publishing. Defaults to True.

Returns:

A list of the sections statistical products.

Return type:

list[SinglePublishing]

single_stat(stat_id='4922')

Get the metadata for specific product.

Parameters:

stat_id (str) – The ID for the product in statistikkregisteret. Defaults to “4922”.

Returns:

Datastructure with the found metadata.

Return type:

SinglePublishing

specific_publishing(publish_id='162143')

Get the publishing-data from a specific publishing-ID in statistikkregisteret.

Parameters:

publish_id (str) – The API-ID for the publishing. Defaults to “162143”.

Returns:

The metadata found for the specific publishing.

Return type:

PublishingSpecifics

time_until_publishing(shortname='trosamf')

Calculate the time between now and the publishing.

Returns a negative timedelta, if there is no future publishing recorded.

Parameters:

shortname (str) – The shortcode to look for in the API among the publishings. Defaults to “trosamf”.

Returns:

The time difference between now, and the latest publishing date.

If no publishingdata is found, returns None.

Return type:

datetime.timedelta | None

fagfunksjoner.api.valuta module

class Attribute(id, name, description, relationship, role, values)

Bases: object

Represents an attribute within the dataset.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • relationship (dict[str, list[str]])

  • role (str | None)

  • values (list[dict[str, str]])

id

The identifier of the attribute.

name

The name of the attribute.

description

The description of the attribute.

relationship

The relationship of the attribute to dimensions.

role

The role of the attribute (if any).

values

The values associated with the attribute.

description: str
id: str
name: str
relationship: dict[str, list[str]]
role: str | None
values: list[dict[str, str]]
class Data(dataSets, structure)

Bases: object

Represents the data part of the dataset.

Parameters:
dataSets

A list of datasets.

structure

The structure of the dataset.

dataSets: list[DataSet]
structure: Structure
class DataSet(links, reportingBegin, reportingEnd, action, series)

Bases: object

Represents a dataset.

Parameters:

  • links (list[Link])

  • reportingBegin (str)

  • reportingEnd (str)

  • action (str)

  • series (dict[str, Series])

A list of related links.

reportingBegin

The start date of the reporting period.

reportingEnd

The end date of the reporting period.

action

The action associated with the dataset.

series

The series within the dataset.

action: str
links: list[Link]
reportingBegin: str
reportingEnd: str
series: dict[str, Series]
class Dimension(id, name, description, keyPosition, role, values)

Bases: object

Represents a dimension within the dataset.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • keyPosition (int)

  • role (str | None)

  • values (list[dict[str, str]])

id

The identifier of the dimension.

name

The name of the dimension.

description

The description of the dimension.

keyPosition

The key position of the dimension in the dataset.

role

The role of the dimension (if any).

values

The values associated with the dimension.

description: str
id: str
keyPosition: int
name: str
role: str | None
values: list[dict[str, str]]

Bases: object

Represents a hyperlink related to the dataset.

Parameters:

  • rel (str)

  • href (str | None)

  • uri (str | None)

  • urn (str | None)

rel

The relationship type of the link.

href

The URL of the link (if available).

uri

The URI of the link (if available).

urn

The URN of the link (if available).

href: str | None = None
rel: str
uri: str | None = None
urn: str | None = None
class Observation(id, name, description, keyPosition, role, values)

Bases: object

Represents an observation within the dataset.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • keyPosition (int)

  • role (str | None)

  • values (list[dict[str, str | float]])

id

The identifier of the observation.

name

The name of the observation.

description

The description of the observation.

keyPosition

The key position of the observation in the dataset.

role

The role of the observation (if any).

values

The values associated with the observation.

description: str
id: str
keyPosition: int
name: str
role: str | None
values: list[dict[str, str | float]]
class Receiver(id)

Bases: object

Represents the receiver of the dataset.

Parameters:

id (str)

id

The identifier of the receiver.

id: str
class Sender(id)

Bases: object

Represents the sender of the dataset.

Parameters:

id (str)

id

The identifier of the sender.

id: str
class Series(attributes, observations)

Bases: object

Represents a series within the dataset.

Parameters:

  • attributes (list[int])

  • observations (dict[str, list[str]])

attributes

The attributes of the series.

observations

The observations within the series.

attributes: list[int]
observations: dict[str, list[str]]
class Structure(links, name, names, description, descriptions, dimensions, attributes)

Bases: object

Represents the structure of the dataset.

Parameters:

  • links (list[Link])

  • name (str)

  • names (dict[str, str])

  • description (str)

  • descriptions (dict[str, str])

  • dimensions (dict[str, list[Dimension]])

  • attributes (dict[str, list[Attribute]])

A list of related links.

name

The name of the structure.

names

A dictionary of names in different languages.

description

The description of the structure.

descriptions

A dictionary of descriptions in different languages.

dimensions

The dimensions of the structure.

attributes

The attributes of the structure.

attributes: dict[str, list[Attribute]]
description: str
descriptions: dict[str, str]
dimensions: dict[str, list[Dimension]]
links: list[Link]
name: str
names: dict[str, str]
class ValutaData(meta, data, df=None)

Bases: object

Represents the entire dataset including metadata and data.

Parameters:
meta

The metadata of the dataset.

data

The data part of the dataset.

df

A DataFrame representation of the dataset (optional).

data: Data
df: DataFrame | None = None
meta: ValutaMeta
class ValutaMeta(id, prepared, test, datasetId, sender, receiver, links)

Bases: object

Metadata related to the dataset.

Parameters:

  • id (str)

  • prepared (str)

  • test (bool)

  • datasetId (str)

  • sender (Sender)

  • receiver (Receiver)

  • links (list[Link])

id

The identifier of the metadata.

prepared

The preparation timestamp of the metadata.

test

Indicates if the dataset is a test.

datasetId

The identifier of the dataset.

sender

The sender of the dataset.

receiver

The receiver of the dataset.

A list of related links.

datasetId: str
id: str
links: list[Link]
prepared: str
receiver: Receiver
sender: Sender
test: bool
create_dataframe(data_obj, structure_obj)

Create a DataFrame from data and structure objects.

Parameters:

  • data_obj (Data) – The data object containing datasets.

  • structure_obj (Structure) – The structure object containing dimensions and attributes.

Returns:

A pandas DataFrame created from the data and structure objects.

Return type:

pd.DataFrame

download_exchange_rates(currency='', frequency='M', date_from='2021-01-01', date_to=None, language='no', detail='full')

Fetch exchange rates from Norges Bank’s API.

See https://app.norges-bank.no/query/index.html#/no/

Parameters:

  • currency (str) – Specified in UPPER case letters. For multiple currencies, use a plus sign (e.g., ‘GBP+EUR+USD’). No value gives all currencies.

  • frequency (str) – Can be B (Business, daily rates), M (monthly rates), A (annual rates). For multiple frequencies, use a plus sign (e.g., ‘A+M’). No value gives all frequencies. For annual rates, the time interval must cover a full year, similarly for months.

  • date_from (str) – Specified in the format YYYY-MM-DD.

  • date_to (None | str) – Specified in the format YYYY-MM-DD. If None, defaults to today’s date.

  • language (str) – ‘no’ for Norwegian, ‘en’ for English.

  • detail (str) – ‘full’ gives both data and attributes, ‘dataonly’ gives only data, ‘serieskeysonly’ gives series without data or attributes, ‘nodata’ gives series and attributes without data.

Returns:

The data retrieved from the API, parsed into a ValutaData object.

Return type:

ValutaData

make_single_dataframe_record(series_key, series_val, obs_key, obs_value, structure_obj)

Create a single record for a pandas DataFrame from a series and observation.

This function generates a dictionary representing a single row in a pandas DataFrame based on the series key, series value, observation key, observation value, and the structure object of the dataset.

Parameters:

  • series_key (str) – The key representing the series in the dataset.

  • series_val (Series) – The series object containing attributes and observations.

  • obs_key (str) – The key representing the specific observation in the series.

  • obs_value (list[str]) – The list of values corresponding to the observation.

  • structure_obj (Structure) – The structure object containing dataset dimensions and attributes.

Returns:

A dictionary representing a single record in the DataFrame.

Return type:

dict[str, str | float]

parse_datasets(datasets_data)

Parse the datasets section from data.

Parameters:

datasets_data (list[dict[str, Any]]) – Data containing datasets information.

Returns:

A list of DataSet dataclass instances.

Return type:

list[DataSet]

parse_response(json_data)

Convert the json response to a ValutaData object with nested dataclasses.

Parameters:

json_data (dict[str, Any]) – The response from the Norske Bank API.

Returns:

An instance of the dataclass ValutaData.

Return type:

ValutaData

parse_structure(structure)

Parse the structure section from data.

Parameters:

structure (dict[str, Any]) – Data containing the structure information.

Returns:

An instance of the Structure dataclass.

Return type:

Structure

Module contents

Module to facilitate talking to different APIs that SSB might be interested in.