feat: add subLocalityLevels for Nominatim (#15)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.10.0
+
+* [Nominatim] Add `subLocalityLevels`
+
 ## 0.9.0
 
 * Introduce async / await (or Promise) syntax (providers return a promise if no callback is given)

docs/provider_usage.md

@@ -298,7 +298,7 @@ Here is a table listing the parameters according to the providers:
       <td>geocoded</td>
       <td>subLocalityLevels</td>
       <td>Levels for the sublocality</td>
-      <td>Google Maps</td>
+      <td>Google Maps, Nominatim</td>
     </tr>
     <tr>
       <td>geocoded</td>

docs/provider_usage/googlemaps.md

@@ -26,4 +26,4 @@
 - `locationType`: a type representing the precision of the result
 - `streetAddress`: the street number with the street name
 - `intersection`, `political`, `colloquialArea`, `ward`, `neighborhood`, `premise`, `subpremise`, `naturalFeature`, `airport`, `park`, `pointOfInterest`, `establishment`, `postalCodeSuffix`: additional address components
-- `subLocalityLevels`: levels for the sublocality
+- `subLocalityLevels`: levels for the sublocality (greater level number means smaller area)

docs/provider_usage/nominatim.md

@@ -22,3 +22,4 @@
 - `osmId`, `osmType`: reference to the OpenStreetMap object
 - `category`, `type`: key and value of the main OpenStreetMap tag
 - `attribution`: OpenStreetMap licensing information
+- `subLocalityLevels`: levels for the sublocality (greater level number means smaller area)

spec/provider/NominatimProvider.spec.ts

@@ -72,6 +72,10 @@ describe("OpenStreetMap / Nominatim Geocoder Provider", () => {
         expect(geocoded.getStreetName()).toEqual("Pennsylvania Avenue");
         expect(geocoded.getSubLocality()).toEqual(undefined);
         expect(geocoded.getLocality()).toEqual("Washington");
+        expect(geocoded.getSubLocalityLevels()).toEqual([
+          AdminLevel.create({ level: 3, name: "Penn Quarter" }),
+          AdminLevel.create({ level: 5, name: "Pennsylvania Avenue" }),
+        ]);
         expect(geocoded.getPostalCode()).toEqual("20045");
         expect(geocoded.getRegion()).toEqual("District of Columbia");
         expect(geocoded.getAdminLevels()).toEqual([
@@ -125,6 +129,9 @@ describe("OpenStreetMap / Nominatim Geocoder Provider", () => {
         expect(geocoded.getStreetName()).toEqual(undefined);
         expect(geocoded.getSubLocality()).toEqual("Quartier du Père-Lachaise");
         expect(geocoded.getLocality()).toEqual("Paris");
+        expect(geocoded.getSubLocalityLevels()).toEqual([
+          AdminLevel.create({ level: 1, name: "Quartier du Père-Lachaise" }),
+        ]);
         expect(geocoded.getPostalCode()).toEqual("75020");
         expect(geocoded.getRegion()).toEqual("Île-de-France");
         expect(geocoded.getAdminLevels()).toEqual([

src/provider/nominatim/NominatimGeocoded.ts

@@ -1,4 +1,5 @@
 import Geocoded, { GeocodedObject } from "Geocoded";
+import AdminLevel from "AdminLevel";
 
 export interface NominatimGeocodedObject extends GeocodedObject {
   readonly displayName?: string;
@@ -7,6 +8,7 @@ export interface NominatimGeocodedObject extends GeocodedObject {
   readonly category?: string;
   readonly type?: string;
   readonly attribution?: string;
+  readonly subLocalityLevels?: AdminLevel[];
 }
 
 export default class NominatimGeocoded extends Geocoded {
@@ -22,13 +24,16 @@ export default class NominatimGeocoded extends Geocoded {
 
   private readonly attribution?: string;
 
+  private readonly subLocalityLevels: AdminLevel[];
+
   protected constructor({
     displayName,
     osmId,
     osmType,
     category,
     type,
     attribution,
+    subLocalityLevels,
     ...geocodedObject
   }: NominatimGeocodedObject) {
     super(geocodedObject);
@@ -38,6 +43,7 @@ export default class NominatimGeocoded extends Geocoded {
     this.category = category;
     this.type = type;
     this.attribution = attribution;
+    this.subLocalityLevels = subLocalityLevels || [];
   }
 
   public static create(object: NominatimGeocodedObject): NominatimGeocoded {
@@ -53,6 +59,7 @@ export default class NominatimGeocoded extends Geocoded {
       category: this.category,
       type: this.type,
       attribution: this.attribution,
+      subLocalityLevels: this.subLocalityLevels,
     };
   }
 
@@ -121,4 +128,12 @@ export default class NominatimGeocoded extends Geocoded {
   public getAttribution(): undefined | string {
     return this.attribution;
   }
+
+  public addSubLocalityLevel(subLocalityLevel: AdminLevel): void {
+    this.subLocalityLevels.push(subLocalityLevel);
+  }
+
+  public getSubLocalityLevels(): AdminLevel[] {
+    return this.subLocalityLevels;
+  }
 }

src/provider/nominatim/NominatimProvider.ts

@@ -62,22 +62,47 @@ export interface NominatimResult {
   icon: string;
   address: {
     attraction?: string;
+    pedestrian?: string;
+    // eslint-disable-next-line camelcase
+    house_name?: string;
     // eslint-disable-next-line camelcase
     house_number?: string;
     road?: string;
-    pedestrian?: string;
+    retail?: string;
+    commercial?: string;
+    industrial?: string;
+    farmyard?: string;
+    farm?: string;
+    residental?: string;
+    // eslint-disable-next-line camelcase
+    city_block?: string;
+    quarter?: string;
+    allotments?: string;
     neighbourhood?: string;
+    // eslint-disable-next-line camelcase
+    isolated_dwelling?: string;
+    croft?: string;
+    hamlet?: string;
+    // eslint-disable-next-line camelcase
+    city_district?: string;
+    district?: string;
+    borough?: string;
+    subdivision?: string;
     suburb?: string;
+    municipality?: string;
     city?: string;
     town?: string;
     village?: string;
-    hamlet?: string;
+    region?: string;
+    // eslint-disable-next-line camelcase
+    state_district?: string;
     state?: string;
     county?: string;
     postcode?: string;
     country?: string;
     // eslint-disable-next-line camelcase
     country_code?: string;
+    continent?: string;
   };
 }
 
@@ -385,6 +410,56 @@ export default class NominatimProvider
       }
     });
 
+    const subLocalityLevels: (
+      | "city_district"
+      | "district"
+      | "borough"
+      | "suburb"
+      | "subdivision"
+      | "hamlet"
+      | "croft"
+      | "isolated_dwelling"
+      | "neighbourhood"
+      | "allotments"
+      | "quarter"
+      | "city_block"
+      | "residental"
+      | "farm"
+      | "farmyard"
+      | "industrial"
+      | "commercial"
+      | "retail"
+      | "road"
+      | "house_name"
+    )[][] = [
+      ["city_district", "district", "borough", "suburb", "subdivision"],
+      ["hamlet", "croft", "isolated_dwelling"],
+      ["neighbourhood", "allotments", "quarter"],
+      [
+        "city_block",
+        "residental",
+        "farm",
+        "farmyard",
+        "industrial",
+        "commercial",
+        "retail",
+      ],
+      ["road"],
+      ["house_name"],
+    ];
+    subLocalityLevels.forEach((subLocalities, level) => {
+      subLocalities.forEach((subLocalityLevel) => {
+        if (result.address[subLocalityLevel]) {
+          geocoded.addSubLocalityLevel(
+            AdminLevel.create({
+              level: level + 1,
+              name: result.address[subLocalityLevel] || "",
+            })
+          );
+        }
+      });
+    });
+
     return geocoded;
   }
 }