PIMS-683 - Geocoder Service

.env-template

@@ -13,7 +13,7 @@ POSTGRES_DB=
 POSTGRES_PORT=
 POSTGRES_SERVICE= # only when in a container
 
-# For Express API Development
+# For Express API Development & Express Keycloak
 
 FRONTEND_URL=
 BACKEND_URL=
@@ -23,3 +23,10 @@ BACKEND_URL=
 SSO_CLIENT_ID= # Keycloak client_id
 SSO_CLIENT_SECRET= # Keycloak client_secret
 SSO_AUTH_SERVER_URL= # Keycloak auth URL, see example below.
+
+# CSS Keycloak API
+CSS_API_CLIENT_ID= # Keycloak CSS API Service Account client_id
+CSS_API_CLIENT_SECRET= # Keycloak CSS API Service Account client_secret
+
+# BC Geocoder
+GEOCODER_KEY=

express-api/Dockerfile

@@ -2,7 +2,7 @@
 #                 Base                #
 #############################################
 # Use an official Node.js runtime as a base image
-FROM node:18.17.1-bullseye-slim as base
+FROM node:21.6-bullseye-slim as base
 
 # Set the working directory in the container
 WORKDIR /express-api
@@ -25,7 +25,7 @@ RUN npm run build
 #############################################
 #                 Prod Build                #
 #############################################
-FROM node:18.17.1-bullseye-slim as Prod
+FROM node:21.6-bullseye-slim as Prod
 
 # Set the working directory to /express-api
 WORKDIR /express-api

express-api/src/constants/index.ts

@@ -1,8 +1,10 @@
 import networking from '@/constants/networking';
 import switches from '@/constants/switches';
+import urls from '@/constants/urls';
 
 const constants = {
   ...networking,
   ...switches,
+  ...urls,
 };
 export default constants;

express-api/src/constants/urls.ts

@@ -0,0 +1,6 @@
+const urls = {
+  GEOCODER: {
+    HOSTURI: 'https://geocoder.api.gov.bc.ca',
+  },
+};
+export default urls;

express-api/src/services/geocoder/geocoderService.ts

@@ -0,0 +1,75 @@
+import { IAddressModel } from '@/services/geocoder/interfaces/IAddressModel';
+import { IFeatureCollectionModel } from '@/services/geocoder/interfaces/IFeatureCollectionModel';
+import constants from '@/constants';
+import { IFeatureModel } from '@/services/geocoder/interfaces/IFeatureModel';
+import { getLongitude, getLatitude, getAddress1 } from './geocoderUtils';
+import { ErrorWithCode } from '@/utilities/customErrors/ErrorWithCode';
+import { ISitePidsResponseModel } from './interfaces/ISitePidsResponseModel';
+
+const mapFeatureToAddress = (feature: IFeatureModel): IAddressModel => {
+  return {
+    siteId: feature.properties.siteID,
+    fullAddress: feature.properties.fullAddress,
+    address1: getAddress1(feature.properties),
+    administrativeArea: feature.properties.localityName,
+    provinceCode: feature.properties.provinceCode,
+    longitude: getLongitude(feature.geometry),
+    latitude: getLatitude(feature.geometry),
+    score: feature.properties.score,
+  };
+};
+
+/**
+ * @description Sends a request to Geocoder for addresses that match the specified 'address'.
+ * @param address String of searchable address. eg. "4000 Seymour St Victoria BC"
+ * @returns address information matching IAddressModel format
+ * @throws ErrorWithCode if the response is not 200 OK
+ */
+export const getSiteAddresses = async (address: string) => {
+  const url = new URL('/addresses.json', constants.GEOCODER.HOSTURI);
+  url.searchParams.append('addressString', address);
+
+  const response = await fetch(url.toString(), {
+    headers: {
+      apiKey: process.env.GEOCODER__KEY,
+    },
+  });
+
+  if (!response.ok) {
+    throw new ErrorWithCode('Failed to fetch data', response.status);
+  }
+
+  const responseData = await response.json();
+  const featureCollection: IFeatureCollectionModel = responseData;
+  const addressInformation: IAddressModel = mapFeatureToAddress(featureCollection.features[0]);
+
+  return addressInformation;
+};
+
+/**
+ * @description Sends a request to Geocoder for all parcel identifiers (PIDs) associated with an individual site.
+ * @param siteId a unique identifier assigned to every site in B.C.
+ * @returns Valid 'siteId' values for an address
+ * @throws ErrorWithCode if result is not 200 OK
+ */
+export const getPids = async (siteId: string) => {
+  const url = new URL(`/parcels/pids/${siteId}.json`, constants.GEOCODER.HOSTURI);
+  const result = await fetch(url.toString(), {
+    headers: {
+      apiKey: process.env.GEOCODER_KEY,
+    },
+  });
+
+  if (result.status != 200) {
+    throw new ErrorWithCode(result.statusText, result.status);
+  }
+
+  const resultData = await result.json();
+  const pidInformation: ISitePidsResponseModel = resultData;
+  return pidInformation;
+};
+
+export const GeocoderService = {
+  getSiteAddresses,
+  getPids,
+};

express-api/src/services/geocoder/geocoderUtils.ts

@@ -0,0 +1,77 @@
+/**
+ * geocoderUtils.ts - Utility functions for working with geocoding data
+ */
+
+import { IPropertyModel } from '@/services/geocoder/interfaces/IPropertyModel';
+import { IGeometryModel } from '@/services/geocoder/interfaces/IGeometryModel';
+import { IFeatureModel } from '@/services/geocoder/interfaces/IFeatureModel';
+import { IAddressModel } from '@/services/geocoder/interfaces/IAddressModel';
+
+/**
+ * Constructs address string based on property data.
+ * @param properties - The property data.
+ * @returns The constructed address string.
+ */
+export const getAddress1 = (properties: IPropertyModel): string => {
+  const address = [];
+
+  if (properties.civicNumber) address.push(properties.civicNumber);
+
+  if (properties.isStreetTypePrefix && properties.streetType) address.push(properties.streetType);
+
+  if (properties.isStreetDirectionPrefix && properties.streetDirection)
+    address.push(properties.streetDirection);
+
+  if (properties.streetName) address.push(properties.streetName);
+
+  if (properties.streetQualifier) address.push(properties.streetQualifier);
+
+  if (!properties.isStreetDirectionPrefix && properties.streetDirection)
+    address.push(properties.streetDirection);
+
+  if (!properties.isStreetTypePrefix && properties.streetType) address.push(properties.streetType);
+
+  return address.join(' ');
+};
+
+/**
+ * Retrieves latitude from geometry data.
+ * @param geometry - The geometry data.
+ * @returns The latitude value.
+ */
+export const getLatitude = (geometry: IGeometryModel): number => {
+  if (geometry.coordinates && geometry.coordinates.length === 2) {
+    return geometry.coordinates[1];
+  }
+  return 0;
+};
+
+/**
+ * Retrieves longitude from geometry data.
+ * @param geometry - The geometry data.
+ * @returns The longitude value.
+ */
+export const getLongitude = (geometry: IGeometryModel): number => {
+  if (geometry.coordinates && geometry.coordinates.length === 2) {
+    return geometry.coordinates[0];
+  }
+  return 0;
+};
+
+/**
+ * Maps feature data to address data.
+ * @param feature - The feature data.
+ * @returns The mapped address data.
+ */
+export const mapFeatureToAddress = (feature: IFeatureModel): IAddressModel => {
+  return {
+    siteId: feature.properties.siteID,
+    fullAddress: feature.properties.fullAddress,
+    address1: getAddress1(feature.properties),
+    administrativeArea: feature.properties.localityName,
+    provinceCode: feature.properties.provinceCode,
+    longitude: getLongitude(feature.geometry),
+    latitude: getLatitude(feature.geometry),
+    score: feature.properties.score,
+  };
+};

express-api/src/services/geocoder/interfaces/IAddressModel.ts

@@ -0,0 +1,10 @@
+export interface IAddressModel {
+  siteId: string;
+  fullAddress: string;
+  address1: string;
+  administrativeArea: string;
+  provinceCode: string;
+  latitude: number;
+  longitude: number;
+  score: number;
+}

express-api/src/services/geocoder/interfaces/ICrsModel.ts

@@ -0,0 +1,4 @@
+export interface ICrsModel {
+  type: string;
+  properties: { [key: string]: unknown };
+}

express-api/src/services/geocoder/interfaces/IFaultModel.ts

@@ -0,0 +1,5 @@
+export interface IFaultModel {
+  element: string;
+  fault: string;
+  penalty: number;
+}

express-api/src/services/geocoder/interfaces/IFeatureCollectionModel.ts

@@ -0,0 +1,23 @@
+import { ICrsModel } from '@/services/geocoder/interfaces/ICrsModel';
+import { IFeatureModel } from '@/services/geocoder/interfaces/IFeatureModel';
+
+export interface IFeatureCollectionModel {
+  type: string;
+  queryAddress: string;
+  searchTimestamp: string;
+  executionTime: number;
+  version: string;
+  baseDataDate: string;
+  crs: ICrsModel;
+  interpolation: string;
+  echo: string;
+  locationDescripture: string;
+  setback: number;
+  minScore: number;
+  maxResults: number;
+  disclaimer: string;
+  privacyStatement: string;
+  copyrightNotice: string;
+  copyrightLicense: string;
+  features: IFeatureModel[];
+}

express-api/src/services/geocoder/interfaces/IFeatureModel.ts

@@ -0,0 +1,8 @@
+import { IGeometryModel } from '@/services/geocoder/interfaces/IGeometryModel';
+import { IPropertyModel } from '@/services/geocoder/interfaces/IPropertyModel';
+
+export interface IFeatureModel {
+  type: string;
+  geometry: IGeometryModel;
+  properties: IPropertyModel;
+}

express-api/src/services/geocoder/interfaces/IGeometryModel.ts

@@ -0,0 +1,7 @@
+import { ICrsModel } from '@/services/geocoder/interfaces/ICrsModel';
+
+export interface IGeometryModel {
+  type: string;
+  crs: ICrsModel;
+  coordinates: number[];
+}

express-api/src/services/geocoder/interfaces/IPropertyModel.ts

@@ -0,0 +1,35 @@
+import { IFaultModel } from '@/services/geocoder/interfaces/IFaultModel';
+
+export interface IPropertyModel {
+  fullAddress: string;
+  score: number;
+  matchPrecision: string;
+  precisionPoints: number;
+  faults: IFaultModel[];
+  siteName: string;
+  unitDesignator: string;
+  unitNumber: string;
+  unitNumberSuffix: string;
+  civicNumber: string;
+  civicNumberSuffix: string;
+  streetName: string;
+  streetType: string;
+  isStreetTypePrefix: boolean;
+  streetDirection: string;
+  isStreetDirectionPrefix: boolean;
+  streetQualifier: string;
+  localityName: string;
+  localityType: string;
+  electoralArea: string;
+  provinceCode: string;
+  locationPositionalAccuracy: string;
+  locationDescriptor: string;
+  siteID: string;
+  blockID: string;
+  fullSiteDescriptor: string;
+  accessNotes: string;
+  siteStatus: string;
+  siteRetireDate: string;
+  changeDate: string;
+  isOfficial: string;
+}

express-api/src/services/geocoder/interfaces/ISitePidsResponseModel.ts

@@ -0,0 +1,4 @@
+export interface ISitePidsResponseModel {
+  siteID: string;
+  pids: string;
+}