Riferimento API

Tutto viene esportato dalla root del package, e ogni dataset ha anche il proprio entry point:

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

// Solo ciò che usi: i tassi d'interesse da soli pesano pochi kilobyte
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	Contenuto
belgica	Tutto ciò che segue, tranne i confini dei cantoni
belgica/territory	Distretti giudiziari, arrondissement, cantoni, comuni, province, regioni
belgica/canton-boundaries	La geometria dei cantoni, e findCantonsAt
belgica/courts	Corti e tribunali, e gli helper per i contatti
belgica/prisons	Carceri, e gli helper per i contatti
belgica/houses-of-justice	Justitiehuizen / maisons de justice, e gli helper per i contatti
belgica/interest-rates	Tassi d'interesse
belgica/postal-codes	Codici postali, con i comuni a cui appartengono
belgica/data/*.json	I file di dati grezzi
belgica/schema/*.schema.json	JSON Schema
belgica/datapackage.json	Descrittore del data package

Convenzioni:

• Le ricerche per id restituiscono undefined quando nulla corrisponde; le funzioni che restituiscono elenchi restituiscono un array vuoto.
• Le funzioni lanciano errori solo per input non valido: un giorno malformato, o un giorno precedente alla copertura dei dati (RangeError). Mai per dati mancanti.
• Ogni ricerca accetta un giorno facoltativo, { on: '2025-06-01' } o un Date, e senza di esso risponde per oggi. Una ricerca per id trova sempre un record noto: la versione di oggi, o l'ultima di un record che è terminato. Vedi tempo.
• I dataset esportati sono readonly: copiali prima di ordinarli o modificarli ([...courts].sort()).
• Una ricerca con un id noto (un letterale come 'gent-1', o un valore di tipo CantonId) restituisce il record stesso, mai undefined. Qualsiasi altra stringa restituisce Record | undefined. Vedi identificatori.

Territorio

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': Bruxelles non ha province, è il codice della regione

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: la Regione di Bruxelles-Capitale non è una provincia

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' }) // la versione di quel giorno
getCanton('gent-1', { on: '2020-01-01' }) // RangeError: i dati descrivono la situazione dal 2025-01-01

getCantonsForMunicipality(id)

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

I cantoni che coprono un comune in un dato giorno, per impostazione predefinita oggi. Un solo cantone per la maggior parte dei comuni; più cantoni per le città suddivise (Antwerpen, Gent, Brussel, …). In quel caso decide l'indirizzo, e il territory di ogni cantone descrive la sua parte.

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

L'arrondissement giudiziario in cui si trova un comune, per codice REFNIS. Ogni comune si trova in esattamente uno, anche una città suddivisa tra più cantoni.

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

getProvinceForMunicipality(id)

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

La provincia in cui si trova un comune, per codice REFNIS. undefined per i 19 comuni della Regione di Bruxelles-Capitale, che non ha province, e per un codice sconosciuto.

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'

Confini dei cantoni

Solo in belgica/canton-boundaries: la geometria conta circa un milione di posizioni, quindi la root del package non la riesporta (i tipi invece sì). Vedi la pagina sui dati.

findCantonsAt(longitude, latitude)

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

I cantoni il cui confine contiene un punto, in un dato giorno (oggi per impostazione predefinita). Prima la longitudine, poi la latitudine, in gradi decimali (WGS 84), nell'ordine di GeoJSON. Un cantone per un punto in Belgio; nessuno al di fuori; due per un punto sulla linea tra due cantoni. Lancia un RangeError per coordinate che non sono numeri finiti.

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

getCantonBoundary(cantonId)

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

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

Corti e tribunali

getCourt(id)

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

Un tribunale, una sezione o una sede. Gli id sono il type del tribunale seguito dal luogo: 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

Il vredegerecht / justice de paix (giudice di pace) di un cantone. Ogni cantone ne ha uno. Un giudice di pace che ha sede in più luoghi (Philippeville, a Couvin e Florennes) non ha indirizzo né contatti propri: li hanno le sue sedi, vedi getDivisions.

const [canton] = getCantonsForMunicipality('44088')
getJusticeOfThePeace(canton.id).address // il giudice di pace di Merelbeke-Melle

getDivisions(courtId)

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

Le sezioni di un tribunale, o le sedi di un giudice di pace che ha sede in più luoghi, in un dato giorno (oggi per impostazione predefinita); vuoto per un tribunale che non ne ha.

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

getCourtsForCanton(cantonId)

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

I tribunali la cui area comprende un cantone in un dato giorno (oggi per impostazione predefinita): il suo giudice di pace e, per ciascun altro tipo, il tribunale che lo copre (il tribunale nel suo insieme, non le sue sezioni); a Bruxelles entrambi i tribunali linguistici di un tipo. Vuoto per un cantone sconosciuto.

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[]

I tribunali che soddisfano tutti i filtri indicati e sono validi in un dato giorno (oggi per impostazione predefinita); un filtro vuoto restituisce tutti i tribunali di quel giorno.

findCourts({ type: 'enterprise-court', arrondissement: 'west-vlaanderen' }) // le sue sezioni lì
findCourts({ type: 'court-of-appeal' }) // le cinque corti d'appello

Contatti

In ogni entry point che contiene record con contatti: la root, courts, prisons e houses-of-justice.

getContact(record, type, label?)

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

Il valore del primo contatto di quel tipo, facoltativamente con quell'etichetta (la cancelleria o il servizio, come lo nomina la fonte).

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

formatPhoneNumber(e164)

function formatPhoneNumber(e164: string): string

Un numero belga nella sua forma scritta nazionale. Lancia un RangeError per qualsiasi cosa che non sia un numero belga in forma 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'

Carceri

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'

Codici postali

getPostalCode(id)

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

Un record per id: il codice postale e il codice REFNIS uniti, '9000-44021'.

getMunicipalitiesForPostalCode(postalCode)

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

I comuni a cui appartiene un codice postale in un dato giorno (oggi per impostazione predefinita): uno per quasi tutti i codici; due per 1040, 1050 e 1804, dove decide la via. Gli stessi record Municipality restituiti da getMunicipality. Vuoto per un codice sconosciuto.

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[]

I codici postali di un comune in un dato giorno (oggi per impostazione predefinita), per codice REFNIS, in ordine. Vuoto per un codice sconosciuto.

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

Competenza

Domande che combinano più dataset. Si trovano solo nella root del package, perché richiedono sia il territorio sia i tribunali.

findCourtsWithJurisdiction(municipalityId, type)

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

I tribunali di un tipo competenti per un comune in un dato giorno (oggi per impostazione predefinita), per codice REFNIS: i tribunali la cui area, come la stabilisce la legge (cantons), comprende uno dei cantoni del comune. Un solo tribunale per la maggior parte dei comuni; a Bruxelles il tribunale di lingua neerlandese e quello di lingua francese; per una città suddivisa tra cantoni, ogni giudice di pace che ne serve uno. Restituisce il tribunale nel suo insieme: quale delle sue sezioni tratta una causa è stabilito da un regio decreto e non è ancora nei dati, quindi scegli tra getDivisions(court.id). Vuoto per un codice sconosciuto.

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 // il cantone copre solo una parte del comune
}

I giudici di pace per un comune in un dato giorno (oggi per impostazione predefinita): uno per la maggior parte dei comuni, più d'uno per una città suddivisa tra cantoni, dove decide l'indirizzo e il territory di ogni cantone dice quale parte copre.

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)
}

I tribunali per un codice postale in un dato giorno (oggi per impostazione predefinita), per comune: il codice postale dà il comune (codici postali), il comune i suoi giudici di pace e i suoi tribunali del tipo richiesto. Una voce per quasi tutti i codici; due per 1040, 1050 e 1804, che appartengono a due comuni, così la risposta non viene mai ridotta a uno solo di essi. Vuoto per un codice sconosciuto. In una città suddivisa tra cantoni è comunque la via a decidere tra i giudici di pace, come con 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']

Tassi d'interesse

getInterestRate(date, type, options?)

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

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

Il tasso applicabile in un giorno, oppure null quando per quel giorno non c'è un tasso noto. Un Date viene letto come giorno di calendario locale; una stringa deve iniziare con un giorno YYYY-MM-DD valido (un timestamp ISO va bene, l'ora viene ignorata).

Lancia un RangeError per qualsiasi altra cosa: '2013-1-15', '15/01/2013', '2013-02-30' o un Date non valido. Un tasso mancante è null; un giorno malformato è un errore, così i due casi non si possono confondere.

contractAfter20130316 conta solo per l'interesse commerciale tra il 2013 e il 15 marzo 2015; per impostazione predefinita si usa il tasso per i contratti più vecchi. Vedi tassi d'interesse.

getLatestKnownRateDate(type)

function getLatestKnownRateDate(type: InterestType): string

L'ultimo giorno per cui è noto un tasso, YYYY-MM-DD.

Tempo

Ogni record ha un periodo di validità, e ogni ricerca accetta un giorno. Gli helper sono esportati per i tuoi record.

interface Validity {
    validFrom?: string // primo giorno, YYYY-MM-DD; assente: da prima della copertura
    validTo?: string // ultimo giorno; assente: ancora valido
}

interface OnDay {
    on?: Date | string // oggi per impostazione predefinita; un Date viene letto come giorno locale
}

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', oppure un RangeError

Ogni dataset indica da quale giorno descrive la situazione; una ricerca per un giorno precedente lancia un RangeError invece di rispondere con la mappa di oggi. Il territorio e l'elenco dei tribunali derivano dalla legge come modificata per il 1° gennaio 2025; le carceri e le justitiehuizen / maisons de justice sono note dal giorno in cui i loro siti sono stati letti per la prima volta. Le versioni precedenti sono previste (#27).

Gli array esportati (courts, prisons, …) contengono ogni versione di ogni record. Un record che la fonte smette di elencare non viene cancellato: mantiene il suo id e riceve un validTo, il giorno prima del controllo settimanale che non l'ha trovato. Uno che la fonte inizia a elencare riceve un validFrom. Così una ricerca per id senza giorno restituisce la versione di oggi, o l'ultima versione di un record che è terminato: controlla validTo prima di depositare qualcosa lì.

Dataset

I dataset completi, tipizzati:

Export	Tipo
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>>

Tipi

Tipo	Descritto in
JudicialAreaId, ArrondissementId, CantonId, RegionId, ProvinceId, MunicipalityId, CourtId, PrisonId, HouseOfJusticeId, PostalCodeId: union degli id presenti nei dati, rigenerate insieme a essi	Identificatori
Locale = 'nl' | 'fr' | 'de'
SourceRef = { url: string; retrieved: string }: da dove provengono i dati di un record	Qualità dei dati
Translated = Record<Locale, string>
Bilingual = Record<'nl' | 'fr', string>: nomi come li indica il Gerechtelijk Wetboek / Code judiciaire
JudicialArea, Arrondissement, Canton, Region, Province, Municipality, LegalBasis, Validity, OnDay	Territorio
Court, CourtType, CourtFilter, Address, Contact, ContactType, CantonCourt	Corti e tribunali
PostalCode, PostalCodeCourts	Codici postali
Prison, HouseOfJustice	Carceri, Justitiehuizen
InterestType, InterestRatePeriod, InterestRateSeries, InterestRateResult	Tassi d'interesse