@mountainpass/addressr 2.1.1 → 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

@@ -737,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) {
@@ -984,20 +985,13 @@ async function getPostcode(postcode) {
   const searchResp = await globalThis.esClient.search({
     index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
     body: {
-      size: 0,
+      size: 100,
       query: {
         term: {
           postcodes: postcode
         }
       },
-      aggs: {
-        localities: {
-          terms: {
-            field: 'locality_name.raw',
-            size: 100
-          }
-        }
-      }
+      _source: ['locality_name', 'locality_pid']
     }
   });
   return searchResp;
@@ -1018,18 +1012,6 @@ async function getState(abbreviation) {
             field: 'state_name',
             size: 1
           }
-        },
-        localities: {
-          terms: {
-            field: 'locality_name.raw',
-            size: 1000
-          }
-        },
-        postcodes: {
-          terms: {
-            field: 'postcodes',
-            size: 1000
-          }
         }
       }
     }
@@ -1599,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}`
@@ -182,8 +225,14 @@ function startRest2Server() {
       postcode
     }) => {
       const result = await (0, _addressService.getPostcode)(postcode);
-      const localities = result.body.aggregations.localities.buckets.map(l => ({
-        name: l.key
+      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,
@@ -192,6 +241,7 @@ function startRest2Server() {
       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}`
@@ -233,15 +283,9 @@ function startRest2Server() {
     }) => {
       const result = await (0, _addressService.getState)(abbreviation);
       const stateName = result.body.aggregations.state_name.buckets[0]?.key || abbreviation.toUpperCase();
-      const localities = result.body.aggregations.localities.buckets.map(l => ({
-        name: l.key
-      }));
-      const postcodes = result.body.aggregations.postcodes.buckets.map(p => p.key);
       const body = {
         abbreviation: abbreviation.toUpperCase(),
-        name: stateName,
-        localities,
-        postcodes
+        name: stateName
       };
       const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
       return {
@@ -293,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.1';
+const version = exports.version = '2.1.2';

package/package.json

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