@mountainpass/addressr 2.1.0 → 2.1.2

package/lib/client/elasticsearch.js

@@ -113,6 +113,9 @@ async function initIndex(esClient, clear, synonyms) {
         },
         confidence: {
           type: 'integer'
+        },
+        locality_pid: {
+          type: 'keyword'
         }
       }
     }

package/lib/service/address-service.js

@@ -9,6 +9,8 @@ exports.fetchGnafFile = fetchGnafFile;
 exports.getAddress = getAddress;
 exports.getAddresses = getAddresses;
 exports.getLocality = getLocality;
+exports.getPostcode = getPostcode;
+exports.getState = getState;
 exports.loadGnaf = loadGnaf;
 exports.mapAddressDetails = mapAddressDetails;
 exports.searchForAddress = searchForAddress;
@@ -735,7 +737,8 @@ async function loadAddressDetails(file, expectedCount, context, {
             sla,
             ssla,
             structured,
-            confidence: structured.structured.confidence
+            confidence: structured.structured.confidence,
+            locality_pid: row.LOCALITY_PID
           });
         }
         if (indexingBody.length > 0) {
@@ -934,20 +937,29 @@ async function getLocality(pid) {
   return resp;
 }
 async function searchForPostcode(searchString) {
+  const query = searchString && searchString.length > 0 ? {
+    bool: {
+      filter: [{
+        prefix: {
+          postcodes: searchString
+        }
+      }]
+    }
+  } : {
+    bool: {
+      filter: [{
+        exists: {
+          field: 'postcodes'
+        }
+      }]
+    }
+  };
   const searchResp = await globalThis.esClient.search({
     index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
     body: {
       from: 0,
       size: 0,
-      query: {
-        bool: {
-          filter: [{
-            prefix: {
-              postcodes: searchString
-            }
-          }]
-        }
-      },
+      query,
       aggs: {
         postcodes: {
           terms: {
@@ -969,6 +981,43 @@ async function searchForPostcode(searchString) {
   logger('postcode hits', JSON.stringify(searchResp.body.aggregations, undefined, 2));
   return searchResp;
 }
+async function getPostcode(postcode) {
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      size: 100,
+      query: {
+        term: {
+          postcodes: postcode
+        }
+      },
+      _source: ['locality_name', 'locality_pid']
+    }
+  });
+  return searchResp;
+}
+async function getState(abbreviation) {
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      size: 0,
+      query: {
+        term: {
+          state_abbreviation: abbreviation.toUpperCase()
+        }
+      },
+      aggs: {
+        state_name: {
+          terms: {
+            field: 'state_name',
+            size: 1
+          }
+        }
+      }
+    }
+  });
+  return searchResp;
+}
 async function searchForState(searchString) {
   const query = searchString ? {
     bool: {
@@ -1532,10 +1581,12 @@ async function getAddress(addressId) {
     });
     // TODO: store hash in address
     const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(json)).digest('hex');
+    const localityPid = jsonX.body._source.locality_pid;
     return {
       link,
       json,
-      hash
+      hash,
+      localityPid
     };
   } catch (error_) {
     error('error getting record from elastic search', error_);

package/lib/src/waycharter-server.js

@@ -47,10 +47,37 @@ function startRest2Server() {
       const {
         json,
         hash,
-        statusCode
+        statusCode,
+        localityPid
       } = await (0, _addressService.getAddress)(pid);
+      const links = [];
+      if (localityPid) {
+        links.push({
+          rel: 'related',
+          uri: `/localities/${localityPid}`,
+          title: json.structured?.locality?.name || 'Locality'
+        });
+      }
+      if (json.structured) {
+        const s = json.structured;
+        if (s.postcode) {
+          links.push({
+            rel: 'related',
+            uri: `/postcodes/${s.postcode}`,
+            title: `Postcode ${s.postcode}`
+          });
+        }
+        if (s.state && s.state.abbreviation) {
+          links.push({
+            rel: 'related',
+            uri: `/states/${s.state.abbreviation}`,
+            title: s.state.name
+          });
+        }
+      }
       return {
         body: json,
+        links,
         headers: {
           etag: `"${_version.version}-${hash}"`,
           'cache-control': `public, max-age=${ONE_WEEK}`
@@ -114,9 +141,25 @@ function startRest2Server() {
     }) => {
       const resp = await (0, _addressService.getLocality)(pid);
       const source = resp.body._source;
+      const links = [];
+      if (source.primary_postcode) {
+        links.push({
+          rel: 'related',
+          uri: `/postcodes/${source.primary_postcode}`,
+          title: `Postcode ${source.primary_postcode}`
+        });
+      }
+      if (source.state_abbreviation) {
+        links.push({
+          rel: 'related',
+          uri: `/states/${source.state_abbreviation}`,
+          title: source.state_name
+        });
+      }
       const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(source)).digest('hex');
       return {
         body: source,
+        links,
         headers: {
           etag: `"${_version.version}-${hash}"`,
           'cache-control': `public, max-age=${ONE_WEEK}`
@@ -177,38 +220,56 @@ function startRest2Server() {
     }]
   });
   const postcodesType = waycharter.registerCollection({
+    itemPath: '/:postcode',
+    itemLoader: async ({
+      postcode
+    }) => {
+      const result = await (0, _addressService.getPostcode)(postcode);
+      const hits = result.body.hits.hits;
+      const localities = hits.map(h => ({
+        name: h._source.locality_name
+      }));
+      const links = hits.map(h => ({
+        rel: 'related',
+        uri: `/localities/${h._source.locality_pid}`,
+        title: h._source.locality_name
+      }));
+      const body = {
+        postcode,
+        localities
+      };
+      const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        links,
+        headers: {
+          etag: `"${_version.version}-${hash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        },
+        status: 200
+      };
+    },
     collectionPath: '/postcodes',
     collectionLoader: async ({
       q
     }) => {
-      if (q && q.length > 2) {
-        const result = await (0, _addressService.searchForPostcode)(q);
-        const buckets = result.body.aggregations.postcodes.buckets;
-        const body = buckets.map(bucket => ({
-          postcode: bucket.key,
-          localities: bucket.localities.buckets.map(l => ({
-            name: l.key
-          }))
-        }));
-        const responseHash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
-        return {
-          body,
-          hasMore: false,
-          headers: {
-            etag: `"${_version.version}-${responseHash}"`,
-            'cache-control': `public, max-age=${ONE_WEEK}`
-          }
-        };
-      } else {
-        return {
-          body: [],
-          hasMore: false,
-          headers: {
-            etag: `"${_version.version}"`,
-            'cache-control': `public, max-age=${ONE_WEEK}`
-          }
-        };
-      }
+      const result = await (0, _addressService.searchForPostcode)(q || '');
+      const buckets = result.body.aggregations.postcodes.buckets;
+      const body = buckets.map(bucket => ({
+        postcode: bucket.key,
+        localities: bucket.localities.buckets.map(l => ({
+          name: l.key
+        }))
+      }));
+      const responseHash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        hasMore: false,
+        headers: {
+          etag: `"${_version.version}-${responseHash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        }
+      };
     },
     filters: [{
       rel: 'https://addressr.io/rels/postcode-search',
@@ -216,11 +277,31 @@ function startRest2Server() {
     }]
   });
   const statesType = waycharter.registerCollection({
+    itemPath: '/:abbreviation',
+    itemLoader: async ({
+      abbreviation
+    }) => {
+      const result = await (0, _addressService.getState)(abbreviation);
+      const stateName = result.body.aggregations.state_name.buckets[0]?.key || abbreviation.toUpperCase();
+      const body = {
+        abbreviation: abbreviation.toUpperCase(),
+        name: stateName
+      };
+      const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        headers: {
+          etag: `"${_version.version}-${hash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        },
+        status: 200
+      };
+    },
     collectionPath: '/states',
     collectionLoader: async ({
       q
     }) => {
-      const result = await (0, _addressService.searchForState)(q && q.length > 1 ? q : undefined);
+      const result = await (0, _addressService.searchForState)(q || undefined);
       const buckets = result.body.aggregations.states.buckets;
       const body = buckets.map(bucket => ({
         abbreviation: bucket.key,
@@ -256,12 +337,199 @@ function startRest2Server() {
       };
     }
   });
+  waycharter.registerResourceType({
+    path: '/api-docs',
+    loader: async () => {
+      const spec = {
+        openapi: '3.0.3',
+        info: {
+          title: 'Addressr by Mountain Pass',
+          description: 'Free Australian Address Validation, Search and Autocomplete. This OpenAPI spec is supplementary — the HATEOAS link-driven API is the authoritative contract.',
+          version: _version.version
+        },
+        paths: {
+          '/addresses': {
+            get: {
+              summary: 'Search Addresses',
+              operationId: 'searchAddresses',
+              parameters: [{
+                name: 'q',
+                in: 'query',
+                required: true,
+                schema: {
+                  type: 'string',
+                  minLength: 3
+                },
+                description: 'Address search query'
+              }],
+              responses: {
+                200: {
+                  description: 'List of matching addresses'
+                }
+              }
+            }
+          },
+          '/addresses/{pid}': {
+            get: {
+              summary: 'Get Address',
+              operationId: 'getAddress',
+              parameters: [{
+                name: 'pid',
+                in: 'path',
+                required: true,
+                schema: {
+                  type: 'string'
+                },
+                description: 'Address persistent identifier'
+              }],
+              responses: {
+                200: {
+                  description: 'Address details with structured data'
+                }
+              }
+            }
+          },
+          '/localities': {
+            get: {
+              summary: 'Search Localities',
+              operationId: 'searchLocalities',
+              parameters: [{
+                name: 'q',
+                in: 'query',
+                required: true,
+                schema: {
+                  type: 'string',
+                  minLength: 2
+                },
+                description: 'Locality/suburb name search query'
+              }],
+              responses: {
+                200: {
+                  description: 'List of matching localities'
+                }
+              }
+            }
+          },
+          '/localities/{pid}': {
+            get: {
+              summary: 'Get Locality',
+              operationId: 'getLocality',
+              parameters: [{
+                name: 'pid',
+                in: 'path',
+                required: true,
+                schema: {
+                  type: 'string'
+                },
+                description: 'Locality persistent identifier'
+              }],
+              responses: {
+                200: {
+                  description: 'Locality details'
+                }
+              }
+            }
+          },
+          '/postcodes': {
+            get: {
+              summary: 'Search Postcodes',
+              operationId: 'searchPostcodes',
+              parameters: [{
+                name: 'q',
+                in: 'query',
+                required: false,
+                schema: {
+                  type: 'string'
+                },
+                description: 'Postcode prefix search query. Omit to list all postcodes.'
+              }],
+              responses: {
+                200: {
+                  description: 'List of matching postcodes with associated localities'
+                }
+              }
+            }
+          },
+          '/postcodes/{postcode}': {
+            get: {
+              summary: 'Get Postcode',
+              operationId: 'getPostcode',
+              parameters: [{
+                name: 'postcode',
+                in: 'path',
+                required: true,
+                schema: {
+                  type: 'string'
+                },
+                description: 'Australian postcode'
+              }],
+              responses: {
+                200: {
+                  description: 'Postcode details with associated localities'
+                }
+              }
+            }
+          },
+          '/states': {
+            get: {
+              summary: 'Search States',
+              operationId: 'searchStates',
+              parameters: [{
+                name: 'q',
+                in: 'query',
+                required: false,
+                schema: {
+                  type: 'string'
+                },
+                description: 'State name or abbreviation search. Omit to list all states.'
+              }],
+              responses: {
+                200: {
+                  description: 'List of matching states and territories'
+                }
+              }
+            }
+          },
+          '/states/{abbreviation}': {
+            get: {
+              summary: 'Get State',
+              operationId: 'getState',
+              parameters: [{
+                name: 'abbreviation',
+                in: 'path',
+                required: true,
+                schema: {
+                  type: 'string'
+                },
+                description: 'State/territory abbreviation (e.g., NSW, VIC)'
+              }],
+              responses: {
+                200: {
+                  description: 'State/territory details'
+                }
+              }
+            }
+          }
+        }
+      };
+      return {
+        body: spec,
+        headers: {
+          'cache-control': `public, max-age=${ONE_WEEK}`,
+          'content-type': 'application/json'
+        }
+      };
+    }
+  });
   waycharter.registerResourceType({
     path: '/',
     loader: async () => {
       return {
         body: {},
         links: [...addressesType.additionalPaths, ...localitiesType.additionalPaths, ...postcodesType.additionalPaths, ...statesType.additionalPaths, {
+          rel: 'https://addressr.io/rels/api-docs',
+          uri: '/api-docs'
+        }, {
           rel: 'https://addressr.io/rels/health',
           uri: '/health'
         }],

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.1.0';
+const version = exports.version = '2.1.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",