Dokumentacja API

Wszystko jest eksportowane z głównego punktu pakietu, a każdy zbiór danych ma też własny entry point:

import { getCanton, getInterestRate /* … */ } from 'belgica'

// Tylko to, czego używasz: same stopy procentowe to kilka kilobajtów
import { getInterestRate } from 'belgica/interest-rates'
import { getCourt, getJusticeOfThePeace } from 'belgica/courts'
import { getCanton, getCantonsForMunicipality } from 'belgica/territory'
import { findCantonsAt } from 'belgica/canton-boundaries'
import { getPrison } from 'belgica/prisons'
import { getHouseOfJustice } from 'belgica/houses-of-justice'
import { getMunicipalitiesForPostalCode } from 'belgica/postal-codes'

Entry point	Zawartość
belgica	Wszystko poniżej, z wyjątkiem granic kantonów
belgica/territory	Obszary sądowe, okręgi sądowe (arrondissements), kantony, gminy, prowincje, regiony
belgica/canton-boundaries	Geometria kantonów i findCantonsAt
belgica/courts	Sądy i funkcje pomocnicze do kontaktów
belgica/prisons	Więzienia i funkcje pomocnicze do kontaktów
belgica/houses-of-justice	Justitiehuizen / maisons de justice i funkcje pomocnicze do kontaktów
belgica/interest-rates	Stopy procentowe
belgica/postal-codes	Kody pocztowe, z gminami, do których należą
belgica/data/*.json	Surowe pliki z danymi
belgica/schema/*.schema.json	JSON Schema
belgica/datapackage.json	Deskryptor data package

Konwencje:

• Wyszukiwania po id zwracają undefined, gdy nic nie pasuje; funkcje zwracające listy zwracają pustą tablicę.
• Funkcje rzucają wyjątek tylko przy niepoprawnych danych wejściowych: błędnie zapisany dzień albo dzień sprzed zakresu danych (RangeError). Nigdy z powodu brakujących danych.
• Każde wyszukiwanie przyjmuje opcjonalny dzień, { on: '2025-06-01' } albo Date, a bez niego odpowiada dla dnia dzisiejszego. Wyszukiwanie po id zawsze znajduje znany rekord: dzisiejszą wersję albo ostatnią wersję rekordu, który wygasł. Zobacz czas.
• Eksportowane zbiory danych są readonly: skopiuj je przed sortowaniem lub zmianą ([...courts].sort()).
• Wyszukiwanie ze znanym id (literał taki jak 'gent-1' albo wartość typu CantonId) zwraca sam rekord, nigdy undefined. Każdy inny napis zwraca Record | undefined. Zobacz identyfikatory.

Terytorium

getJudicialArea(id)

function getJudicialArea(id: JudicialAreaId): JudicialArea
function getJudicialArea(id: string, options?: OnDay): JudicialArea | undefined

getArrondissement(id)

function getArrondissement(id: ArrondissementId): Arrondissement
function getArrondissement(id: string, options?: OnDay): Arrondissement | undefined

getArrondissement('oost-vlaanderen').name.fr // 'Flandre orientale'

getMunicipality(id)

function getMunicipality(id: MunicipalityId): Municipality
function getMunicipality(id: string, options?: OnDay): Municipality | undefined

getMunicipality('44021').name // { nl: 'Gent', fr: 'Gand' }
getMunicipality('44021').province // '40000'
getMunicipality('21004').province // '04000': Bruksela nie ma prowincji, to kod regionu

getRegion(id)

function getRegion(id: RegionId): Region
function getRegion(id: string, options?: OnDay): Region | undefined

getRegion('02000').name.fr // 'Région flamande'

getProvince(id)

function getProvince(id: ProvinceId): Province
function getProvince(id: string, options?: OnDay): Province | undefined

getProvince('40000').name.nl // 'Provincie Oost-Vlaanderen'
getProvince('40000').region // '02000'
getProvince('04000') // undefined: Region Stołeczny Brukseli nie jest prowincją

getCanton(id)

function getCanton(id: CantonId): Canton
function getCanton(id: string, options?: OnDay): Canton | undefined

getCanton('oudergem').seat.nl // 'Etterbeek'
getCanton('gent-1', { on: '2025-06-01' }) // wersja z tego dnia
getCanton('gent-1', { on: '2020-01-01' }) // RangeError: dane opisują stan od 2025-01-01

getCantonsForMunicipality(id)

function getCantonsForMunicipality(id: string, options?: OnDay): Canton[]

Kantony obejmujące gminę w danym dniu, domyślnie dziś. Jeden kanton dla większości gmin; kilka dla miast podzielonych (Antwerpen, Gent, Brussel, …). Wtedy rozstrzyga adres z ulicą, a territory każdego kantonu opisuje jego część.

getCantonsForMunicipality('44088').map((c) => c.id) // ['merelbeke-melle']
getCantonsForMunicipality('44021').map((c) => c.id) // ['gent-1', 'gent-2', 'gent-3', 'gent-4', 'gent-5']

getArrondissementForMunicipality(id)

function getArrondissementForMunicipality(id: string, options?: OnDay): Arrondissement | undefined

Okręg sądowy (arrondissement), w którym leży gmina, po kodzie REFNIS. Każda gmina leży w dokładnie jednym, nawet miasto podzielone między kilka kantonów.

getArrondissementForMunicipality('44021')?.id // 'oost-vlaanderen'

getProvinceForMunicipality(id)

function getProvinceForMunicipality(id: string, options?: OnDay): Province | undefined

Prowincja, w której leży gmina, po kodzie REFNIS. undefined dla 19 gmin Regionu Stołecznego Brukseli, który nie ma prowincji, oraz dla nieznanego kodu.

getProvinceForMunicipality('44021')?.id // '40000'
getProvinceForMunicipality('21004') // undefined: Brussel

getRegionForMunicipality(id)

function getRegionForMunicipality(id: string, options?: OnDay): Region | undefined

getRegionForMunicipality('21004')?.name.nl // 'Brussels Hoofdstedelijk Gewest'

Granice kantonów

Tylko w belgica/canton-boundaries: geometria to około miliona pozycji, więc główny punkt pakietu jej nie reeksportuje (jej typy owszem). Zobacz stronę z danymi.

findCantonsAt(longitude, latitude)

function findCantonsAt(longitude: number, latitude: number, options?: OnDay): Canton[]

Kantony, których granica obejmuje punkt, w danym dniu (domyślnie dziś). Najpierw długość, potem szerokość geograficzna, w stopniach dziesiętnych (WGS 84), w kolejności GeoJSON. Jeden kanton dla punktu w Belgii; żaden poza nią; dwa dla punktu na linii między dwoma kantonami. Rzuca RangeError dla współrzędnych, które nie są skończonymi liczbami.

findCantonsAt(3.7268, 51.053).map((c) => c.id) // ['gent-1']: Sint-Baafskathedraal
findCantonsAt(2.3522, 48.8566) // []: Paryż

getCantonBoundary(cantonId)

function getCantonBoundary(id: CantonId): CantonBoundary
function getCantonBoundary(id: string, options?: OnDay): CantonBoundary | undefined

getCantonBoundary('gent-1').geometry.type // 'MultiPolygon'

Sądy

getCourt(id)

function getCourt(id: CourtId): Court
function getCourt(id: string, options?: OnDay): Court | undefined

Sąd, wydział lub siedziba. Id to type sądu, a po nim miejscowość: justice-of-the-peace-gent-1, police-court-brussel-fr, enterprise-court-gent-brugge.

getCourt('court-of-appeal-brussel').name // { nl: 'Hof van Beroep Brussel', fr: "Cour d'appel de Bruxelles" }

getJusticeOfThePeace(cantonId)

function getJusticeOfThePeace(cantonId: CantonId): Court
function getJusticeOfThePeace(cantonId: string, options?: OnDay): Court | undefined

Vredegerecht / justice de paix (sąd pokoju) kantonu. Każdy kanton ma jeden. Vredegerecht / justice de paix, który zasiada w kilku miejscach (Philippeville, w Couvin i Florennes), nie ma własnego adresu ani kontaktów: mają je jego siedziby, zobacz getDivisions.

const [canton] = getCantonsForMunicipality('44088')
getJusticeOfThePeace(canton.id).address // vredegerecht w Merelbeke-Melle

getDivisions(courtId)

function getDivisions(courtId: string, options?: OnDay): Court[]

Wydziały sądu albo siedziby vredegerecht / justice de paix, który zasiada w kilku miejscach, w danym dniu (domyślnie dziś); pusta tablica dla sądu, który ich nie ma.

getDivisions('labour-court-gent').map((c) => c.id) // ['labour-court-gent-aalst', …]

getCourtsForCanton(cantonId)

function getCourtsForCanton(cantonId: string, options?: OnDay): Court[]

Sądy, których obszar obejmuje kanton w danym dniu (domyślnie dziś): jego vredegerecht / justice de paix i, dla każdego innego typu, sąd, który go obejmuje (sąd jako całość, nie jego wydziały); w Brukseli oba sądy językowe danego typu. Pusta tablica dla nieznanego kantonu.

getCourtsForCanton('gent-1').map((c) => c.id)
// ['court-of-appeal-gent', 'court-of-assize-oost-vlaanderen', 'court-of-first-instance-oost-vlaanderen', …]

findCourts(filter)

function findCourts(
    filter: {
        type?: CourtType
        kind?: 'court' | 'division' | 'seat'
        arrondissement?: string
        judicialArea?: string
    },
    options?: OnDay,
): Court[]

Sądy, które spełniają każdy podany filtr i obowiązują w danym dniu (domyślnie dziś); pusty filtr zwraca wszystkie sądy z tego dnia.

findCourts({ type: 'enterprise-court', arrondissement: 'west-vlaanderen' }) // jego wydziały w tym okręgu
findCourts({ type: 'court-of-appeal' }) // pięć hoven van beroep / cours d'appel

Dane kontaktowe

W każdym entry poincie, który ma rekordy z kontaktami: w głównym, courts, prisons i houses-of-justice.

getContact(record, type, label?)

function getContact(
    record: { contacts: readonly Contact[] },
    type: 'phone' | 'fax' | 'email' | 'bank-account',
    label?: string,
): string | undefined

Wartość pierwszego kontaktu danego typu, opcjonalnie z daną etykietą (sekretariat lub służba, tak jak nazywa je źródło).

getContact(getCourt('court-of-appeal-liege'), 'email', 'Greffe pénal')
// 'liege.ca.greffepenal@just.fgov.be'

formatPhoneNumber(e164)

function formatPhoneNumber(e164: string): string

Belgijski numer w krajowej formie zapisu. Rzuca RangeError dla wszystkiego, co nie jest belgijskim numerem w formacie E.164.

formatPhoneNumber('+3292343210') // '09 234 32 10'
formatPhoneNumber('+3253820701') // '053 82 07 01'
formatPhoneNumber('+32470123456') // '0470 12 34 56'

formatIban(iban)

function formatIban(iban: string): string

formatIban('BE73679200844560') // 'BE73 6792 0084 4560'

Więzienia

getPrison(id)

function getPrison(id: PrisonId): Prison
function getPrison(id: string, options?: OnDay): Prison | undefined

getPrison('gevangenis-gent').name.fr // 'Prison de Gand'

Justitiehuizen / maisons de justice

getHouseOfJustice(id)

function getHouseOfJustice(id: HouseOfJusticeId): HouseOfJustice
function getHouseOfJustice(id: string, options?: OnDay): HouseOfJustice | undefined

getHouseOfJustice('justitiehuis-gent').ovo // 'OVO001917'

Kody pocztowe

getPostalCode(id)

function getPostalCode(id: PostalCodeId): PostalCode
function getPostalCode(id: string, options?: OnDay): PostalCode | undefined

Rekord po id: kod pocztowy i kod REFNIS połączone, '9000-44021'.

getMunicipalitiesForPostalCode(postalCode)

function getMunicipalitiesForPostalCode(postalCode: string, options?: OnDay): Municipality[]

Gminy, do których należy kod pocztowy w danym dniu (domyślnie dziś): jedna dla niemal każdego kodu; dwie dla 1040, 1050 i 1804, gdzie rozstrzyga ulica. Te same rekordy Municipality, które zwraca getMunicipality. Pusta tablica dla nieznanego kodu.

getMunicipalitiesForPostalCode('9050').map((m) => m.name.nl) // ['Gent']
getMunicipalitiesForPostalCode('1040').map((m) => m.name.nl) // ['Brussel', 'Etterbeek']
getMunicipalitiesForPostalCode('0000') // []

getPostalCodes(municipalityId)

function getPostalCodes(municipalityId: string, options?: OnDay): PostalCode[]

Kody pocztowe gminy w danym dniu (domyślnie dziś), po kodzie REFNIS, w kolejności. Pusta tablica dla nieznanego kodu.

getPostalCodes('44021').map((p) => p.postalCode) // ['9000', '9030', '9031', …]

Właściwość

Pytania łączące kilka zbiorów danych. Są tylko w głównym punkcie pakietu, bo potrzebują zarówno terytorium, jak i sądów.

findCourtsWithJurisdiction(municipalityId, type)

function findCourtsWithJurisdiction(
    municipalityId: string,
    type: CourtType,
    options?: OnDay,
): Court[]

Sądy danego typu właściwe dla gminy w danym dniu (domyślnie dziś), po kodzie REFNIS: sądy, których obszar, tak jak określa go ustawa (cantons), obejmuje jeden z kantonów gminy. Jeden sąd dla większości gmin; w Brukseli sąd niderlandzkojęzyczny i francuskojęzyczny; dla miasta podzielonego między kantony każdy vredegerecht / justice de paix, który obsługuje jeden z nich. Zwraca sąd jako całość: który z jego wydziałów rozpatruje sprawę, ustala dekret królewski, którego jeszcze nie ma w danych, więc wybierz spośród getDivisions(court.id). Pusta tablica dla nieznanego kodu.

findCourtsWithJurisdiction('23088', 'police-court').map((c) => c.id) // ['police-court-vilvoorde']
findCourtsWithJurisdiction('21004', 'court-of-first-instance').map((c) => c.id)
// ['court-of-first-instance-brussel-fr', 'court-of-first-instance-brussel-nl']
findCourtsWithJurisdiction('44021', 'labour-court').map((c) => c.id) // ['labour-court-gent']

findJusticesOfThePeace(municipalityId)

function findJusticesOfThePeace(municipalityId: string, options?: OnDay): CantonCourt[]

interface CantonCourt {
    canton: Canton
    court: Court
    partial: boolean // kanton obejmuje tylko część gminy
}

Vredegerechten / justices de paix dla gminy w danym dniu (domyślnie dziś): jeden dla większości gmin, kilka dla miasta podzielonego między kantony, gdzie rozstrzyga adres z ulicą, a territory każdego kantonu mówi, którą część obejmuje.

findJusticesOfThePeace('44088')
// [{ canton: { id: 'merelbeke-melle', … }, court: { id: 'justice-of-the-peace-merelbeke-melle', … }, partial: false }]

findJusticesOfThePeace('44021').map((c) => c.canton.id) // ['gent-1', 'gent-2', 'gent-3', 'gent-4', 'gent-5']

findCourtsForPostalCode(postalCode, type)

function findCourtsForPostalCode(
    postalCode: string,
    type: CourtType,
    options?: OnDay,
): PostalCodeCourts[]

interface PostalCodeCourts {
    municipality: Municipality
    justicesOfThePeace: CantonCourt[] // findJusticesOfThePeace(municipality.id)
    courts: Court[] // findCourtsWithJurisdiction(municipality.id, type)
}

Sądy dla kodu pocztowego w danym dniu (domyślnie dziś), osobno dla każdej gminy: kod pocztowy wskazuje gminę (kody pocztowe), a gmina jej vredegerechten / justices de paix i jej sądy żądanego typu. Jeden wpis dla niemal każdego kodu; dwa dla 1040, 1050 i 1804, które należą do dwóch gmin, więc odpowiedź nigdy nie jest sprowadzana do jednej z nich. Pusta tablica dla nieznanego kodu. W mieście podzielonym między kantony między vredegerechten nadal rozstrzyga ulica, tak jak w findJusticesOfThePeace.

findCourtsForPostalCode('9050', 'labour-court')
// [{ municipality: { id: '44021', … }, justicesOfThePeace: [gent-1 … gent-5], courts: [labour-court-gent] }]

findCourtsForPostalCode('1040', 'police-court').map((r) => r.municipality.name.nl) // ['Brussel', 'Etterbeek']

Stopy procentowe

getInterestRate(date, type, options?)

function getInterestRate(
    date: Date | string,
    type: InterestType,
    options?: { contractAfter20130316?: boolean },
): InterestRateResult | null

interface InterestRateResult {
    rate: number // procent
    period: { from: string; to: string }
}

Stopa obowiązująca w danym dniu albo null, gdy w danych nie ma dla niego stopy. Date jest odczytywane jako lokalny dzień kalendarzowy; napis musi zaczynać się od poprawnego dnia YYYY-MM-DD (znacznik czasu ISO jest w porządku, jego godzina jest ignorowana).

Rzuca RangeError dla wszystkiego innego: '2013-1-15', '15/01/2013', '2013-02-30' albo niepoprawnej Date. Brakująca stopa to null; błędnie zapisany dzień to błąd, więc tych dwóch przypadków nie da się pomylić.

contractAfter20130316 ma znaczenie tylko dla odsetek handlowych od 2013 roku do 15 marca 2015; domyślnie używana jest stopa dla starszych umów. Zobacz stopy procentowe.

getLatestKnownRateDate(type)

function getLatestKnownRateDate(type: InterestType): string

Ostatni dzień, dla którego w danych jest stopa, YYYY-MM-DD.

Czas

Każdy rekord ma okres obowiązywania, a każde wyszukiwanie przyjmuje dzień. Funkcje pomocnicze są eksportowane na potrzeby twoich własnych rekordów.

interface Validity {
    validFrom?: string // pierwszy dzień, YYYY-MM-DD; brak: od czasu sprzed zakresu
    validTo?: string // ostatni dzień; brak: nadal obowiązuje
}

interface OnDay {
    on?: Date | string // domyślnie dziś; Date jest odczytywane jako lokalny dzień
}

const territoryCoverage: { from: '2025-01-01' }
const courtsCoverage: { from: '2025-01-01' }
const prisonsCoverage: { from: '2026-10-20' }
const housesOfJusticeCoverage: { from: '2026-10-20' }
const postalCodesCoverage: { from: '2025-01-01' }

function appliesOn(record: Validity, day: string): boolean
function toDay(date: Date | string): string // 'YYYY-MM-DD' albo RangeError

Każdy zbiór danych podaje, od którego dnia opisuje stan rzeczy; wyszukiwanie dla wcześniejszego dnia rzuca RangeError, zamiast odpowiadać dzisiejszą mapą. Terytorium i lista sądów wynikają z ustawy w brzmieniu obowiązującym 1 stycznia 2025; więzienia i justitiehuizen / maisons de justice są znane od dnia, w którym ich strony zostały odczytane po raz pierwszy. Wcześniejsze wersje są planowane (#27).

Eksportowane tablice (courts, prisons, …) zawierają każdą wersję każdego rekordu. Rekord, którego źródło przestaje wymieniać, nie jest usuwany: zachowuje swoje id i dostaje validTo, dzień przed cotygodniową kontrolą, która go nie znalazła. Rekord, który źródło zaczyna wymieniać, dostaje validFrom. Dlatego wyszukiwanie po id bez dnia zwraca dzisiejszą wersję albo ostatnią wersję rekordu, który wygasł: sprawdź validTo, zanim coś tam złożysz.

Zbiory danych

Pełne zbiory danych, z typami:

Eksport	Typ
judicialAreas	readonly JudicialArea[]
arrondissements	readonly Arrondissement[]
cantons	readonly Canton[]
regions	readonly Region[]
provinces	readonly Province[]
municipalities	readonly Municipality[]
courts	readonly Court[]
prisons	readonly Prison[]
housesOfJustice	readonly HouseOfJustice[]
postalCodes	readonly PostalCode[]
interestRates	Readonly<Record<InterestType, InterestRateSeries>>

Typy

Typ	Opisane na stronie
JudicialAreaId, ArrondissementId, CantonId, RegionId, ProvinceId, MunicipalityId, CourtId, PrisonId, HouseOfJusticeId, PostalCodeId: unie id występujących w danych, generowane razem z nimi	Identyfikatory
Locale = 'nl' | 'fr' | 'de'
SourceRef = { url: string; retrieved: string }: skąd pochodzą dane rekordu	Jakość danych
Translated = Record<Locale, string>
Bilingual = Record<'nl' | 'fr', string>: nazwy w brzmieniu z Gerechtelijk Wetboek / Code judiciaire
JudicialArea, Arrondissement, Canton, Region, Province, Municipality, LegalBasis, Validity, OnDay	Terytorium
Court, CourtType, CourtFilter, Address, Contact, ContactType, CantonCourt	Sądy
PostalCode, PostalCodeCourts	Kody pocztowe
Prison, HouseOfJustice	Więzienia, Justitiehuizen / maisons de justice
InterestType, InterestRatePeriod, InterestRateSeries, InterestRateResult	Stopy procentowe