@defra/forms-engine-plugin 4.0.41 → 4.0.42

package/src/server/plugins/map/routes/vts/README.md

@@ -0,0 +1,5 @@
+File in this directory are sourced from https://github.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets
+
+VTS_OUTDOOR_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Outdoor.json
+VTS_DARK_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Dark.json
+VTS_BLACK_AND_WHITE_URL=https://raw.githubusercontent.com/OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets/main/OS_VTS_3857_Black_and_White.json

package/src/server/plugins/map/service.js

@@ -0,0 +1,84 @@
+import { getErrorMessage } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { getJson } from '~/src/server/services/httpService.js'
+
+const logger = createLogger()
+
+/**
+ * Returns an empty result set
+ */
+function empty() {
+  /** @type {OsNamesFindResult[]} */
+  const results = []
+
+  return /** @type {OsNamesFindResponse} */ ({ header: {}, results })
+}
+
+/**
+ * Logs OS names errors
+ * @param {unknown} err - the error
+ * @param {string} endpoint - the OS api endpoint
+ */
+function logErrorAndReturnEmpty(err, endpoint) {
+  const msg = `${getErrorMessage(err)} ${(Boom.isBoom(err) && err.data?.payload?.error?.message) ?? ''}`
+
+  logger.error(err, `Exception occured calling OS names ${endpoint} - ${msg}}`)
+
+  return empty()
+}
+
+/**
+ * Fetch data from OS names API
+ * @param {string} url - the url to get address json data from
+ * @param {string} endpoint - the url endpoint description for logging
+ */
+async function getData(url, endpoint) {
+  const getJsonByType = /** @type {typeof getJson<OsNamesFindResponse>} */ (
+    getJson
+  )
+
+  try {
+    const response = await getJsonByType(url)
+
+    if (response.error) {
+      return logErrorAndReturnEmpty(response.error, endpoint)
+    }
+
+    const results = response.payload
+
+    return results
+  } catch (err) {
+    return logErrorAndReturnEmpty(err, endpoint)
+  }
+}
+
+/**
+ * OS names search find by query
+ * @param {string} query - the search term
+ * @param {string} apiKey - the OS api key
+ */
+export async function find(query, apiKey) {
+  const endpoint = 'find'
+  const url = `https://api.os.uk/search/names/v1/find?key=${apiKey}&query=${query}&fq=local_type:postcode%20local_type:hamlet%20local_type:village%20local_type:town%20local_type:city%20local_type:other_settlement&maxresults=8`
+
+  return getData(url, endpoint)
+}
+
+/**
+ * OS names search nearest by E/N
+ * @param {number} easting - the easting
+ * @param {number} northing - the northing
+ * @param {string} apiKey - the OS api key
+ */
+export async function nearest(easting, northing, apiKey) {
+  const endpoint = 'nearest'
+  const url = `https://api.os.uk/search/names/v1/nearest?key=${apiKey}&point=${easting},${northing}&radius=1000&fq=local_type:Airfield%20local_type:Airport%20local_type:Bus_Station%20local_type:Chemical_Works%20local_type:City%20local_type:Coach_Station%20local_type:Electricity_Distribution%20local_type:Electricity_Production%20local_type:Further_Education%20local_type:Gas_Distribution_or_Storage%20local_type:Hamlet%20local_type:Harbour%20local_type:Helicopter_Station%20local_type:Heliport%20local_type:Higher_or_University_Education%20local_type:Hill_Or_Mountain%20local_type:Hospice%20local_type:Hospital%20local_type:Medical_Care_Accommodation%20local_type:Named_Road%20local_type:Non_State_Primary_Education%20local_type:Non_State_Secondary_Education%20local_type:Other_Settlement%20local_type:Passenger_Ferry_Terminal%20local_type:Port_Consisting_of_Docks_and_Nautical_Berthing%20local_type:Postcode%20local_type:Primary_Education%20local_type:Railway_Station%20local_type:Road_User_Services%20local_type:Secondary_Education%20local_type:Section_Of_Named_Road%20local_type:Section_Of_Numbered_Road%20local_type:Special_Needs_Education%20local_type:Suburban_Area%20local_type:Town%20local_type:Urban_Greenspace%20local_type:Vehicular_Ferry_Terminal%20local_type:Vehicular_Rail_Terminal%20local_type:Village%20local_type:Waterfall%20`
+
+  return getData(url, endpoint)
+}
+
+/**
+ * @import { OsNamesFindResponse, OsNamesFindResult } from '~/src/server/plugins/map/types.js'
+ */

package/src/server/plugins/map/service.test.js

@@ -0,0 +1,144 @@
+import Boom from '@hapi/boom'
+
+import * as service from '~/src/server/plugins/map/service.js'
+import { result as findResult } from '~/src/server/plugins/map/test/__stubs__/find.js'
+import { result as nearestResult } from '~/src/server/plugins/map/test/__stubs__/nearest.js'
+import { getJson } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('Maps service', () => {
+  describe('find', () => {
+    it('should return entires', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: findResult,
+        error: undefined
+      })
+
+      const { results } = await service.find('NW1 6XE', 'apikey')
+
+      expect(results).toHaveLength(8)
+      expect(results.at(1)).toEqual({
+        GAZETTEER_ENTRY: {
+          ID: 'NW26XE',
+          NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW26XE',
+          NAME1: 'NW2 6XE',
+          TYPE: 'other',
+          LOCAL_TYPE: 'Postcode',
+          GEOMETRY_X: 523065,
+          GEOMETRY_Y: 185795,
+          MOST_DETAIL_VIEW_RES: 3500,
+          LEAST_DETAIL_VIEW_RES: 18000,
+          POPULATED_PLACE: 'London',
+          POPULATED_PLACE_URI:
+            'http://data.ordnancesurvey.co.uk/id/4000000074813508',
+          POPULATED_PLACE_TYPE:
+            'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+          DISTRICT_BOROUGH: 'Brent',
+          DISTRICT_BOROUGH_URI:
+            'http://data.ordnancesurvey.co.uk/id/7000000000011447',
+          DISTRICT_BOROUGH_TYPE:
+            'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+          COUNTY_UNITARY: 'Greater London',
+          COUNTY_UNITARY_URI:
+            'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+          COUNTY_UNITARY_TYPE:
+            'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+          REGION: 'London',
+          REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+          COUNTRY: 'England',
+          COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+        }
+      })
+    })
+
+    it('should return an empty response when an error is encountered', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 300,
+          headers: {}
+        }),
+        payload: undefined,
+        error: new Error('Unknown error')
+      })
+
+      const { results } = await service.find('NW1 6XE', 'apikey')
+
+      expect(results).toHaveLength(0)
+      expect(results).toEqual([])
+    })
+
+    it('should return an empty response when a non 200 response is encountered', async () => {
+      jest
+        .mocked(getJson)
+        .mockRejectedValueOnce(
+          Boom.badRequest(
+            'OS API error',
+            new Error('Invalid postcode segments')
+          )
+        )
+
+      const { results } = await service.find('invalid postcode', 'apikey')
+
+      expect(results).toHaveLength(0)
+      expect(results).toEqual([])
+    })
+  })
+
+  describe('nearest', () => {
+    it('should return entries', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: nearestResult,
+        error: undefined
+      })
+
+      const { results } = await service.nearest(700000, 1300000, 'apikey')
+
+      expect(results).toHaveLength(1)
+      expect(results.at(0)).toEqual({
+        GAZETTEER_ENTRY: {
+          ID: 'NW26XE',
+          NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW26XE',
+          NAME1: 'NW2 6XE',
+          TYPE: 'other',
+          LOCAL_TYPE: 'Postcode',
+          GEOMETRY_X: 523065,
+          GEOMETRY_Y: 185795,
+          MOST_DETAIL_VIEW_RES: 3500,
+          LEAST_DETAIL_VIEW_RES: 18000,
+          POPULATED_PLACE: 'London',
+          POPULATED_PLACE_URI:
+            'http://data.ordnancesurvey.co.uk/id/4000000074813508',
+          POPULATED_PLACE_TYPE:
+            'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+          DISTRICT_BOROUGH: 'Brent',
+          DISTRICT_BOROUGH_URI:
+            'http://data.ordnancesurvey.co.uk/id/7000000000011447',
+          DISTRICT_BOROUGH_TYPE:
+            'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+          COUNTY_UNITARY: 'Greater London',
+          COUNTY_UNITARY_URI:
+            'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+          COUNTY_UNITARY_TYPE:
+            'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+          REGION: 'London',
+          REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+          COUNTRY: 'England',
+          COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+        }
+      })
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */

package/src/server/plugins/map/test/__stubs__/find.js

@@ -0,0 +1,271 @@
+/** @type {OsNamesFindResponse} */
+export const result = {
+  header: {
+    uri: 'https://api.os.uk/search/names/v1/find?query=NW1%206XE&fq=local_type%3Apostcode%20local_type%3Ahamlet%20local_type%3Avillage%20local_type%3Atown%20local_type%3Acity%20local_type%3Aother_settlement&maxresults=8',
+    query: 'NW1 6XE',
+    format: 'JSON',
+    maxresults: 8,
+    offset: 0,
+    totalresults: 2016,
+    filter:
+      'fq=local_type:postcode local_type:hamlet local_type:village local_type:town local_type:city local_type:other_settlement'
+  },
+  results: [
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW16XE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW16XE',
+        NAME1: 'NW1 6XE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 527850,
+        GEOMETRY_Y: 182134,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'City of Westminster',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074559881',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'City of Westminster',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011164',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW26XE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW26XE',
+        NAME1: 'NW2 6XE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 523065,
+        GEOMETRY_Y: 185795,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'London',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074813508',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'Brent',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011447',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW36XE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW36XE',
+        NAME1: 'NW3 6XE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 526197,
+        GEOMETRY_Y: 185535,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'Hampstead',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074541613',
+        DISTRICT_BOROUGH: 'Camden',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011244',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW10XE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW10XE',
+        NAME1: 'NW1 0XE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 529608,
+        GEOMETRY_Y: 183996,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'Camden Town',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074557754',
+        DISTRICT_BOROUGH: 'Camden',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011244',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW16AE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW16AE',
+        NAME1: 'NW1 6AE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 527873,
+        GEOMETRY_Y: 182010,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'City of Westminster',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074559881',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'City of Westminster',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011164',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW16DE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW16DE',
+        NAME1: 'NW1 6DE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 527681,
+        GEOMETRY_Y: 182107,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'City of Westminster',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074559881',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'City of Westminster',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011164',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW16EX',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW16EX',
+        NAME1: 'NW1 6EX',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 527534,
+        GEOMETRY_Y: 182220,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'City of Westminster',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074559881',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'City of Westminster',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011164',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    },
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW16HE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW16HE',
+        NAME1: 'NW1 6HE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 527621,
+        GEOMETRY_Y: 182113,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'City of Westminster',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074559881',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'City of Westminster',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011164',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    }
+  ]
+}
+
+/**
+ * @import { OsNamesFindResponse } from '~/src/server/plugins/map/types.js'
+ */

package/src/server/plugins/map/test/__stubs__/nearest.js

@@ -0,0 +1,46 @@
+export const result = {
+  header: {
+    uri: 'https://api.os.uk/search/names/v1/nearest?point=523065%2C185795&radius=1000&fq=local_type%3AAirfield%20local_type%3AAirport%20local_type%3ABus_Station%20local_type%3AChemical_Works%20local_type%3ACity%20local_type%3ACoach_Station%20local_type%3AElectricity_Distribution%20local_type%3AElectricity_Production%20local_type%3AFurther_Education%20local_type%3AGas_Distribution_or_Storage%20local_type%3AHamlet%20local_type%3AHarbour%20local_type%3AHelicopter_Station%20local_type%3AHeliport%20local_type%3AHigher_or_University_Education%20local_type%3AHill_Or_Mountain%20local_type%3AHospice%20local_type%3AHospital%20local_type%3AMedical_Care_Accommodation%20local_type%3ANamed_Road%20local_type%3ANon_State_Primary_Education%20local_type%3ANon_State_Secondary_Education%20local_type%3AOther_Settlement%20local_type%3APassenger_Ferry_Terminal%20local_type%3APort_Consisting_of_Docks_and_Nautical_Berthing%20local_type%3APostcode%20local_type%3APrimary_Education%20local_type%3ARailway_Station%20local_type%3ARoad_User_Services%20local_type%3ASecondary_Education%20local_type%3ASection_Of_Named_Road%20local_type%3ASection_Of_Numbered_Road%20local_type%3ASpecial_Needs_Education%20local_type%3ASuburban_Area%20local_type%3ATown%20local_type%3AUrban_Greenspace%20local_type%3AVehicular_Ferry_Terminal%20local_type%3AVehicular_Rail_Terminal%20local_type%3AVillage%20local_type%3AWaterfall%20',
+    query: 'point=523065,185795 radius=1000',
+    format: 'JSON',
+    maxresults: 1,
+    offset: 0,
+    totalresults: 1,
+    filter:
+      'fq=local_type:Airfield local_type:Airport local_type:Bus_Station local_type:Chemical_Works local_type:City local_type:Coach_Station local_type:Electricity_Distribution local_type:Electricity_Production local_type:Further_Education local_type:Gas_Distribution_or_Storage local_type:Hamlet local_type:Harbour local_type:Helicopter_Station local_type:Heliport local_type:Higher_or_University_Education local_type:Hill_Or_Mountain local_type:Hospice local_type:Hospital local_type:Medical_Care_Accommodation local_type:Named_Road local_type:Non_State_Primary_Education local_type:Non_State_Secondary_Education local_type:Other_Settlement local_type:Passenger_Ferry_Terminal local_type:Port_Consisting_of_Docks_and_Nautical_Berthing local_type:Postcode local_type:Primary_Education local_type:Railway_Station local_type:Road_User_Services local_type:Secondary_Education local_type:Section_Of_Named_Road local_type:Section_Of_Numbered_Road local_type:Special_Needs_Education local_type:Suburban_Area local_type:Town local_type:Urban_Greenspace local_type:Vehicular_Ferry_Terminal local_type:Vehicular_Rail_Terminal local_type:Village local_type:Waterfall'
+  },
+  results: [
+    {
+      GAZETTEER_ENTRY: {
+        ID: 'NW26XE',
+        NAMES_URI: 'http://data.ordnancesurvey.co.uk/id/postcodeunit/NW26XE',
+        NAME1: 'NW2 6XE',
+        TYPE: 'other',
+        LOCAL_TYPE: 'Postcode',
+        GEOMETRY_X: 523065,
+        GEOMETRY_Y: 185795,
+        MOST_DETAIL_VIEW_RES: 3500,
+        LEAST_DETAIL_VIEW_RES: 18000,
+        POPULATED_PLACE: 'London',
+        POPULATED_PLACE_URI:
+          'http://data.ordnancesurvey.co.uk/id/4000000074813508',
+        POPULATED_PLACE_TYPE:
+          'http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#city',
+        DISTRICT_BOROUGH: 'Brent',
+        DISTRICT_BOROUGH_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000011447',
+        DISTRICT_BOROUGH_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/LondonBorough',
+        COUNTY_UNITARY: 'Greater London',
+        COUNTY_UNITARY_URI:
+          'http://data.ordnancesurvey.co.uk/id/7000000000041441',
+        COUNTY_UNITARY_TYPE:
+          'http://data.ordnancesurvey.co.uk/ontology/admingeo/GreaterLondonAuthority',
+        REGION: 'London',
+        REGION_URI: 'http://data.ordnancesurvey.co.uk/id/7000000000041428',
+        COUNTRY: 'England',
+        COUNTRY_URI: 'http://data.ordnancesurvey.co.uk/id/country/england'
+      }
+    }
+  ]
+}

package/src/server/plugins/map/types.js

@@ -0,0 +1,119 @@
+/**
+ * @typedef {{
+ *   ordnanceSurveyApiKey: string
+ * }} MapConfiguration
+ */
+
+//
+// Route types
+//
+
+/**
+ * Map proxy query params
+ * @typedef {object} MapProxyQuery
+ * @property {string} url - the proxied url
+ */
+
+/**
+ * Map geocode query params
+ * @typedef {object} MapGeocodeQuery
+ * @property {string} query - name query
+ */
+
+/**
+ * Map reverse geocode query params
+ * @typedef {object} MapReverseGeocodeQuery
+ * @property {number} easting - the Easting point
+ * @property {number} northing - the Northing point
+ */
+
+/**
+ * Map geocode get request
+ * @typedef {object} MapProxyGetRequestRefs
+ * @property {MapProxyQuery} Query - Request query
+ */
+
+/**
+ * Map geocode get request
+ * @typedef {object} MapGeocodeGetRequestRefs
+ * @property {MapGeocodeQuery} Query - Request query
+ */
+
+/**
+ * Map reverst geocode get request
+ * @typedef {object} MapReverseGeocodeGetRequestRefs
+ * @property {MapReverseGeocodeQuery} Query - Request query
+ */
+
+/**
+ * @typedef {MapProxyGetRequestRefs} MapProxyRequestRefs
+ * @typedef {MapGeocodeGetRequestRefs} MapGeocodeRequestRefs
+ * @typedef {MapReverseGeocodeGetRequestRefs} MapReverseGeocodeRequestRefs
+ * @typedef {Request<MapGeocodeGetRequestRefs>} MapProxyGetRequest
+ * @typedef {Request<MapGeocodeGetRequestRefs>} MapGeocodeGetRequest
+ * @typedef {Request<MapReverseGeocodeGetRequestRefs>} MapReverseGeocodeGetRequest
+ * @typedef {MapProxyGetRequest | MapGeocodeGetRequest | MapReverseGeocodeGetRequest} MapRequest
+ */
+
+//
+// Service types
+//
+
+/**
+ * @typedef {object} OsNamesFindResponse
+ * @property {OsNamesFindHeader} header - Metadata about the search request and results.
+ * @property {OsNamesFindResult[]} results - An array of matched place records from the search.
+ */
+
+/**
+ * @typedef {object} OsNamesFindHeader
+ * @property {string} uri - The query URI (usually same as search text).
+ * @property {string} query - The original text query string passed to the API.
+ * @property {string} format - The response format returned (e.g., "JSON").
+ * @property {number} maxresults - The maximum number of results requested.
+ * @property {number} offset - The offset used in the search results.
+ * @property {number} totalresults - The total number of results that matched the query.
+ * @property {string} filter - The original filter string passed to the API.
+ */
+
+/**
+ * @typedef {object} OsNamesFindGazetteerEntry
+ * @property {string} ID - Unique identifier for the place/feature.
+ * @property {string} NAMES_URI - A URI (identifier) for this named feature.
+ * @property {string} NAME1 - Primary name of the feature.
+ * @property {string} TYPE - General type classification of the feature.
+ * @property {string} LOCAL_TYPE - Local or more specific type classification.
+ * @property {number} GEOMETRY_X - Easting coordinate (British National Grid).
+ * @property {number} GEOMETRY_Y - Northing coordinate (British National Grid).
+ * @property {number} MOST_DETAIL_VIEW_RES - Most detailed resolution available.
+ * @property {number} LEAST_DETAIL_VIEW_RES - Least detailed resolution available.
+ * @property {number} [MBR_XMIN] - Minimum bounding box X (easting).
+ * @property {number} [MBR_YMIN] - Minimum bounding box Y (northing).
+ * @property {number} [MBR_XMAX] - Maximum bounding box X (easting).
+ * @property {number} [MBR_YMAX] - Maximum bounding box Y (northing).
+ * @property {string} [DISTRICT_BOROUGH] - (Optional) District borough.
+ * @property {string} [DISTRICT_BOROUGH_URI] - (Optional) URI for the district borough.
+ * @property {string} [DISTRICT_BOROUGH_TYPE] - (Optional) Type of the district borough.
+ * @property {string} [POSTCODE_DISTRICT] - (Optional) Postcode district.
+ * @property {string} [POSTCODE_DISTRICT_URI] - (Optional) URI for the postcode district.
+ * @property {string} [POPULATED_PLACE] - (Optional) Name of associated populated place.
+ * @property {string} [POPULATED_PLACE_URI] - (Optional) URI of populated place.
+ * @property {string} [POPULATED_PLACE_TYPE] - (Optional) Type of populated place.
+ * @property {string} [COUNTY_UNITARY] - (Optional) County or unitary authority name.
+ * @property {string} [COUNTY_UNITARY_URI] - (Optional) URI for county/unitary authority.
+ * @property {string} [COUNTY_UNITARY_TYPE] - (Optional) Classification of county/unitary authority.
+ * @property {string} [REGION] - (Optional) Region name.
+ * @property {string} [REGION_URI] - (Optional) URI for region.
+ * @property {string} [COUNTRY] - (Optional) Country name.
+ * @property {string} [COUNTRY_URI] - (Optional) URI for country.
+ */
+
+/**
+ * OS names GAZETTEER_ENTRY response
+ * @typedef {object} OsNamesFindResult
+ * @property {OsNamesFindGazetteerEntry} GAZETTEER_ENTRY - Gazetteer entry
+ */
+
+/**
+ * @import { Request } from '@hapi/hapi'
+ */