Merge pull request #260 from ideal-postcodes/global_address

Author: cblanc

dist/openapi.json

@@ -41,7 +41,7 @@
     },
     {
       "name": "Licensees",
-      "description": "The Licensee resource represents an alternate legal End User of our data who may not be same entity as the owners of the account.\n\nThe concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.\n\nSublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.\n"
+      "description": "The Licensee resource represents an alternate legal End User of our data who may not be the same entity as the owners of the account.\n\nThe concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.\n\nSublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.\n"
     },
     {
       "name": "Configs",
@@ -346,7 +346,7 @@
         ],
         "summary": "Retrieve by UMPRN",
         "operationId": "UMPRN",
-        "description": "Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID).\n\nUMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.\n\n## Testing\n\nTo test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following\n\n- `0` Returns a successful UMPRN lookup response `2000`\n- `-1` Returns \"UMPRN not found\", error `4044`\n- `-2` Returns \"no lookups remaining\", error `4020`\n- `-3` Returns \"daily (or individual) lookup limit breached\", error `4021`\n\nTest request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.\n\n### Pricing\n\nPer lookup charges apply. Empty responses are not charged.\n",
+        "description": "Returns a multiple occupancy address identified via its UMPRN (Multiple Residence Unique ID).\n\nUMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.\n\n## Testing\n\nTo test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following\n\n- `0` Returns a successful UMPRN lookup response `2000`\n- `-1` Returns \"UMPRN not found\", error `4044`\n- `-2` Returns \"no lookups remaining\", error `4020`\n- `-3` Returns \"daily (or individual) lookup limit breached\", error `4021`\n\nTest request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.\n\n### Pricing\n\nPer lookup charges apply. Empty responses are not charged.\n",
         "parameters": [
           {
             "name": "umprn",
@@ -461,7 +461,7 @@
         ],
         "summary": "Availability",
         "operationId": "KeyAvailability",
-        "description": "Returns public information on your API Key.\n\nThis endpoint can be used for the following:\n- Determine if the key is currently useable via the `available` property\n- Determine available contexts for a an API Key\n- Identify the currently likely context of a user given their location\n\nYou may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).\n",
+        "description": "Returns public information on your API Key.\n\nThis endpoint can be used for the following:\n - Determine if the key is currently usable via the `available` property\n - Determine available contexts for an API Key\n- Identify the currently likely context of a user given their location\n\nYou may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).\n",
         "parameters": [
           {
             "$ref": "#/components/parameters/ApiKeyPathParam"
@@ -743,7 +743,7 @@
           "UK"
         ],
         "summary": "Cleanse Address",
-        "description": "The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.\n\n## Confidence Score\n\nThe confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.\n\n### Deciding on an Acceptable Confidence Score Threshold\n\nDifferent address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organistation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.\n\nWhen determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:\n- Which confidence scores indicate ambigious matches (i.e. up to building level only)\n- Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)\n\nDepending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the throroughfare or building name only? Are accurate organisation names an important feature?\n",
+        "description": "The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.\n\n## Confidence Score\n\nThe confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.\n\n### Deciding on an Acceptable Confidence Score Threshold\n\nDifferent address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organisation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.\n\nWhen determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:\n - Which confidence scores indicate ambiguous matches (i.e. up to building level only)\n- Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)\n\nDepending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the thoroughfare or building name only? Are accurate organisation names an important feature?\n",
         "operationId": "AddressCleanse",
         "parameters": [
           {
@@ -854,7 +854,7 @@
           "US"
         ],
         "summary": "Verify Address",
-        "description": "The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS).\n\nThe address verify API accepts the 3 combination of inputs:\n\n- Free-form address submitted as a single string in `query`\n  - Example: \"123 Main St, Springfield, CO 81073-1119\"\n- Only free-form and zip code address components submitted as separate parameters:\n  - `query` for the street address\n  - `zip_code` for the ZIP code\n  - Example:\n    - `query`: \"123 Main St, Springfield CO\"\n    - `zip_code`: \"81073-1119\"\n- Only free-form, city and state address components submitted as separate parameters:\n  - `query` for the street address\n  - `city` for the city\n  - `state` for the state\n  - Example:\n    - `query`: \"123 Main St\"\n    - `city`: \"Springfield\"\n    - `state`: \"CO\"\n",
+        "description": "The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS).\n\nThe address verify API accepts the 3 combination of inputs:\n\n- Free-form address submitted as a single string in `query`\n  - Example: \"123 Main St, Springfield, CO 81073-1119\"\n- Only free-form and zip code address components submitted as separate parameters:\n  - `query` for the first address line\n  - `zip_code` for the ZIP code\n  - Example:\n    - `query`: \"123 Main St, Springfield CO\"\n    - `zip_code`: \"81073-1119\"\n- Only free-form, city and state address components submitted as separate parameters:\n  - `query` for the first address line\n  - `city` for the city\n  - `state` for the state\n  - Example:\n    - `query`: \"123 Main St\"\n    - `city`: \"Springfield\"\n    - `state`: \"CO\"\n",
         "operationId": "AddressVerify",
         "parameters": [
           {
@@ -885,7 +885,7 @@
                 "properties": {
                   "query": {
                     "type": "string",
-                    "description": "Freeform address input to verify.\n\nCan be submitted standalone, or with the following address components:\n- `zip_code`\n- `city` and `state`\n",
+                    "description": "Address input to verify.\n\nIf submitting a freeform address verification query, enter the full address. E.g. `query=123 Main St, Springfield, CO, 81073`\n\nOtherwise, query can be accompanied with the following address components:\n- `zip_code`\n- `city` and `state`\n\nIf zip_code or `city` and `state` or supplied, please omit this information from query by using it purely for the first address line. E.g. `query=123 Main St`\n",
                     "example": "123 Main St, Springfield, CO 81073"
                   },
                   "zip_code": {
@@ -1473,7 +1473,7 @@
           "Place Search"
         ],
         "summary": "Find Place",
-        "description": "Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.\n\nThis API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation.\n\n## Implementing Place Autocomplete\n\nExtracting the full information of a place is a 2 step process:\n\n1. Retrieve place suggestions via /places\n2. Retrieve the entire place with the ID provided in the suggestion\n\n## Suggestion Format\n\nEach place suggestion contains a descriptive name which you can provide to users to uniquely idenfity a place.\n\n## Rate Limiting and Cost\n\nThe rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.\n\nAutocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.\n",
+        "description": "Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.\n\nThis API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation.\n\n## Implementing Place Autocomplete\n\nExtracting the full information of a place is a 2 step process:\n\n1. Retrieve place suggestions via /places\n2. Retrieve the entire place with the ID provided in the suggestion\n\n## Suggestion Format\n\nEach place suggestion contains a descriptive name which you can provide to users to uniquely identify a place.\n\n## Rate Limiting and Cost\n\nThe rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.\n\nAutocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.\n",
         "operationId": "FindPlace",
         "parameters": [
           {
@@ -9764,10 +9764,8 @@
           },
           "thoroughfare": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Street name",
+            "example": "Georgia Ave"
           },
           "dependant_thoroughfare": {
             "type": "string",
@@ -9778,24 +9776,18 @@
           },
           "building_number": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Address or house number",
+            "example": "2"
           },
           "building_name": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Name of the building associated with the address",
+            "example": "Holland House"
           },
           "sub_building_name": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Name of the sub-building associated with the address",
+            "example": "Kingscourt Post Office"
           },
           "premise": {
             "type": "string",
@@ -9806,10 +9798,8 @@
           },
           "po_box": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "PO Box number",
+            "example": "100"
           },
           "department_name": {
             "type": "string",
@@ -9820,10 +9810,8 @@
           },
           "organisation_name": {
             "type": "string",
-            "description": "Not available for non-UK addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Name of the company or organisation associated with the address",
+            "example": "Farrell's Gift Shop"
           },
           "udprn": {
             "type": "string",
@@ -12305,17 +12293,13 @@
           },
           "primary_number": {
             "type": "string",
-            "description": "Not available for non-US addresses",
-            "enum": [
-              ""
-            ]
+            "description": "House number or PO Box number",
+            "example": "10"
           },
           "secondary_number": {
             "type": "string",
-            "description": "Not available for non-US addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Unit or apartment number",
+            "example": "4"
           },
           "plus_4_code": {
             "type": "string",
@@ -12377,10 +12361,8 @@
           },
           "street_name": {
             "type": "string",
-            "description": "Not available for non-US addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Street name",
+            "example": "Harvey St"
           },
           "street_suffix_abbreviation": {
             "type": "string",
@@ -12398,10 +12380,8 @@
           },
           "building_or_firm_name": {
             "type": "string",
-            "description": "Not available for non-US addresses",
-            "enum": [
-              ""
-            ]
+            "description": "Name of the company or building associated with the address",
+            "example": "Cooper Ltd"
           },
           "address_secondary_abbreviation": {
             "type": "string",