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.

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 statisticss, 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.

owner_name

The ownership section name.

owner_code

The ownership section code.

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.

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) – The identifier of the attribute.

  • name (str) – The name of the attribute.

  • description (str) – The description of the attribute.

  • relationship (dict[str, list[str]]) – The relationship of the attribute to dimensions.

  • role (str | None) – The role of the attribute (if any).

  • values (list[dict[str, str]]) – 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 (list[DataSet]) – A list of datasets.

  • structure (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]) – A list of related links.

  • reportingBegin (str) – The start date of the reporting period.

  • reportingEnd (str) – The end date of the reporting period.

  • action (str) – The action associated with the dataset.

  • series (dict[str, Series]) – The series within the dataset.

action: str
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) – The identifier of the dimension.

  • name (str) – The name of the dimension.

  • description (str) – The description of the dimension.

  • keyPosition (int) – The key position of the dimension in the dataset.

  • role (str | None) – The role of the dimension (if any).

  • values (list[dict[str, str]]) – 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) – The relationship type of the link.

  • href (str | None) – The URL of the link (if available).

  • uri (str | None) – The URI of the link (if available).

  • urn (str | None) – 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) – The identifier of the observation.

  • name (str) – The name of the observation.

  • description (str) – The description of the observation.

  • keyPosition (int) – The key position of the observation in the dataset.

  • role (str | None) – The role of the observation (if any).

  • values (list[dict[str, str | float]]) – 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) – The identifier of the receiver.

id: str
class Sender(id)

Bases: object

Represents the sender of the dataset.

Parameters:

id (str) – The identifier of the sender.

id: str
class Series(attributes, observations)

Bases: object

Represents a series within the dataset.

Parameters:

  • attributes (list[int]) – The attributes of the series.

  • observations (dict[str, list[str]]) – 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]) – A list of related links.

  • name (str) – The name of the structure.

  • names (dict[str, str]) – A dictionary of names in different languages.

  • description (str) – The description of the structure.

  • descriptions (dict[str, str]) – A dictionary of descriptions in different languages.

  • dimensions (dict[str, list[Dimension]]) – The dimensions of the structure.

  • attributes (dict[str, list[Attribute]]) – The attributes of the structure.

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

Bases: object

Represents the entire dataset including metadata and data.

Parameters:

  • meta (ValutaMeta) – The metadata of the dataset.

  • data (Data) – The data part of the dataset.

  • df (DataFrame | None) – 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) – The identifier of the metadata.

  • prepared (str) – The preparation timestamp of the metadata.

  • test (bool) – Indicates if the dataset is a test.

  • datasetId (str) – The identifier of the dataset.

  • sender (Sender) – The sender of the dataset.

  • receiver (Receiver) – The receiver of the dataset.

  • links (list[Link]) – A list of related links.

datasetId: str
id: str
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.