@mountainpass/addressr 2.1.1 → 2.1.3

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

@@ -18,6 +18,638 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 var app = (0, _express.default)();
 const ONE_DAY = 60 * 60 * 24;
 const ONE_WEEK = ONE_DAY * 7;
+function buildOpenApiSpec(apiVersion) {
+  const schemas = {
+    AddressSearchResult: {
+      type: 'object',
+      properties: {
+        sla: {
+          type: 'string',
+          description: 'Single line address',
+          example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        ssla: {
+          type: 'string',
+          description: 'Short single line address (for addresses with flats)',
+          example: '1/19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        highlight: {
+          type: 'object',
+          description: 'Search term highlights in the address',
+          properties: {
+            sla: {
+              type: 'string'
+            },
+            ssla: {
+              type: 'string'
+            }
+          }
+        },
+        score: {
+          type: 'number',
+          description: 'Search relevance score',
+          example: 5.43
+        },
+        pid: {
+          type: 'string',
+          description: 'Persistent identifier for the address',
+          example: 'GAOT_717882967'
+        }
+      }
+    },
+    Address: {
+      type: 'object',
+      properties: {
+        sla: {
+          type: 'string',
+          example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        structured: {
+          type: 'object',
+          properties: {
+            confidence: {
+              type: 'integer',
+              example: 2
+            },
+            flat: {
+              type: 'object',
+              properties: {
+                number: {
+                  type: 'integer',
+                  example: 1
+                },
+                type: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'UNIT'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'UNIT'
+                    }
+                  }
+                }
+              }
+            },
+            number: {
+              type: 'object',
+              properties: {
+                number: {
+                  type: 'integer',
+                  example: 19
+                }
+              }
+            },
+            street: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  example: 'MURRAY'
+                },
+                type: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'ROAD'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'RD'
+                    }
+                  }
+                }
+              }
+            },
+            locality: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  example: 'CHRISTMAS ISLAND'
+                },
+                class: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'U'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'UNOFFICIAL SUBURB'
+                    }
+                  }
+                }
+              }
+            },
+            postcode: {
+              type: 'string',
+              example: '6798'
+            },
+            state: {
+              type: 'object',
+              properties: {
+                abbreviation: {
+                  type: 'string',
+                  example: 'OT'
+                },
+                name: {
+                  type: 'string',
+                  example: 'OTHER TERRITORIES'
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    LocalitySearchResult: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          example: 'LILYDALE'
+        },
+        state: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              example: 'VICTORIA'
+            },
+            abbreviation: {
+              type: 'string',
+              example: 'VIC'
+            }
+          }
+        },
+        class: {
+          type: 'object',
+          properties: {
+            code: {
+              type: 'string',
+              description: 'Classification code (G=Gazetted, U=Unofficial, T=Topographic, I=Informal)',
+              example: 'G'
+            },
+            name: {
+              type: 'string',
+              example: 'GAZETTED LOCALITY'
+            }
+          }
+        },
+        postcode: {
+          type: 'string',
+          description: 'Primary postcode for this locality',
+          example: '3140'
+        },
+        score: {
+          type: 'number',
+          example: 5.23
+        },
+        pid: {
+          type: 'string',
+          example: 'loc1234567890ab'
+        }
+      }
+    },
+    Locality: {
+      type: 'object',
+      properties: {
+        locality_name: {
+          type: 'string',
+          example: 'CHRISTMAS ISLAND'
+        },
+        locality_class_code: {
+          type: 'string',
+          example: 'U'
+        },
+        locality_class_name: {
+          type: 'string',
+          example: 'UNOFFICIAL SUBURB'
+        },
+        primary_postcode: {
+          type: 'string',
+          example: '6798'
+        },
+        postcodes: {
+          type: 'array',
+          items: {
+            type: 'string'
+          },
+          example: ['6798']
+        },
+        state_abbreviation: {
+          type: 'string',
+          example: 'OT'
+        },
+        state_name: {
+          type: 'string',
+          example: 'OTHER TERRITORIES'
+        },
+        locality_pid: {
+          type: 'string',
+          example: 'loc9984d8beb142'
+        }
+      }
+    },
+    PostcodeSearchResult: {
+      type: 'object',
+      properties: {
+        postcode: {
+          type: 'string',
+          example: '3140'
+        },
+        localities: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                example: 'LILYDALE'
+              }
+            }
+          }
+        }
+      }
+    },
+    PostcodeDetail: {
+      type: 'object',
+      properties: {
+        postcode: {
+          type: 'string',
+          example: '6798'
+        },
+        localities: {
+          type: 'array',
+          description: 'Locality names. Individual locality resources are linked via related Link headers.',
+          items: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                example: 'CHRISTMAS ISLAND'
+              }
+            }
+          }
+        }
+      }
+    },
+    State: {
+      type: 'object',
+      properties: {
+        abbreviation: {
+          type: 'string',
+          example: 'NSW'
+        },
+        name: {
+          type: 'string',
+          example: 'NEW SOUTH WALES'
+        }
+      }
+    },
+    Health: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          example: 'healthy'
+        },
+        version: {
+          type: 'string',
+          example: '2.1.2'
+        },
+        timestamp: {
+          type: 'string',
+          format: 'date-time',
+          example: '2026-04-14T11:17:54.637Z'
+        }
+      }
+    }
+  };
+  return {
+    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. Follow `related` Link headers to navigate between addresses, localities, postcodes and states.',
+      version: apiVersion
+    },
+    servers: [{
+      url: 'https://addressr.p.rapidapi.com',
+      description: 'RapidAPI'
+    }],
+    paths: {
+      '/addresses': {
+        get: {
+          summary: 'Search Addresses',
+          description: 'Search Australian addresses by any component — street, suburb, postcode, state. Supports fuzzy and prefix matching.',
+          operationId: 'searchAddresses',
+          tags: ['Addresses'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: true,
+            schema: {
+              type: 'string',
+              minLength: 3
+            },
+            example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND',
+            description: 'Address search query (min 3 characters)'
+          }, {
+            name: 'page',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'integer',
+              minimum: 0
+            },
+            example: 0,
+            description: 'Zero-based page number for pagination'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching addresses',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/AddressSearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/addresses/{pid}': {
+        get: {
+          summary: 'Get Address',
+          description: 'Get full structured details for a specific address. Response includes Link headers with `related` rels to the locality, postcode, and state.',
+          operationId: 'getAddress',
+          tags: ['Addresses'],
+          parameters: [{
+            name: 'pid',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: 'GAOT_717882967',
+            description: 'Address persistent identifier (G-NAF PID)'
+          }],
+          responses: {
+            200: {
+              description: 'Address details with structured data',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Address'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/localities': {
+        get: {
+          summary: 'Search Localities',
+          description: 'Search Australian suburbs and localities by name. Supports fuzzy and prefix matching. Returns localities with state, postcode, and classification.',
+          operationId: 'searchLocalities',
+          tags: ['Localities'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: true,
+            schema: {
+              type: 'string',
+              minLength: 2
+            },
+            example: 'lilydale',
+            description: 'Locality/suburb name search query (min 2 characters)'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/LocalitySearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/localities/{pid}': {
+        get: {
+          summary: 'Get Locality',
+          description: 'Get details for a specific locality. Response includes Link headers with `related` rels to the postcode and state.',
+          operationId: 'getLocality',
+          tags: ['Localities'],
+          parameters: [{
+            name: 'pid',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: 'loc9984d8beb142',
+            description: 'Locality persistent identifier'
+          }],
+          responses: {
+            200: {
+              description: 'Locality details',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Locality'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/postcodes': {
+        get: {
+          summary: 'Search Postcodes',
+          description: 'Search Australian postcodes by prefix. Returns matching postcodes with their associated localities. Omit `q` to list all postcodes in ascending order.',
+          operationId: 'searchPostcodes',
+          tags: ['Postcodes'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'string'
+            },
+            example: '314',
+            description: 'Postcode prefix search query (0+ characters). Omit to list all postcodes.'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching postcodes with associated localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/PostcodeSearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/postcodes/{postcode}': {
+        get: {
+          summary: 'Get Postcode',
+          description: 'Get details for a specific postcode including all associated localities. Each locality is linked via a `related` Link header.',
+          operationId: 'getPostcode',
+          tags: ['Postcodes'],
+          parameters: [{
+            name: 'postcode',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: '6798',
+            description: 'Australian postcode'
+          }],
+          responses: {
+            200: {
+              description: 'Postcode details with associated localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/PostcodeDetail'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/states': {
+        get: {
+          summary: 'Search States',
+          description: 'Search Australian states and territories by name or abbreviation. Omit `q` to list all states alphabetically.',
+          operationId: 'searchStates',
+          tags: ['States'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'string'
+            },
+            example: 'New',
+            description: 'State name or abbreviation search (0+ characters). Omit to list all states.'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching states and territories',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/State'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/states/{abbreviation}': {
+        get: {
+          summary: 'Get State',
+          description: 'Get details for a specific state or territory. Use `/localities?q=` or `/postcodes?q=` to search within a state.',
+          operationId: 'getState',
+          tags: ['States'],
+          parameters: [{
+            name: 'abbreviation',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string',
+              enum: ['ACT', 'NSW', 'NT', 'QLD', 'SA', 'TAS', 'VIC', 'WA', 'OT']
+            },
+            example: 'NSW',
+            description: 'State/territory abbreviation'
+          }],
+          responses: {
+            200: {
+              description: 'State/territory details',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/State'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/health': {
+        get: {
+          summary: 'Health Check',
+          description: 'Check API service status. Returns version, timestamp, and health status.',
+          operationId: 'healthCheck',
+          tags: ['System'],
+          responses: {
+            200: {
+              description: 'API is healthy',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Health'
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    components: {
+      schemas
+    },
+    tags: [{
+      name: 'Addresses',
+      description: 'Search and retrieve addresses'
+    }, {
+      name: 'Localities',
+      description: 'Search and retrieve suburbs/localities'
+    }, {
+      name: 'Postcodes',
+      description: 'Search and retrieve postcodes'
+    }, {
+      name: 'States',
+      description: 'Search and retrieve states/territories'
+    }, {
+      name: 'System',
+      description: 'System endpoints'
+    }]
+  };
+}
 var serverPort = process.env.PORT || 8080;
 var logger = (0, _debug.default)('api');
 var error = (0, _debug.default)('error');
@@ -47,10 +679,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 +773,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 +857,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 +873,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 +915,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 +969,28 @@ function startRest2Server() {
       };
     }
   });
+  waycharter.registerResourceType({
+    path: '/api-docs',
+    loader: async () => {
+      const spec = buildOpenApiSpec(_version.version);
+      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.3';

package/package.json

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