/** * @copyright Sister Software * @license AGPL-3.0 * @author Teffen Ellis, et al. * * `vlaanderen`: the INSPIRE Addresses (AD) theme of agentschap Digitaal Vlaanderen, read from a * local harvest of its WFS 2.0 download service at `https://geo.api.vlaanderen.be/ad/wfs`. * * Coverage is the Flemish Region rather than Belgium. Brussels and Wallonia publish the same theme * through their own services, so this adapter emits `BE` on every row it yields, and a Belgian build needs * two more sources beside it. * * The schema-level reading is `#inspire/address`, which owns every part of an `ad:Address` that the * publishers spell alike. This module holds only what is Flanders' own: the `resourceId` rewrite its * references need, the homonym discriminator its street names carry, and the lost characters its * values carry. * * The adapter records `Modellicentie voor gratis hergebruik Vlaanderen` on every row, the terms the * address-source register elects for `be-property-building-1` in `electedTerms`. Article 3 grants * reproduction, adaptation and commercial exploitation for any lawful purpose. Article 4 makes * attribution the only condition, in the form the licensor specifies, so the model card must carry * `Bron: Digitaal Vlaanderen`. * * The capabilities document's `ows:Fees` and `ows:AccessConstraints` state what calling the service * costs and who may call it. They describe the service rather than licensing the data, so the * license comes from the register and this adapter reads the capabilities for feature types alone. * * ## Why the input is a harvest rather than the service * * An `ad:Address` carries its house number inline and everything else by reference. Each address * holds exactly four `ad:component/@xlink:href` values, measured over 1,000 addresses at six * `startIndex` offsets with all four prefixes occurring 1,000 times each. The references are * absolute URIs that resolve back into the same service under the `resourceId` rewrite that * {@linkcode componentResourceID} performs: * * | reference | `resourceId` | feature type | * | -------------------------------------------------- | -------------------- | --------------------- | * | `https://data.vlaanderen.be/id/straatnaam/205827` | `straatnaam_205827` | `ad:ThoroughfareName` | * | `https://data.vlaanderen.be/id/postinfo/9800` | `postinfo_9800` | `ad:PostalDescriptor` | * | `https://data.vlaanderen.be/id/gemeentenaam/44083` | `gemeentenaam_44083` | `ad:AdminUnitName` | * | `http://vocab.belgif.be/auth/refnis1995/1000#id` | `refnis1995_1000` | `ad:AdminUnitName` | * * Resolving per address would cost four requests per row against 4,563,062 addresses. The component * types are small — 167,218 thoroughfare names, 1,190 postal descriptors, 609 administrative-unit * names — so the harvest takes each component type whole and the adapter joins locally. * * `ad:AddressRepresentation` is the one denormalized type, carrying street, postcode and post name * inline, and it cannot be harvested: any `startIndex`, `startIndex=0` included, answers HTTP 400 * `ows:ExceptionCode/NoApplicableCode` with `java.lang.RuntimeException: Failed to get property: * {http://www.opengis.net/wfs/2.0}boundedBy`, and `resultType=hits` answers HTTP 504. Only its * unindexed first page works. * * ## What the harvest records, and why it has to * * `sortBy=gml:identifier` answers HTTP 504, so no stable ordering can be requested and a paged * harvest has no ordering guarantee. Two harvests may hold the same addresses in a different order. * The harvest manifest lists its pages and the adapter reads them in that listed order, so one * harvest reproduces its own bytes even though a second harvest need not match it. * * A bare `resultType=hits` answers `numberMatched="10000"` and stays there under `count=1000000`: * that is a per-request cap rather than a count. The same request with `startIndex=1` answers * `numberMatched="4563062"`, which agrees with the bisected tail — `startIndex=4563061` returns one * feature and `startIndex=4563062` returns none. Every results page reports * `numberMatched="unknown"`. Page size caps at 10,000, so a full harvest is 457 pages. * * The adapter honors `opts.limit` and `opts.signal`, and refuses any `opts.country` but `BE`. */ import { type MarkupElement } from "@mailwoman/core/html/elements"; import { PathBuilder } from "path-ts"; import { type CorpusAdapter } from "#types"; /** * Registry id for this adapter. * * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from. */ export declare const VLAANDEREN_ADAPTER_ID = "vlaanderen"; /** * The terms the address-source register elects for `be-property-building-1`. * * The value is the register's `electedTerms` for license * `unchecked-access-free-be-agentschap-digitaal-vlaanderen`, which carries no `spdx`, * so `electedLicenseLabel` answers this string and the share-alike prefix filter matches it. */ export declare const VLAANDEREN_DEFAULT_LICENSE = "Modellicentie voor gratis hergebruik Vlaanderen"; /** * The one jurisdiction this adapter emits. * * The service publishes the Flemish Region. * ISO 3166-1 assigns that region no code of its own, so its own, so the set holds one code * and a caller naming any other gets {@linkcode UnsupportedCountryError} rather than zero rows. */ export declare const VLAANDEREN_COUNTRIES: readonly string[]; /** * What a harvest of the service holds, written beside its GML by the harvester. * * The manifest exists because the service grants no ordering: it records which pages were taken and in * which order, so the adapter's output is a function of the harvest rather than of a directory listing. */ export interface VlaanderenHarvest { /** * The service the pages came from. */ service: string; /** * The WFS version the harvester spoke. */ wfsVersion: string; /** * The `outputFormat` the pages are written in. */ outputFormat: string; /** * When the harvest ran, as the service's own `timeStamp` reported it. */ retrievedAt: string; /** * The `numberMatched` the service reported for `ad:Address` past index 0. */ addressCount: number; /** * The files holding each component feature type, in the order the adapter reads them. * * A list rather than one file per type, because page size caps at 10,000 * and `ad:ThoroughfareName` holds 167,218 features: the type needs 17 pages. * `ad:PostalDescriptor` (1,190) and `ad:AdminUnitName` (609) each fit in one, * and are still listed, so a type that grows past the cap needs no change here. */ components: { ThoroughfareName: readonly string[]; PostalDescriptor: readonly string[]; AdminUnitName: readonly string[]; }; /** * The address pages, in the order the adapter reads them. */ addressPages: readonly { startIndex: number; file: string; /** * The `numberReturned` the page's own root element states. * * The adapter checks the features it parsed against this, so a truncated page raises * rather than reading as a short one. */ numberReturned: number; }[]; } /** * Raised when the harvest cannot answer what the adapter asked it for. * * A harvest missing a component file or holding a short page cannot be read as a smaller * harvest: every address references all four components, so an absent component file * turns every row into a row with no street rather than into fewer rows. */ export declare class VlaanderenHarvestError extends Error { constructor(message: string); } /** * The `resourceId` that a component reference addresses in the same service. * * Flanders writes an absolute identifier URI rather than the local `#` fragment that * the Netherlands, Wallonia and Brussels write, and the service answers it under the * `gml:id` built from the URI's last two path segments joined with `_`. * A fragment is dropped, because `…/refnis1995/1000#id` addresses `refnis1995_1000`. * * @returns The id, or `null` when the href is not a URL with at least two path segments. * A caller treats `null` as a reference it could not read rather than as a * reference the publisher left blank. */ export declare function componentResourceID(href: string): string | null; /** * A Flemish street name read apart from the homonym discriminator that follows it. * * `gn:text` on an `ad:ThoroughfareName` is not the street name alone: it is the name, * an underscore, and a discriminator that is usually empty. * Over 20,000 values at twenty offsets, 19,979 end with `_` and the remaining 21 carry a * discriminator after it — `Rue de Cronwez_01`, `Rue de Cronwez_02`, `Heide_01`, `Heide_02`, * `Kattenberg_BO`, `Kattenberg_EK`, `Ringlaan_ME`, `Ringlaan_BEWI`, `Berkenlaan_WI`, * `Weerstandlaan_BO`, `Weerstandlaan_HO`, `Cit? du Repos_01` through `_04`, `Rue du Roeulx_01`, * `Rue du Roeulx_02`, `Rue Verte_01`, `Rue Verte_02` and `Rue des Par?onniers_01`/`_02`. * * Exactly 21 values carry an `_` anywhere but at the end, and they are the same 21: no value holds * both a discriminator and a trailing separator, so the field is one separator at one position. * * The same streets read through `ad:AddressRepresentation/ad:thoroughfare` carry * no separator at all, 0 of 10,000, which is the publisher's own evidence that * everything from the `_` onward is bookkeeping rather than name. * * So the split takes the last `_` and keeps the head. * Stripping only a trailing `_` would leave `Rue de Cronwez_01` in a corpus, * and keeping the whole value would leave `Acacialaan_`. */ export interface SplitStreetName { /** * The street name, with the separator and any discriminator removed. */ street: string; /** * The homonym discriminator, empty for all but 21 of the 20,000 values measured. */ discriminator: string; } /** * Splits an `ad:ThoroughfareName` `gn:text` value into its {@link SplitStreetName}. * * @throws {@linkcode VlaanderenHarvestError} when the value carries no `_`, * which no value of the 20,000 measured did. * That is a change in the publisher's field rather than an odd street, and guessing at * it would write a bookkeeping suffix into every row sharing the new shape. */ export declare function splitStreetName(value: string): SplitStreetName; /** * The house number an address states inline, or `undefined` when it states none this adapter can use. * * `designatorsByType` skips a designator the publisher marked void, so a void number * and an absent one both answer `undefined` here. * Both are refusals rather than addresses with no number, and the caller counts * them together for that reason. * * `ad:designator` was present and populated on 1,000 of 1,000 addresses sampled, * so neither condition has been seen on this service. */ export declare function houseNumberOf(address: MarkupElement): string | undefined; /** * Reads the harvest manifest and checks that it names what the adapter needs. */ export declare function readVlaanderenHarvest(root: PathBuilder): Promise; export declare function createVlaanderenAdapter(): CorpusAdapter; /** * The configured adapter instance registered with the corpus builder. */ export declare const vlaanderenAdapter: CorpusAdapter; //# sourceMappingURL=adapter.d.ts.map