@seta-labs/geo 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @seta-labs/geo
 
+## 0.7.0
+
+- `reverseGeocode(input)` answers from a chain of sources: the ANNCSU register
+  and the OpenStreetMap house numbers loaded in seta-geo first (within 25 m),
+  TrueWay last (an exact street address within 50 m). Failing a number, the
+  named road TrueWay places the point on, as `match.level: 'VIA'` with
+  `streetNumber`, `location` and `distanceM` null. Never an approximate
+  number: with neither, `match` is null and `status` is `NO_RESULT`.
+- The result gains `admin` (new type `GeoAdminArea`: `codComune`, `comune`,
+  `provincia`, `regione`), the municipality of the point from the ISTAT
+  boundaries, present even without a match; and `match` (new type
+  `GeoStreetMatch`): `level`, `provider` (`ANNCSU`, `OSM`, `TRUEWAY`),
+  `precision`, `street`, `streetNumber`, `postalCode`, `locality`,
+  `location`, `distanceM`, `sourceRef`.
+- `address` is now composed from the match: `Via Ponte Schiavo 13, Roma (RM)`,
+  or `Via Ponte Schiavo, Roma (RM)` for a street alone.
+- With `include: 'full'`, `results` is the raw answer of `match.provider`:
+  the TrueWay result list, or the ANNCSU/OSM record as one item.
+- The request takes `maxDistanceM` (1-50), which can only tighten the limits.
+
 ## 0.6.0
 
 - `comune(codComune)` gains the `territorio` block (new type

package/dist/index.d.ts

@@ -111,30 +111,30 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/cadastre/parcel': {
+    '/territory/status': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        get: operations['TerritoryController_status'];
         put?: never;
-        post: operations['CadastreController_parcel'];
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/cadastre/parcels': {
+    '/territory/datasets': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['CadastreController_listParcels'];
+        get: operations['TerritoryController_datasets'];
         put?: never;
         post?: never;
         delete?: never;
@@ -143,14 +143,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/status': {
+    '/territory/comuni': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_status'];
+        get: operations['TerritoryController_listComuni'];
         put?: never;
         post?: never;
         delete?: never;
@@ -159,14 +159,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/datasets': {
+    '/territory/quotazioni': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_datasets'];
+        get: operations['TerritoryController_listQuotazioni'];
         put?: never;
         post?: never;
         delete?: never;
@@ -175,14 +175,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/comuni': {
+    '/territory/compravendite': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listComuni'];
+        get: operations['TerritoryController_listCompravendite'];
         put?: never;
         post?: never;
         delete?: never;
@@ -191,14 +191,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/quotazioni': {
+    '/territory/comuni/{codComune}': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listQuotazioni'];
+        get: operations['TerritoryController_comune'];
         put?: never;
         post?: never;
         delete?: never;
@@ -207,48 +207,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/compravendite': {
+    '/territory/resolve': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listCompravendite'];
+        get?: never;
         put?: never;
-        post?: never;
+        post: operations['TerritoryController_resolve'];
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/territory/comuni/{codComune}': {
+    '/cadastre/parcel': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_comune'];
+        get?: never;
         put?: never;
-        post?: never;
+        post: operations['CadastreController_parcel'];
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/territory/resolve': {
+    '/cadastre/parcels': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        get: operations['CadastreController_listParcels'];
         put?: never;
-        post: operations['TerritoryController_resolve'];
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -410,83 +410,68 @@ interface components {
              * @enum {string}
              */
             include?: 'best' | 'full';
+            /** @description Tightens the distance a house number may lie from the point (25 m for ANNCSU and OSM, 50 m for TrueWay); it never widens them. */
+            maxDistanceM?: number;
         };
-        ReverseGeocodeResultDto: {
-            /** @enum {string} */
-            status: 'OK' | 'NO_RESULT';
-            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
-            query: string;
-            /** @description Formatted address of the best-tier result. */
-            address: string | null;
-            /** @description True when the answer came from the cache, no provider call. */
-            cached: boolean;
-            /** @description Only with include=full: the provider's result list exactly as returned (all tiers, all fields). Empty array = the provider answered with no results. Null = the raw response is not available for this cached row. */
-            results?: {
-                [key: string]: unknown;
-            }[] | null;
+        GeoAdminAreaDto: {
+            /** @description Belfiore code, `H501`. */
+            codComune: string;
+            comune: string;
+            /** @description Province code, `RM`. */
+            provincia: string;
+            regione: string;
         };
-        CadastreParcelRequestDto: {
+        GeoLocationDto: {
             lat: number;
             lng: number;
         };
-        CadastreParcelResultDto: {
-            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
-            query: string;
+        GeoStreetMatchDto: {
             /**
-             * @description What lies under the point, verbatim from the map: PARTICELLA, STRADA, …
-             * @example PARTICELLA
+             * @description How far down the address the match reaches: `CIVICO` a house number close enough, `VIA` only the street, when no source has a number close enough.
+             * @enum {string}
              */
-            tipologia: string;
-            /** @example B885 */
-            codComune: string | null;
-            /** @description Null when the map gives none: blanks and "null" strings are cleared. */
-            sezione: string | null;
-            /** @example 36 */
-            foglio: string | null;
-            /** @example G */
-            allegato: string | null;
-            sviluppo: string | null;
-            /** @example 5101 */
-            particella: string | null;
-            /** @description The map answer exactly as returned (blank SEZIONE and "null" strings included). */
-            raw: {
-                [key: string]: unknown;
-            };
-            /** @description True when the answer came from the cache, no map call. */
-            cached: boolean;
-        };
-        CadastreParcelRowDto: {
-            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals. */
-            query: string;
-            lat: number;
-            lng: number;
-            /** @example PARTICELLA */
-            tipologia: string;
-            /** @example B885 */
-            codComune: string | null;
-            /** @description Municipality name; null when the code is not in the registry. */
-            comune: string | null;
-            /** @example AL */
-            provincia: string | null;
-            sezione: string | null;
-            /** @example 36 */
-            foglio: string | null;
-            /** @example G */
-            allegato: string | null;
-            sviluppo: string | null;
-            /** @example 5101 */
-            particella: string | null;
+            level: 'CIVICO' | 'VIA';
             /**
-             * Format: date-time
-             * @description When the map last gave this answer.
+             * @description The source that answered: ANNCSU and OSM are loaded locally, TrueWay is paid.
+             * @enum {string}
              */
-            updatedAt: string;
+            provider: 'ANNCSU' | 'OSM' | 'TRUEWAY';
+            /** @description How the source rates the position: `metodo-1`…`metodo-5` (ANNCSU), `nodo` or `edificio` (OSM), `exact` (TrueWay), `centroid` (a TrueWay street). */
+            precision: string;
+            street: string;
+            /** @description `12`, `12/A`, `12 rosso`; null at level `VIA`. */
+            streetNumber: string | null;
+            /** @description Null from ANNCSU, which has none. */
+            postalCode: string | null;
+            /** @description Hamlet or locality as the source names it; the municipality is in `admin`. */
+            locality: string | null;
+            /** @description Where the house number is; null for a street the source places at its centroid. */
+            location: components['schemas']['GeoLocationDto'] | null;
+            /** @description Metres from the requested point to `location`; null without a location. */
+            distanceM: number | null;
+            /** @description Id of the record in its source: ANNCSU access, OSM `n123`/`w456`. */
+            sourceRef: string | null;
         };
-        CadastreParcelsPageDto: {
-            page: number;
-            pageSize: number;
-            total: number;
-            items: components['schemas']['CadastreParcelRowDto'][];
+        ReverseGeocodeResultDto: {
+            /**
+             * @description OK when `match` is present.
+             * @enum {string}
+             */
+            status: 'OK' | 'NO_RESULT';
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
+            query: string;
+            /** @description The match as one line: `Via Ponte Schiavo 13, Roma (RM)`, or `Via Ponte Schiavo, Roma (RM)` at level `VIA`. */
+            address: string | null;
+            /** @description Municipality of the point from the ISTAT boundaries, whatever the match; null at sea, abroad or while no boundary edition is loaded. */
+            admin: components['schemas']['GeoAdminAreaDto'] | null;
+            /** @description An exact house number close enough, else the street a source names (level `VIA`); null when neither: never an approximate number. */
+            match: components['schemas']['GeoStreetMatchDto'] | null;
+            /** @description True when the answer came from stored rows: no source was asked again. */
+            cached: boolean;
+            /** @description Only with include=full: the raw answer of the source in `match.provider` (the TrueWay result list, or the ANNCSU/OSM record as one item); without a match, the raw answer of the last source asked. */
+            results?: {
+                [key: string]: unknown;
+            }[] | null;
         };
         TerritoryStatusDto: {
             /** @description Latest OMI publication loaded (`YYYY-S`), null while no supply is loaded. */
@@ -651,7 +636,7 @@ interface components {
         TerritoryComuneDetailDto: {
             comune: components['schemas']['TerritoryComuneDto'];
             istat: components['schemas']['TerritoryIstatDto'];
-            /** @description Null for a suppressed municipality: SITUAS describes only the current ones. */
+            /** @description Latest SITUAS edition that describes the municipality; null when none does, as for one suppressed before the first edition loaded. */
             territorio: components['schemas']['TerritoryTerritorioDto'] | null;
             /** @description Publication the zone quotations come from, null while none is loaded. */
             semestre: string | null;
@@ -687,6 +672,69 @@ interface components {
         TerritoryResolveResponseDto: {
             items: components['schemas']['TerritoryPointResultDto'][];
         };
+        CadastreParcelRequestDto: {
+            lat: number;
+            lng: number;
+        };
+        CadastreParcelResultDto: {
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
+            query: string;
+            /**
+             * @description What lies under the point, verbatim from the map: PARTICELLA, STRADA, …
+             * @example PARTICELLA
+             */
+            tipologia: string;
+            /** @example B885 */
+            codComune: string | null;
+            /** @description Null when the map gives none: blanks and "null" strings are cleared. */
+            sezione: string | null;
+            /** @example 36 */
+            foglio: string | null;
+            /** @example G */
+            allegato: string | null;
+            sviluppo: string | null;
+            /** @example 5101 */
+            particella: string | null;
+            /** @description The map answer exactly as returned (blank SEZIONE and "null" strings included). */
+            raw: {
+                [key: string]: unknown;
+            };
+            /** @description True when the answer came from the cache, no map call. */
+            cached: boolean;
+        };
+        CadastreParcelRowDto: {
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals. */
+            query: string;
+            lat: number;
+            lng: number;
+            /** @example PARTICELLA */
+            tipologia: string;
+            /** @example B885 */
+            codComune: string | null;
+            /** @description Municipality name; null when the code is not in the registry. */
+            comune: string | null;
+            /** @example AL */
+            provincia: string | null;
+            sezione: string | null;
+            /** @example 36 */
+            foglio: string | null;
+            /** @example G */
+            allegato: string | null;
+            sviluppo: string | null;
+            /** @example 5101 */
+            particella: string | null;
+            /**
+             * Format: date-time
+             * @description When the map last gave this answer.
+             */
+            updatedAt: string;
+        };
+        CadastreParcelsPageDto: {
+            page: number;
+            pageSize: number;
+            total: number;
+            items: components['schemas']['CadastreParcelRowDto'][];
+        };
     };
     responses: never;
     parameters: never;
@@ -894,97 +942,6 @@ interface operations {
             };
         };
     };
-    CadastreController_parcel: {
-        parameters: {
-            query?: never;
-            header?: {
-                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
-                'Cache-Control'?: string;
-            };
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                'application/json': components['schemas']['CadastreParcelRequestDto'];
-            };
-        };
-        responses: {
-            /** @description What the AdE cadastral map finds under the point: a parcel, a street, … */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['CadastreParcelResultDto'];
-                };
-            };
-            /** @description Missing or invalid API key. */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-            /** @description CADASTRE_UNAVAILABLE or CADASTRE_INVALID_REPLY: the map gave no answer. */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-            /** @description CADASTRE_BLOCKED: the map is refusing calls; Retry-After says when to try again. */
-            503: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
-            504: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-        };
-    };
-    CadastreController_listParcels: {
-        parameters: {
-            query?: {
-                page?: number;
-                pageSize?: number;
-                /** @description Cadastral municipality code. */
-                codComune?: string;
-                foglio?: string;
-                particella?: string;
-                /** @description What lies under the point. */
-                tipologia?: string;
-            };
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description The stored map answers, newest first; never a map call. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    'application/json': components['schemas']['CadastreParcelsPageDto'];
-                };
-            };
-            /** @description Missing or invalid API key. */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-        };
-    };
     TerritoryController_status: {
         parameters: {
             query?: never;
@@ -1214,6 +1171,97 @@ interface operations {
             };
         };
     };
+    CadastreController_parcel: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['CadastreParcelRequestDto'];
+            };
+        };
+        responses: {
+            /** @description What the AdE cadastral map finds under the point: a parcel, a street, … */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['CadastreParcelResultDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CADASTRE_UNAVAILABLE or CADASTRE_INVALID_REPLY: the map gave no answer. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CADASTRE_BLOCKED: the map is refusing calls; Retry-After says when to try again. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    CadastreController_listParcels: {
+        parameters: {
+            query?: {
+                page?: number;
+                pageSize?: number;
+                /** @description Cadastral municipality code. */
+                codComune?: string;
+                foglio?: string;
+                particella?: string;
+                /** @description What lies under the point. */
+                tipologia?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The stored map answers, newest first; never a map call. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['CadastreParcelsPageDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
 }
 
 type ApiPaths = paths;
@@ -1224,6 +1272,8 @@ type GeocodeResult = ApiSchemas['GeocodeResultDto'];
 type GeocodeBatchResponse = ApiSchemas['GeocodeBatchResponseDto'];
 type ReverseGeocodeRequest = ApiSchemas['ReverseGeocodeRequestDto'];
 type ReverseGeocodeResult = ApiSchemas['ReverseGeocodeResultDto'];
+type GeoStreetMatch = ApiSchemas['GeoStreetMatchDto'];
+type GeoAdminArea = ApiSchemas['GeoAdminAreaDto'];
 type CadastreParcelRequest = ApiSchemas['CadastreParcelRequestDto'];
 type CadastreParcelResult = ApiSchemas['CadastreParcelResultDto'];
 type CadastreParcelsPage = ApiSchemas['CadastreParcelsPageDto'];
@@ -1300,4 +1350,4 @@ interface GeoClient {
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-export type { CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, GeoClient, GeoClientOptions, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, LookupCache, LookupOptions, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus, TerritoryTerritorio };
+export type { CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, GeoAdminArea, GeoClient, GeoClientOptions, GeoStreetMatch, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, LookupCache, LookupOptions, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus, TerritoryTerritorio };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",