Referencia de la API

Todo se exporta desde la raíz del paquete, y cada conjunto de datos tiene además su propio entry point:

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

// Solo lo que usas: los tipos de interés por sí solos ocupan unos pocos kilobytes
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	Contenido
belgica	Todo lo de abajo, salvo los límites de los cantones
belgica/territory	Áreas judiciales, distritos judiciales, cantones, municipios, provincias, regiones
belgica/canton-boundaries	La geometría de los cantones, y findCantonsAt
belgica/courts	Tribunales, y los helpers de contacto
belgica/prisons	Prisiones, y los helpers de contacto
belgica/houses-of-justice	Maisons de justice, y los helpers de contacto
belgica/interest-rates	Tipos de interés
belgica/postal-codes	Códigos postales, con los municipios a los que pertenecen
belgica/data/*.json	Los archivos de datos sin procesar
belgica/schema/*.schema.json	JSON Schemas
belgica/datapackage.json	Descriptor del data package

Convenciones:

• Las búsquedas por id devuelven undefined cuando nada coincide; las funciones de lista devuelven un array vacío.
• Las funciones solo lanzan errores ante una entrada no válida: un día mal formado, o un día anterior a la cobertura de los datos (RangeError). Nunca por datos que faltan.
• Toda búsqueda acepta un día opcional, { on: '2025-06-01' } o un Date, y sin él responde para hoy. Una búsqueda por id siempre encuentra un registro conocido: la versión de hoy, o la última de un registro que ha terminado. Ver tiempo.
• Los conjuntos de datos exportados son readonly: cópialos antes de ordenarlos o modificarlos ([...courts].sort()).
• Una búsqueda con un id conocido (un literal como 'gent-1', o un valor de tipo CantonId) devuelve el propio registro, nunca undefined. Cualquier otra cadena devuelve Record | undefined. Ver identificadores.

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': Bruselas no tiene provincia, es el código de la región

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 Región de Bruselas-Capital no es 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 versión de ese día
getCanton('gent-1', { on: '2020-01-01' }) // RangeError: los datos describen la situación desde 2025-01-01

getCantonsForMunicipality(id)

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

Los cantones que cubren un municipio en un día, hoy por defecto. Un cantón para la mayoría de los municipios; varios para las ciudades divididas (Antwerpen, Gent, Brussel, …). Entonces decide la dirección postal, y el territory de cada cantón describe su 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

El distrito judicial en el que está un municipio, por código REFNIS. Cada municipio está exactamente en uno, incluso una ciudad dividida entre varios cantones.

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

getProvinceForMunicipality(id)

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

La provincia en la que está un municipio, por código REFNIS. undefined para los 19 municipios de la Región de Bruselas-Capital, que no tiene provincia, y para un código desconocido.

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'

Límites de los cantones

Solo en belgica/canton-boundaries: la geometría tiene alrededor de un millón de posiciones, así que la raíz del paquete no la reexporta (sí sus tipos). Ver la página de datos.

findCantonsAt(longitude, latitude)

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

Los cantones cuyo límite contiene un punto, en un día (hoy por defecto). Primero la longitud, luego la latitud, en grados decimales (WGS 84), en el orden de GeoJSON. Un cantón para un punto en Bélgica; ninguno fuera; dos para un punto en la línea entre dos cantones. Lanza un RangeError para coordenadas que no son números finitos.

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

getCantonBoundary(cantonId)

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

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

Tribunales

getCourt(id)

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

Un tribunal, una división o una sede. Los ids son el type del tribunal seguido del lugar: 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

La justice de paix (vredegerecht, el juzgado de paz del cantón) de un cantón. Cada cantón tiene una. Una justice de paix con sede en varios lugares (Philippeville, en Couvin y Florennes) no tiene dirección ni contactos propios: los tienen sus sedes, ver getDivisions.

const [canton] = getCantonsForMunicipality('44088')
getJusticeOfThePeace(canton.id).address // el tribunal de Merelbeke-Melle

getDivisions(courtId)

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

Las divisiones de un tribunal, o las sedes de una justice de paix con sede en varios lugares, en un día (hoy por defecto); vacío para un tribunal que no tiene.

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

getCourtsForCanton(cantonId)

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

Los tribunales cuya área contiene un cantón en un día (hoy por defecto): su justice de paix y, de cada otro tipo, el tribunal que lo cubre (el tribunal en su conjunto, no sus divisiones); en Bruselas, los dos tribunales lingüísticos de un tipo. Vacío para un cantón desconocido.

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

Los tribunales que cumplen todos los filtros dados y están vigentes en un día (hoy por defecto); un filtro vacío devuelve todos los tribunales de ese día.

findCourts({ type: 'enterprise-court', arrondissement: 'west-vlaanderen' }) // sus divisiones allí
findCourts({ type: 'court-of-appeal' }) // las cinco cours d'appel

Contactos

En cada entry point que tiene registros con contactos: la raíz, courts, prisons y houses-of-justice.

getContact(record, type, label?)

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

El valor del primer contacto de ese tipo, opcionalmente con esa etiqueta (la secretaría o el servicio, tal como lo nombra la fuente).

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

formatPhoneNumber(e164)

function formatPhoneNumber(e164: string): string

Un número belga en su forma escrita nacional. Lanza un RangeError para cualquier cosa que no sea un número belga en formato 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'

Prisiones

getPrison(id)

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

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

Maisons de justice

getHouseOfJustice(id)

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

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

Códigos postales

getPostalCode(id)

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

Un registro por id: el código postal y el código REFNIS unidos, '9000-44021'.

getMunicipalitiesForPostalCode(postalCode)

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

Los municipios a los que pertenece un código postal en un día (hoy por defecto): uno para casi todos los códigos; dos para 1040, 1050 y 1804, donde decide la calle. Los mismos registros Municipality que da getMunicipality. Vacío para un código desconocido.

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

Los códigos postales de un municipio en un día (hoy por defecto), por código REFNIS, en orden. Vacío para un código desconocido.

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

Competencia

Preguntas que combinan conjuntos de datos. Solo están en la raíz del paquete, ya que necesitan tanto el territorio como los tribunales.

findCourtsWithJurisdiction(municipalityId, type)

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

Los tribunales de un tipo competentes para un municipio en un día (hoy por defecto), por código REFNIS: los tribunales cuya área, tal como la fija la ley (cantons), contiene uno de los cantones del municipio. Un tribunal para la mayoría de los municipios; en Bruselas el tribunal neerlandófono y el francófono; para una ciudad dividida entre cantones, cada justice de paix que sirve a uno de ellos. Da el tribunal en su conjunto: qué división conoce de un asunto lo fija un real decreto y aún no está en los datos, así que elige entre getDivisions(court.id). Vacío para un código desconocido.

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 // el cantón cubre solo parte del municipio
}

Las justices de paix de un municipio en un día (hoy por defecto): una para la mayoría de los municipios, varias para una ciudad dividida entre cantones, donde decide la dirección postal y el territory de cada cantón dice qué parte cubre.

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

Los tribunales de un código postal en un día (hoy por defecto), por municipio: el código postal da el municipio (códigos postales), y el municipio sus justices de paix y sus tribunales del tipo pedido. Una entrada para casi todos los códigos; dos para 1040, 1050 y 1804, que pertenecen a dos municipios, de modo que la respuesta nunca se reduce a uno de ellos. Vacío para un código desconocido. En una ciudad dividida entre cantones, la calle sigue decidiendo entre las justices de paix, como 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']

Tipos de interés

getInterestRate(date, type, options?)

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

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

El tipo que se aplica en un día, o null cuando no hay ningún tipo registrado para él. Un Date se lee como un día del calendario local; una cadena debe empezar por un día YYYY-MM-DD válido (un timestamp ISO sirve, se ignora la hora).

Lanza un RangeError para cualquier otra cosa: '2013-1-15', '15/01/2013', '2013-02-30' o un Date no válido. Un tipo que falta es null; un día mal formado es un error, así que los dos casos no se pueden confundir.

contractAfter20130316 solo importa para el interés comercial entre 2013 y el 15 de marzo de 2015; por defecto se usa el tipo para los contratos más antiguos. Ver tipos de interés.

getLatestKnownRateDate(type)

function getLatestKnownRateDate(type: InterestType): string

El último día para el que hay un tipo registrado, YYYY-MM-DD.

Tiempo

Cada registro tiene un periodo de validez, y cada búsqueda acepta un día. Los helpers se exportan para tus propios registros.

interface Validity {
    validFrom?: string // primer día, YYYY-MM-DD; ausente: desde antes de la cobertura
    validTo?: string // último día; ausente: sigue vigente
}

interface OnDay {
    on?: Date | string // hoy por defecto; un Date se lee como un día local
}

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

Cada conjunto de datos dice a partir de qué día describe la situación; una búsqueda para un día anterior lanza un RangeError en lugar de responder con el mapa de hoy. El territorio y la lista de tribunales se derivan de la ley tal como quedó modificada para el 1 de enero de 2025; las prisiones y las maisons de justice se conocen desde el día en que se leyeron sus sitios por primera vez. Las versiones anteriores están previstas (#27).

Los arrays exportados (courts, prisons, …) contienen todas las versiones de todos los registros. Un registro que la fuente deja de mostrar no se borra: conserva su id y recibe un validTo, el día anterior a la comprobación semanal que no lo encontró. Uno que la fuente empieza a mostrar recibe un validFrom. Así, una búsqueda por id sin día devuelve la versión de hoy, o la última versión de un registro que ha terminado: comprueba validTo antes de presentar algo allí.

Conjuntos de datos

Los conjuntos de datos completos, con tipos:

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

Tipos

Tipo	Descrito en
JudicialAreaId, ArrondissementId, CantonId, RegionId, ProvinceId, MunicipalityId, CourtId, PrisonId, HouseOfJusticeId, PostalCodeId: unions de los ids de los datos, regenerados con ellos	Identificadores
Locale = 'nl' | 'fr' | 'de'
SourceRef = { url: string; retrieved: string }: de dónde proceden los datos de un registro	Calidad de los datos
Translated = Record<Locale, string>
Bilingual = Record<'nl' | 'fr', string>: nombres tal como los da el Code judiciaire
JudicialArea, Arrondissement, Canton, Region, Province, Municipality, LegalBasis, Validity, OnDay	Territorio
Court, CourtType, CourtFilter, Address, Contact, ContactType, CantonCourt	Tribunales
PostalCode, PostalCodeCourts	Códigos postales
Prison, HouseOfJustice	Prisiones, Maisons de justice
InterestType, InterestRatePeriod, InterestRateSeries, InterestRateResult	Tipos de interés