@geospatial-sdk/geocoding 0.0.3-alpha.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Camptocamp
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,11 @@
+# `geocoding`
+
+> TODO: description
+
+## Usage
+
+```
+const geocoding = require('geocoding');
+
+// TODO: DEMONSTRATE API
+```

package/index.ts

@@ -0,0 +1,6 @@
+export {
+  queryGeoadmin,
+  queryDataGouvFr,
+  GeoadminOptions,
+  DataGouvFrOptions,
+} from "./lib/providers";

package/lib/model/index.ts

@@ -0,0 +1,6 @@
+import { Geometry } from "geojson";
+
+export interface GeocodingResult {
+  label: string;
+  geom: Geometry | null;
+}

package/lib/providers/data-gouv-fr.provider.test.ts

@@ -0,0 +1,92 @@
+import { GeocodingResult } from "../model";
+import { DataGouvFrResponse, queryDataGouvFr } from "./data-gouv-fr.provider";
+
+const RESULTS_FIXTURE: DataGouvFrResponse = {
+  type: "FeatureCollection",
+  version: "draft",
+  features: [
+    {
+      type: "Feature",
+      geometry: {
+        type: "Point",
+        coordinates: [2.290084, 49.897443],
+      },
+      properties: {
+        label: "8 Boulevard du Port 80000 Amiens",
+        score: 0.49159121588068583,
+        housenumber: "8",
+        id: "80021_6590_00008",
+        type: "housenumber",
+        name: "8 Boulevard du Port",
+        postcode: "80000",
+        citycode: "80021",
+        x: 648952.58,
+        y: 6977867.25,
+        city: "Amiens",
+        context: "80, Somme, Hauts-de-France",
+        importance: 0.6706612694243868,
+        street: "Boulevard du Port",
+      },
+    },
+  ],
+  attribution: "BAN",
+  licence: "ODbL 1.0",
+  query: "8 bd du port",
+  limit: 1,
+};
+
+global.fetch = vi.fn(() =>
+  Promise.resolve({
+    json: () => Promise.resolve(RESULTS_FIXTURE),
+  } as Response),
+);
+
+describe("queryDataGouvFr", () => {
+  let results: GeocodingResult[];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("results parsing", () => {
+    beforeEach(async () => {
+      results = await queryDataGouvFr("hello");
+    });
+    it("produces geometries, removes html tags from labels", () => {
+      expect(results).toEqual([
+        {
+          geom: {
+            type: "Point",
+            coordinates: [2.290084, 49.897443],
+          },
+          label: "8 Boulevard du Port 80000 Amiens",
+        },
+      ]);
+    });
+  });
+  describe("default options", () => {
+    beforeEach(async () => {
+      results = await queryDataGouvFr("hello world");
+    });
+    it("uses default options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api-adresse.data.gouv.fr/search/?q=hello+world",
+      );
+    });
+  });
+  describe("custom options", () => {
+    beforeEach(async () => {
+      results = await queryDataGouvFr("hello world", {
+        type: "street",
+        limit: 32,
+        cityCode: "12345",
+        postCode: "00000",
+      });
+    });
+    it("uses given options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api-adresse.data.gouv.fr/search/?q=hello+world&limit=32&type=street&postcode=00000&citycode=12345",
+      );
+    });
+  });
+});

package/lib/providers/data-gouv-fr.provider.ts

@@ -0,0 +1,86 @@
+import { GeocodingResult } from "../model";
+import { Geometry } from "geojson";
+
+interface DataGouvFrResponseItem {
+  type: "Feature";
+  geometry: Geometry;
+  properties: {
+    label: string;
+    score: number;
+    id: string;
+    name: string;
+    postcode: string;
+    citycode: string;
+    x: number;
+    y: number;
+    city: string;
+    district?: string;
+    context: string;
+    type: string;
+    importance: number;
+    street: string;
+    housenumber?: string;
+  };
+}
+
+export interface DataGouvFrResponse {
+  type: "FeatureCollection";
+  version: string;
+  features: Array<DataGouvFrResponseItem>;
+  attribution: string;
+  licence: string;
+  query: string;
+  filters?: Record<string, string>;
+  limit: number;
+}
+
+const baseUrl = "https://api-adresse.data.gouv.fr/search/";
+
+/**
+ * Reference documentation: https://adresse.data.gouv.fr/api-doc/adresse
+ * @property type
+ * @property postCode
+ * @property cityCode
+ * @property limit Default value 15
+ */
+export interface DataGouvFrOptions {
+  type?: "housenumber" | "street" | "locality" | "municipality";
+  postCode?: string;
+  cityCode?: string;
+  limit?: number;
+}
+
+export function queryDataGouvFr(
+  input: string,
+  options?: DataGouvFrOptions,
+): Promise<GeocodingResult[]> {
+  const baseOptions: DataGouvFrOptions = {};
+  const finalOptions = options ? { ...baseOptions, ...options } : baseOptions;
+
+  const url = new URL(baseUrl);
+  url.searchParams.set("q", input);
+  if (finalOptions.limit) {
+    url.searchParams.set("limit", finalOptions.limit.toString());
+  }
+  if (finalOptions.type) {
+    url.searchParams.set("type", finalOptions.type);
+  }
+  if (finalOptions.postCode) {
+    url.searchParams.set("postcode", finalOptions.postCode);
+  }
+  if (finalOptions.cityCode) {
+    url.searchParams.set("citycode", finalOptions.cityCode);
+  }
+  return fetch(url.toString())
+    .then((response) => response.json())
+    .then((response: DataGouvFrResponse) =>
+      response.features.map((feature) => {
+        const label = feature.properties?.label.replace(/<[^>]*>?/gm, "");
+        const geom = feature.geometry;
+        return {
+          label,
+          geom,
+        };
+      }),
+    );
+}

package/lib/providers/geoadmin.provider.test.ts

@@ -0,0 +1,169 @@
+import { GeoadminResponse, queryGeoadmin } from "./geoadmin.provider";
+import { GeocodingResult } from "../model";
+
+const RESULTS_FIXTURE: GeoadminResponse = {
+  type: "FeatureCollection",
+  bbox: [8.446892, 47.319034, 8.627209, 47.43514],
+  features: [
+    {
+      geometry: {
+        type: "Point",
+        coordinates: [8.446892, 47.319034],
+      },
+      properties: {
+        origin: "gazetteer",
+        geom_quadindex: "021300220330313020221",
+        weight: 1,
+        zoomlevel: 10,
+        lon: 7.459799289703369,
+        detail: "wabern koeniz",
+        rank: 5,
+        lat: 46.925777435302734,
+        num: 1,
+        y: 601612.0625,
+        x: 197186.8125,
+        label: "<i>Populated Place</i> <b>Wabern</b> (BE) - Köniz",
+        id: 215754,
+      },
+      type: "Feature",
+      id: 215754,
+      bbox: [8.446892, 47.319034, 8.627209, 47.43514],
+    },
+    {
+      geometry: {
+        type: "Point",
+        coordinates: [8.446892, 47.319034],
+      },
+      properties: {
+        origin: "gg25",
+        geom_quadindex: "030003",
+        weight: 6,
+        zoomlevel: 4294967295,
+        lon: 8.527311325073242,
+        detail: "zurigo zh",
+        rank: 2,
+        lat: 47.37721252441406,
+        num: 1,
+        x: 8.527311325073242,
+        y: 47.37721252441406,
+        label: "<b>Zurigo (ZH)</b>",
+        id: 153,
+        featureId: "261",
+      },
+      type: "Feature",
+      id: 153,
+      bbox: [8.446892, 47.319034, 8.627209, 47.43514],
+    },
+  ],
+};
+
+global.fetch = vi.fn(() =>
+  Promise.resolve({
+    json: () => Promise.resolve(RESULTS_FIXTURE),
+  } as Response),
+);
+
+describe("queryGeoadmin", () => {
+  let results: GeocodingResult[];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("results parsing", () => {
+    beforeEach(async () => {
+      results = await queryGeoadmin("hello");
+    });
+    it("produces geometries, removes html tags from labels", () => {
+      expect(results).toEqual([
+        {
+          geom: {
+            coordinates: [
+              [
+                [8.446892, 47.319034],
+                [8.446892, 47.43514],
+                [8.627209, 47.43514],
+                [8.627209, 47.319034],
+                [8.446892, 47.319034],
+              ],
+            ],
+            type: "Polygon",
+          },
+          label: "Populated Place Wabern (BE) - Köniz",
+        },
+        {
+          geom: {
+            coordinates: [
+              [
+                [8.446892, 47.319034],
+                [8.446892, 47.43514],
+                [8.627209, 47.43514],
+                [8.627209, 47.319034],
+                [8.446892, 47.319034],
+              ],
+            ],
+            type: "Polygon",
+          },
+          label: "Zurigo (ZH)",
+        },
+      ]);
+    });
+  });
+  describe("default options", () => {
+    beforeEach(async () => {
+      results = await queryGeoadmin("hello world");
+    });
+    it("uses default options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api3.geo.admin.ch/rest/services/api/SearchServer?geometryFormat=geojson&type=locations&searchText=hello+world&lang=en&sr=4326&origins=zipcode%2Cgg25",
+      );
+    });
+  });
+  describe("locations search", () => {
+    beforeEach(async () => {
+      results = await queryGeoadmin("hello world", {
+        type: "locations",
+        lang: "de",
+        origins: ["district", "address"],
+        limit: 32,
+        sr: "21781",
+      });
+    });
+    it("uses given options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api3.geo.admin.ch/rest/services/api/SearchServer?geometryFormat=geojson&type=locations&searchText=hello+world&lang=de&sr=21781&limit=32&origins=district%2Caddress",
+      );
+    });
+  });
+  describe("feature search", () => {
+    beforeEach(async () => {
+      results = await queryGeoadmin("hello world", {
+        type: "featuresearch",
+        lang: "de",
+        features: ["abc", "def"],
+        limit: 32,
+        sr: "21781",
+      });
+    });
+    it("uses given options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api3.geo.admin.ch/rest/services/api/SearchServer?geometryFormat=geojson&type=featuresearch&searchText=hello+world&lang=de&sr=21781&limit=32&features=abc%2Cdef",
+      );
+    });
+  });
+  describe("layers search", () => {
+    beforeEach(async () => {
+      results = await queryGeoadmin("hello world", {
+        type: "layers",
+        lang: "de",
+        limit: 32,
+        sr: "21781",
+      });
+    });
+    it("uses given options", () => {
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://api3.geo.admin.ch/rest/services/api/SearchServer?geometryFormat=geojson&type=layers&searchText=hello+world&lang=de&sr=21781&limit=32",
+      );
+    });
+  });
+});

package/lib/providers/geoadmin.provider.ts

@@ -0,0 +1,95 @@
+import { GeocodingResult } from "../model";
+import { BBox, FeatureCollection, Geometry } from "geojson";
+
+// from https://github.com/geoblocks/ga-search
+const baseUrl = "https://api3.geo.admin.ch/rest/services/api/SearchServer";
+
+export type GeoadminResponse = FeatureCollection;
+
+/**
+ * Reference documentation: https://api3.geo.admin.ch/services/sdiservices.html#search
+ * @property type Default is 'locations'
+ * @property sr Defaults to 4326
+ * @property limit Default value is 50 for 'locations', 20 for 'featuresearch', 30 for 'layers'
+ * @property lang Default is 'en'
+ * @property origins Defaults to 'zipcode,gg25'; only applies when type is 'locations'
+ * @property features A list of technical layer names; only applies when type is 'featuresearch'
+ */
+export interface GeoadminOptions {
+  type?: "locations" | "featuresearch" | "layers";
+  sr?: "21781" | "2056" | "4326" | "3857";
+  origins?: Array<
+    | "zipcode"
+    | "gg25"
+    | "district"
+    | "kantone"
+    | "gazetteer"
+    | "address"
+    | "parcel"
+  >;
+  limit?: number;
+  lang?: "de" | "fr" | "it" | "rm" | "en";
+  features?: string[];
+}
+
+export function queryGeoadmin(
+  input: string,
+  options?: GeoadminOptions,
+): Promise<GeocodingResult[]> {
+  const baseOptions: GeoadminOptions = {
+    type: "locations",
+    sr: "4326",
+    origins: ["zipcode", "gg25"],
+    lang: "en",
+    features: [],
+  };
+  const finalOptions = options ? { ...baseOptions, ...options } : baseOptions;
+
+  let url = new URL(baseUrl);
+  url.searchParams.set("geometryFormat", "geojson");
+  url.searchParams.set("type", finalOptions.type!);
+  url.searchParams.set("searchText", input);
+  url.searchParams.set("lang", finalOptions.lang!);
+  url.searchParams.set("sr", finalOptions.sr!);
+  if (finalOptions.limit !== undefined) {
+    url.searchParams.set("limit", finalOptions.limit.toString());
+  }
+
+  switch (finalOptions.type!) {
+    case "locations":
+      url.searchParams.set("origins", finalOptions.origins!.join(","));
+      break;
+    case "featuresearch":
+      url.searchParams.set("features", finalOptions.features!.join(","));
+      break;
+  }
+
+  return fetch(url.toString())
+    .then((response) => response.json())
+    .then((response: GeoadminResponse) =>
+      response.features.map((feature) => {
+        const label = feature.properties?.label.replace(/<[^>]*>?/gm, "");
+        const geom = feature.bbox ? bboxToGeometry(feature.bbox) : null;
+        return {
+          label,
+          geom,
+        };
+      }),
+    );
+}
+
+function bboxToGeometry(extent: BBox): Geometry {
+  const [minX, minY, maxX, maxY] = extent;
+  return {
+    type: "Polygon",
+    coordinates: [
+      [
+        [minX, minY],
+        [minX, maxY],
+        [maxX, maxY],
+        [maxX, minY],
+        [minX, minY],
+      ],
+    ],
+  };
+}

package/lib/providers/index.ts

@@ -0,0 +1,3 @@
+export * from "./base.provider";
+export * from "./geoadmin.provider";
+export * from "./data-gouv-fr.provider";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@geospatial-sdk/geocoding",
+  "version": "0.0.3-alpha.0+d226ce9",
+  "description": "Geocoding-related components",
+  "keywords": [
+    "geocoding"
+  ],
+  "author": "Olivia <olivia.guyot@camptocamp.com>",
+  "homepage": "https://github.com/jahow/geospatial-sdk#readme",
+  "license": "BSD-3-Clause",
+  "main": "index.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jahow/geospatial-sdk.git"
+  },
+  "scripts": {
+    "test": "vitest"
+  },
+  "bugs": {
+    "url": "https://github.com/jahow/geospatial-sdk/issues"
+  },
+  "gitHead": "d226ce97fd7d50287c694ce4ed7182755cdfbb4e"
+}