================
CODE SNIPPETS
================
TITLE: Install AddressZen Magento Plugin via Composer
DESCRIPTION: Installs the AddressZen Magento plugin using Composer and enables it along with necessary Magento setup commands.

SOURCE: https://docs.addresszen.com/docs/integrations/magento

LANGUAGE: shell
CODE:
```
composer require addresszen/magento
```

LANGUAGE: shell
CODE:
```
magento module:enable Addresszen_Lookup
magento setup:upgrade
magento setup:di:compile
magento setup:static-content:deploy -f
```

--------------------------------

TITLE: Example API Key Format
DESCRIPTION: An example of what an AddressZen API Key looks like. API Keys are strings of characters used for authentication and typically begin with 'ak_'.

SOURCE: https://docs.addresszen.com/docs/guides/api-key

LANGUAGE: text
CODE:
```
ak_ksqa49sjSdAEDq9I88
```

--------------------------------

TITLE: Install AddressZen OpenAPI Package
DESCRIPTION: This command installs the AddressZen OpenAPI package using npm. This package provides API typings and the OpenAPI v3 specification files.

SOURCE: https://docs.addresszen.com/docs/libraries/open-api

LANGUAGE: bash
CODE:
```
npm install @addresszen/openapi
```

--------------------------------

TITLE: Install Address Lookup via npm
DESCRIPTION: Installs the @addresszen/address-lookup package using npm. This is the first step to using the Address Lookup service in your project.

SOURCE: https://docs.addresszen.com/docs/address-lookup/npm

LANGUAGE: bash
CODE:
```
npm install @addresszen/address-lookup
```

--------------------------------

TITLE: Premise and Organisation Examples
DESCRIPTION: Provides examples for premise details like 'building_name' (e.g., 'Rose Cottage') and 'sub_building_name' (e.g., 'Flat 1'), as well as an example for 'organisation' (e.g., 'Oak Tree Limited').

SOURCE: https://docs.addresszen.com/docs/data/ecad

LANGUAGE: text
CODE:
```
Rose Cottage
```

LANGUAGE: text
CODE:
```
Flat 1
```

LANGUAGE: text
CODE:
```
Oak Tree Limited
```

--------------------------------

TITLE: Version Pinning Example for CDN Usage
DESCRIPTION: This example illustrates the recommended practice of pinning a specific version of the Address Lookup script when using a JavaScript CDN in a production environment. Pinning ensures stability and prevents unexpected breakages due to future updates.

SOURCE: https://docs.addresszen.com/docs/address-lookup/script

LANGUAGE: html
CODE:
```
<script src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup"></script>
```

--------------------------------

TITLE: Clone AddressZen Magento Plugin Repository
DESCRIPTION: Demonstrates how to clone the AddressZen Magento plugin repository from GitHub, either the main project or a specific version using a tag.

SOURCE: https://docs.addresszen.com/docs/integrations/magento

LANGUAGE: git
CODE:
```
git clone --depth=1 https://github.com/addresszen/magento.git
```

LANGUAGE: git
CODE:
```
git clone --branch <tag> -depth=1 https://github.com/addresszen/magento.git
```

--------------------------------

TITLE: Install Address Lookup Package
DESCRIPTION: Installs the Address Lookup library as a project dependency using npm. This is the first step to using the library in your React application.

SOURCE: https://docs.addresszen.com/docs/address-lookup/react

LANGUAGE: bash
CODE:
```
npm install --save @addresszen/address-lookup
```

--------------------------------

TITLE: GET /keys/:key
DESCRIPTION: Retrieves details for a given API key. Supports keys starting with 'sl_' and returns a 'datasets' attribute indicating access to specific datasets like PAF, Multiple Residence, or Not Yet Built.

SOURCE: https://docs.addresszen.com/docs/changelog

LANGUAGE: APIDOC
CODE:
```
## GET /keys/:key

### Description
Retrieves details for a given API key. Supports keys starting with 'sl_' and returns a 'datasets' attribute indicating access to specific datasets like PAF, Multiple Residence, or Not Yet Built.

### Method
GET

### Endpoint
/keys/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key to retrieve details for.

### Response
#### Success Response (200)
- **datasets** (array) - A list of datasets the key has access to (e.g., "PAF", "Multiple Residence", "Not Yet Built").
```

--------------------------------

TITLE: Example API Postcode Lookup (No Licensee)
DESCRIPTION: Demonstrates a standard API request for postcode lookups before implementing sublicensing. This format is used when a single licensee is managed under a key.

SOURCE: https://docs.addresszen.com/docs/guides/sublicensing

LANGUAGE: url
CODE:
```
/v1/postcodes/?api_key=ak_test
```

--------------------------------

TITLE: Example API Address Autocomplete Lookup (With Licensee)
DESCRIPTION: Demonstrates an API request for address autocompletion using a Sublicensing Key. The licensee key is included to attribute the request to a specific client.

SOURCE: https://docs.addresszen.com/docs/guides/sublicensing

LANGUAGE: url
CODE:
```
/v1/autocomplete/addresses?api_key=sk_i98n29d8dj3K&licensee_key=li_randomkey
```

--------------------------------

TITLE: Retrieve Key Details API
DESCRIPTION: Available datasets can be accessed through the `GET /keys/:key/details` API.

SOURCE: https://docs.addresszen.com/docs/changelog

LANGUAGE: APIDOC
CODE:
```
## GET /keys/:key/details

### Description
Retrieves details about an API key, including the datasets it has access to.

### Method
GET

### Endpoint
/keys/:key/details

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key for which to retrieve details.

### Response
#### Success Response (200)
- **datasets** (array) - A list of datasets accessible by the API key.
  - **name** (string) - The name of the dataset.
  - **access_level** (string) - The level of access to the dataset.

#### Response Example
```json
{
  "datasets": [
    {
      "name": "USA Standard",
      "access_level": "full"
    },
    {
      "name": "Canada Enhanced",
      "access_level": "read-only"
    }
  ]
}
```
```

--------------------------------

TITLE: BigCommerce Script Setup and Configuration
DESCRIPTION: This script snippet initializes the AddressZen integration for BigCommerce. It requires an API key and can be configured with various options to control address lookup and population behavior.

SOURCE: https://docs.addresszen.com/docs/integrations/bigcommerce

LANGUAGE: javascript
CODE:
```
<script>
  window.idpcConfig = {
    apiKey: "Your API Key goes here"
  };
</script>
  
<script 
  async
  type="text/javascript"
  crossorigin="anonymous"
  src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/bigcommerce@3">
</script>
```

LANGUAGE: javascript
CODE:
```
window.idpcConfig = {
   // API Key is not set by default
  apiKey: "",

  // Postcode Lookup is enabled
  postcodeLookup: true,

  // Autocomplete is enabled
  autocomplete: true,

  // Company name field is updated
  populateOrganisation: true,
  // County name field is not updated
  populateCounty: false,
  
  // Advanced configuration
  autocompleteOverride: {},
  postcodeLookupOverride: {}
};
```

--------------------------------

TITLE: Example API Address Autocomplete Lookup (No Licensee)
DESCRIPTION: Shows a typical API request for address autocompletion without specifying a licensee. This is the format used for direct key usage.

SOURCE: https://docs.addresszen.com/docs/guides/sublicensing

LANGUAGE: url
CODE:
```
/v1/autocomplete/addresses?api_key=ak_test
```

--------------------------------

TITLE: Example API Postcode Lookup (With Licensee)
DESCRIPTION: Illustrates how to perform an API request for postcode lookups when using a Sublicensing Key. The licensee key is appended to the request to identify the specific client account.

SOURCE: https://docs.addresszen.com/docs/guides/sublicensing

LANGUAGE: url
CODE:
```
/v1/postcodes/?api_key=sk_i98n29d8dj3K&licensee_key=li_randomkey
```

--------------------------------

TITLE: Install and Initialize Address Lookup Plugin
DESCRIPTION: This snippet shows how to include the AddressZen Address Lookup script and initialize it within a JetFormbuilder HTML block. It requires an API key and maps output fields to form input names. The `onLoaded` function customizes the visibility of the lookup container.

SOURCE: https://docs.addresszen.com/docs/integrations/jetformbuilder

LANGUAGE: html
CODE:
```
<script 
src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup"></script>

<script>
  AddressZen.AddressLookup.setup({
    apiKey: 'YOUR_API_KEY',
    outputFields: {
      line_1: 'input[name="line_1"]',
      line_2: 'input[name="line_2"]',
      city: 'input[name="city"]',
      state: 'input[name="state"]',
      zip_plus_4: 'input[name="zipcode"]'
    },
    onLoaded: function () {
      // This prevents the Address Lookup from being in obscured by the default
      // JetFormbuilder styles
      this.view.container.parentElement.parentElement.style.overflow = 'visible';
    }
  });
</script>
```

--------------------------------

TITLE: Address Verification with cURL
DESCRIPTION: Example of how to call the Address Verification API using cURL. It sends a POST request with JSON payload and includes the API key in the query parameters.

SOURCE: https://docs.addresszen.com/docs/address-verification/getting-started

LANGUAGE: bash
CODE:
```
curl -X POST "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "123 Main St, Springfield, CO 81073"
  }'
```

--------------------------------

TITLE: Install and Initialize Address Lookup Plugin for FormAssembly
DESCRIPTION: This JavaScript code snippet demonstrates how to include the AddressZen Address Lookup library and initialize it on a FormAssembly page. It requires an API key and specific CSS selectors for mapping address output fields. Ensure to replace 'YOUR_API_KEY' and adjust the `outputFields` selectors to match your form's field names.

SOURCE: https://docs.addresszen.com/docs/integrations/formassembly

LANGUAGE: html
CODE:
```
<script src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup"></script>

<script>
  document.addEventListener("DOMContentLoaded", function() {
    AddressZen.AddressLookup.setup({
      apiKey: "YOUR_API_KEY",
      outputFields: {
        line_1: 'input[name="tfa_2"]',
        line_2: 'input[name="tfa_3"]',
        city: 'input[name="tfa_4"]',
        state: 'input[name="tfa_5"]',
        zip_plus_4_code: 'input[name="tfa_6"]'
      }
    });
  });
</script>
```

--------------------------------

TITLE: GET Request for Address Autocomplete
DESCRIPTION: This snippet demonstrates how to make a GET request to the /autocomplete/addresses endpoint to retrieve address suggestions. It's the primary method for initiating an address search.

SOURCE: https://docs.addresszen.com/docs/api/find-address

LANGUAGE: HTTP
CODE:
```
GET 
/autocomplete/addresses
```

--------------------------------

TITLE: Example Custom Address Fields (CAF) Configuration
DESCRIPTION: Provides an example of how to configure custom address fields (CAF) for Zoho CRM contacts and accounts. It demonstrates mapping input IDs to specific address components like line_1, post_town, postcode, and county.

SOURCE: https://docs.addresszen.com/docs/integrations/zoho-crm

LANGUAGE: json
CODE:
```
[
  {
     "line_1": "#Crm_Leads_LEADCF2",
     "post_town": "#Crm_Leads_CITY",
     "postcode": "#Crm_Leads_ZIP",
     "county": "#Crm_Leads_LEADCF3"
  },
  {
     "line_1": "#Crm_Accounts_Lane",
     "post_town": "#Crm_Accounts_Town",
     "postcode": "#Crm_Accounts_Postal_Code",
     "county": "#Crm_Accounts_County",
     "country": "#Crm_Accounts_Country"
  }
]
```

--------------------------------

TITLE: ES Module Integration with AddressLookup Setup
DESCRIPTION: This snippet demonstrates integrating Address Lookup using an ES Module compatible build, suitable for modern browsers. It imports the AddressLookup class from a CDN and sets up the service with an API key and output field configurations.

SOURCE: https://docs.addresszen.com/docs/address-lookup/script

LANGUAGE: html
CODE:
```
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@3/dist/address-finder.esm.js"></script>

<script type="module">
  import { AddressLookup } from "https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled@3/dist/address-finder.esm.js";
  AddressLookup.setup({
    apiKey: "zenkey",
    outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      city: "#city",
      state: "#state",
      zip_plus_4_code: "#zipcode",
    },
  });
</script>
```

--------------------------------

TITLE: Add Additional Output Fields to Address Finder
DESCRIPTION: This example shows how to extend the Address Finder initialization to include additional output fields, such as a country field. It demonstrates adding a new key-value pair to the `outputFields` object, mapping 'country' to a specific input element.

SOURCE: https://docs.addresszen.com/docs/integrations/forminator

LANGUAGE: javascript
CODE:
```
outputFields: {
        line_1: 'input[name="text-1"]',
        line_2: 'input[name="text-2"]',
        city: 'input[name="text-3"]',
        state: 'input[name="text-4"]',
        zip_plus_4_code: 'input[name="text-5"]',
        country: 'input[name="text-6"]'
}
```

--------------------------------

TITLE: GET /keys/:key/lookups
DESCRIPTION: Reports lookup information on a key for paid lookups. Returns a CSV download of lookups performed and associated information.

SOURCE: https://docs.addresszen.com/docs/api/key-logs

LANGUAGE: APIDOC
CODE:
```
## GET /keys/:key/lookups

### Description
Reports lookup information on a key for paid lookups. Returns a CSV download of lookups performed and associated information.

### Method
GET

### Endpoint
/keys/:key/lookups

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key to look up.

#### Query Parameters
- **start_date** (string) - Optional - The start date for the lookup interval (YYYY-MM-DD).
- **end_date** (string) - Optional - The end date for the lookup interval (YYYY-MM-DD).

### Request Example
```
GET /keys/YOUR_API_KEY/lookups?start_date=2023-01-01&end_date=2023-01-31
```

### Response
#### Success Response (200)
- **Content-Type**: text/csv
- **Body**: CSV data containing lookup information.

#### Error Response (400)
- **Content-Type**: application/json
- **Body**: JSON object with error code and message.

### Response Example (Error)
```json
{
  "error_code": "INVALID_DATE_FORMAT",
  "message": "The provided date format is invalid."
}
```
```

--------------------------------

TITLE: Address Verification with Node.js (Axios)
DESCRIPTION: Shows how to perform address verification in Node.js using the Axios library. This example includes error handling for API requests and returns the verified address data.

SOURCE: https://docs.addresszen.com/docs/address-verification/getting-started

LANGUAGE: javascript
CODE:
```
const axios = require("axios");

const verifyAddress = async (address) => {
  try {
    const response = await axios.post(
      "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY",
      { query: address },
      {
        headers: {
          "Content-Type": "application/json",
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Verification error:", error.response?.data || error.message);
    throw error;
  }
};

// Usage
verifyAddress("123 Main St, Springfield, CO 81073").then((result) =>
  console.log(result),
);
```

--------------------------------

TITLE: Import React and AddressLookup Modules
DESCRIPTION: Imports essential React hooks (`useEffect`, `useState`, `useRef`) and the `AddressLookup` component from the installed package. These are necessary for building the interactive address lookup feature.

SOURCE: https://docs.addresszen.com/docs/address-lookup/react

LANGUAGE: javascript
CODE:
```
import "./styles.css";
import React, { useEffect, useState, useRef } from "react";
import { AddressLookup } from "@addresszen/address-lookup";
```

--------------------------------

TITLE: Building Number Examples
DESCRIPTION: Demonstrates various formats for building numbers, including simple numeric, alphanumeric concatenations (e.g., '2A'), dual numbers separated by '/', sequences using underscores '_', and ranges using dashes '-'.

SOURCE: https://docs.addresszen.com/docs/data/ecad

LANGUAGE: text
CODE:
```
22
```

LANGUAGE: text
CODE:
```
63/64
```

LANGUAGE: text
CODE:
```
1_5
```

LANGUAGE: text
CODE:
```
63-66
```

--------------------------------

TITLE: GET /keys/:key/usage
DESCRIPTION: Reports the number of lookups consumed on a key for a range of days. Supports filtering by tags and has default date ranges if not specified.

SOURCE: https://docs.addresszen.com/docs/api/key-usage

LANGUAGE: APIDOC
CODE:
```
## GET /keys/:key/usage

### Description
Reports the number of lookups consumed on a key for a range of days. A maximum interval of 90 days can be provided. If no start or end date is provided, the last 21 days will be used. You can append `tags` to scope the number of lookups to those with matching tag values.

### Method
GET

### Endpoint
/keys/:key/usage

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key to retrieve usage stats for.

#### Query Parameters
- **start** (string) - Optional - The start date for the analysis (YYYY-MM-DD). Defaults to 21 days prior to the current time.
- **end** (string) - Optional - The end date for the analysis (YYYY-MM-DD). Defaults to the current time.
- **tags** (string) - Optional - Comma-separated list of tags to filter lookups. E.g., `tags=foo,bar`.

### Request Example
```
GET /keys/your_api_key/usage?start=2023-01-01&end=2023-01-31&tags=premium,enterprise
```

### Response
#### Success Response (200)
- **usage_data** (object) - An object containing usage statistics.
  - **date** (string) - The date of the usage report.
  - **lookups** (integer) - The number of lookups for that date.
  - **tags** (array of strings) - The tags associated with the lookups.

#### Response Example
```json
{
  "usage_data": [
    {
      "date": "2023-01-01",
      "lookups": 150,
      "tags": ["premium"]
    },
    {
      "date": "2023-01-02",
      "lookups": 200,
      "tags": ["premium", "enterprise"]
    }
  ]
}
```

#### Error Response (400)
- **error** (string) - Description of the bad request.

#### Error Example
```json
{
  "error": "Invalid date format provided."
}
```
```

--------------------------------

TITLE: Security - Wildcard Subdomain Allowed URLs
DESCRIPTION: The system now permits wildcard subdomains in allowed URLs for security configurations. For example, '*.domain.com' will match 'domain.com' and all its subdomains.

SOURCE: https://docs.addresszen.com/docs/changelog

LANGUAGE: configuration
CODE:
```
*.domain.com
```

--------------------------------

TITLE: Filtering - Combine Multiple Filters
DESCRIPTION: Demonstrates combining multiple filters to further narrow down the results. This example restricts results to small user organisations in the 'N' postcode area.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET /addresses?su_organisation_indicator=Y&postcode_area=n
```

--------------------------------

TITLE: GET Request for Postcode Lookup
DESCRIPTION: This snippet shows the basic GET request format to retrieve addresses associated with a given UK postcode. The API is case and space insensitive for postcodes. It returns a JSON list of addresses.

SOURCE: https://docs.addresszen.com/docs/api/postcodes

LANGUAGE: HTTP
CODE:
```
GET 
/postcodes/:postcode
```

--------------------------------

TITLE: Browser Integration (UMD) with AddressLookup Setup
DESCRIPTION: This snippet shows how to include the Address Lookup UMD script from a CDN and initialize it with an API key and specific output field mappings. It targets IE11 and upwards, providing a polyfilled and minified package for easy integration.

SOURCE: https://docs.addresszen.com/docs/address-lookup/script

LANGUAGE: html
CODE:
```
<script src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup"></script>
<script>
  AddressZen.AddressLookup.setup({
    apiKey: "zenkey",
    outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      city: "#city",
      state: "#state",
      zip_plus_4_code: "#zipcode",
    },
  });
</script>
```

--------------------------------

TITLE: Find Place Suggestions via GET /places
DESCRIPTION: Retrieves a list of suggested geographical places based on a query. This is the first step in extracting full place information. The response includes place name, descriptive name, and an ID.

SOURCE: https://docs.addresszen.com/docs/api/find-place

LANGUAGE: HTTP
CODE:
```
GET 
/places
```

--------------------------------

TITLE: GET Request to Retrieve Address by UDPRN
DESCRIPTION: This snippet shows the HTTP GET request format to retrieve address details using a UDPRN. The UDPRN is a path parameter that uniquely identifies a delivery point.

SOURCE: https://docs.addresszen.com/docs/api/udprn

LANGUAGE: HTTP
CODE:
```
GET 
/udprn/:udprn
```

--------------------------------

TITLE: Address Validation Setup with AddressLookup
DESCRIPTION: Sets up the AddressLookup component with an API key and configures output fields. It also attaches a submit event listener to the form to prevent submission until a valid address is populated via the onAddressPopulated callback.

SOURCE: https://docs.addresszen.com/docs/address-lookup/validate-before-submitting

LANGUAGE: javascript
CODE:
```
let shouldFormSubmit = false;

AddressZen.AddressLookup.setup({
	apiKey: "ak_test",
	outputFields: {
		line_1: "#line_1",
		line_2: "#line_2",
		city: "#city",
		state: "#state",
		zip_plus_4_code: "#zipcode",
	},
	onLoaded: function () {
		const form = this.input.closest("form");
		if (form === null) return;
		form.addEventListener("submit", (e) => {
			if (shouldFormSubmit === false) {
				e.preventDefault();
				// Add custom action - E.g. show a warning
				alert("Please select an address before proceeding");
				return false;
			}
		});
	},
	onAddressPopulated: function () {
		shouldFormSubmit = true;
	},
});
```

--------------------------------

TITLE: Add Optional AddressZen Output Fields
DESCRIPTION: This example demonstrates how to include additional output fields for AddressZen's AddressLookup, such as building name, to enhance address capture in Elementor forms.

SOURCE: https://docs.addresszen.com/docs/integrations/elementor

LANGUAGE: javascript
CODE:
```
outputFields: {
  building_or_firm_name: '#form-field-building_name',
  line_1: '#form-field-line_1',
  line_2: '#form-field-line_2',
  line_3: '#form-field-line_3',
  post_town: '#form-field-post_town',
  postcode: '#form-field-postcode'
}
```

--------------------------------

TITLE: GET /keys/:key
DESCRIPTION: Fetches public information about a given API Key, including its availability status and the contexts it supports. This is useful for determining if a key is active and understanding its potential use cases based on user location.

SOURCE: https://docs.addresszen.com/docs/api/key-availability

LANGUAGE: APIDOC
CODE:
```
## GET /keys/:key

### Description
Returns public information on your API Key, including its availability status and supported contexts. This endpoint can be used to determine if the key is currently usable, identify available contexts, and understand the likely context of a user based on their location.

### Method
GET

### Endpoint
/keys/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - Your API Key (starts with `ak_`) or Sub-licensed Key (starts with `sl_`).

### Responses
#### Success Response (200)
- **available** (boolean) - Indicates if the API Key is currently usable.
- **contexts** (array of strings) - A list of contexts supported by the API Key.
- **likely_context** (string) - The most probable context for a user associated with this key, often determined by location.

#### Error Response (404)
- **error** (string) - Description of the error, e.g., "Invalid Key".
```

--------------------------------

TITLE: Address - String Type
DESCRIPTION: The house number or address uniquely identifying the location on a street. Can be an empty string if not present. Example: '16'.

SOURCE: https://docs.addresszen.com/docs/data/gnaf

LANGUAGE: string
CODE:
```
"address"
```

--------------------------------

TITLE: Address Line One - String Type
DESCRIPTION: Represents the first line of an address. It can be an empty string if not present. Example: '30 Hampton Cct'.

SOURCE: https://docs.addresszen.com/docs/data/gnaf

LANGUAGE: string
CODE:
```
"line_1"
```

--------------------------------

TITLE: GET /postcodes/:postcode
DESCRIPTION: Retrieves postcode information. If an exact match isn't found, it suggests up to 5 similar postcodes, checking for common character mix-ups. For all responses, it includes 'total', 'limit', and 'page' attributes.

SOURCE: https://docs.addresszen.com/docs/changelog

LANGUAGE: APIDOC
CODE:
```
## GET /postcodes/:postcode

### Description
Retrieves postcode information. If an exact match isn't found, it suggests up to 5 similar postcodes, checking for common character mix-ups. For all responses, it includes 'total', 'limit', and 'page' attributes.

### Method
GET

### Endpoint
/postcodes/:postcode

### Parameters
#### Path Parameters
- **postcode** (string) - Required - The postcode to search for.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return.
- **page** (integer) - Optional - The page number for paginated results.

### Response
#### Success Response (200)
- **suggestions** (array) - A list of suggested postcodes if no exact match is found.
- **total** (integer) - The total number of results available.
- **limit** (integer) - The maximum number of results per page.
- **page** (integer) - The current page number.
- **postcodes** (array) - A list of postcode objects matching the query.
```

--------------------------------

TITLE: Address Lookup Setup in Gravity Forms (JavaScript)
DESCRIPTION: This snippet sets up the Address Lookup functionality provided by AddressZen within a Gravity Forms form. It requires an API key and maps Address Lookup output fields to specific input fields in the Gravity Form. Ensure to replace 'YOUR_API_KEY' and adjust the input field selectors based on your form's field IDs.

SOURCE: https://docs.addresszen.com/docs/integrations/gravity-forms

LANGUAGE: html
CODE:
```
<script src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup"></script>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    AddressZen.AddressLookup.setup({
      apiKey: "YOUR_API_KEY",
      outputFields: {
        line_1: 'input[name="input_1"]',
        line_2: 'input[name="input_2"]',
        city: 'input[name="input_4"]',
        state: 'input[name="input_5"]',
        zip_plus_4_code: 'input[name="input_6"]'
      }
    });
  });
</script>
```

--------------------------------

TITLE: Initialize Address Lookup Plugin in Unbounce
DESCRIPTION: This script initializes the Address Lookup plugin for AddressZen. It requires an API key and maps output fields to specific HTML element IDs within your Unbounce form. Ensure your API key starts with 'ak_'.

SOURCE: https://docs.addresszen.com/docs/integrations/unbounce

LANGUAGE: javascript
CODE:
```
<script src="https://cdn.jsdelivr.net/npm/@addresszen/address-lookup">
</script>

<script>
  document.addEventListener("DOMContentLoaded", function() {
    AddressZen.AddressLookup.setup({
      apiKey: "YOUR API KEY",
      outputFields: {
        line_1: "#street",
        line_2: "#street",
        city: "#city",
        state: "#state",
        zip_plus_4_code: "#zip_code"
      }
    });
  });
</script>
```

--------------------------------

TITLE: Create Configuration API
DESCRIPTION: Creates a new configuration object.

SOURCE: https://context7_llms

LANGUAGE: APIDOC
CODE:
```
## POST /docs/api/create-config.md

### Description
Creates a new configuration.

### Method
POST

### Endpoint
/docs/api/create-config.md

### Parameters
#### Request Body
- **config_name** (string) - Required - The name of the configuration.
- **config_details** (object) - Required - The details of the configuration.

### Request Example
{
  "config_name": "default_config",
  "config_details": {
    "setting1": "value1",
    "setting2": "value2"
  }
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **config_name** (string) - The name of the created configuration.

#### Response Example
{
  "message": "Configuration created successfully.",
  "config_name": "default_config"
}
```

--------------------------------

TITLE: Address Lookup: onMounted Callback
DESCRIPTION: Triggered when the Address Lookup controller attaches to the DOM. This is typically used for DOM manipulation or setup after the component is ready.

SOURCE: https://docs.addresszen.com/docs/address-lookup/callbacks

LANGUAGE: javascript
CODE:
```
instance.onMounted = function() {
  console.log('Address Lookup mounted to DOM.');
};
```

--------------------------------

TITLE: Retrieve API Key Information (GET /keys/:key)
DESCRIPTION: This endpoint allows you to retrieve public information about your API key. It helps determine key usability, available contexts, and the likely context of a user based on their location. Both API Keys (ak_) and Sub-licensed Keys (sl_) are supported.

SOURCE: https://docs.addresszen.com/docs/api/key-availability

LANGUAGE: http
CODE:
```
GET 
/keys/:key
```

--------------------------------

TITLE: Salesforce Custom Object Field Mapping
DESCRIPTION: Example JSON configuration for mapping AddressZen address fields to Salesforce Custom Object fields. This allows Address Lookup to populate specific fields within your custom objects.

SOURCE: https://docs.addresszen.com/docs/integrations/salesforce

LANGUAGE: json
CODE:
```
[
  {
    "line_1": "Address_Line_One__c",
    "post_town": "Town_or_City__c",
    "postcode": "Postcode__c"
  },
  {
    "line_1": "Customer_Line_1__c",
    "line_2": "Customer_Line_2__c",
    "post_town": "Customer_Post_Town__c",
    "postcode": "Customer_Postcode__c",
    "county": "Customer_UPRN__c"
  }
]
```

--------------------------------

TITLE: Eircode Format Example
DESCRIPTION: Illustrates the standard seven-character Eircode format (A65 F4E2) used in Irish postal addresses. The Eircode is a mandatory element and is typically placed on its own line.

SOURCE: https://docs.addresszen.com/docs/data/ecad

LANGUAGE: text
CODE:
```
A65 R2AF
```

--------------------------------

TITLE: Custom Address Fields for Wizards (Example)
DESCRIPTION: Illustrates the configuration for custom address fields specifically for Zoho CRM wizards. It shows how to append 'input' to the identified element IDs within the 'crm-create-fields' parent element for accurate mapping.

SOURCE: https://docs.addresszen.com/docs/integrations/zoho-crm

LANGUAGE: json
CODE:
```
[
  {
    "line_1": "#Crm_Leads_LEADCF2 input",
    "post_town": "#Crm_Leads_CITY input",
    "postcode": "#Crm_Leads_ZIP input",
    "county": "#Crm_Leads_LEADCF3 input"
  }
]
```

--------------------------------

TITLE: GET /places - Find Place
DESCRIPTION: Query for geographical places across countries. Each query returns a list of place suggestions, including place name, descriptive name, and ID. Ideal for identifying places and their geolocation.

SOURCE: https://docs.addresszen.com/docs/api/find-place

LANGUAGE: APIDOC
CODE:
```
## GET /places

### 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.

This 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.

### Method
GET

### Endpoint
/places

### Parameters
#### Query Parameters
* **query** (string) - Required - The search query for places.

### Request Example
```
GET /places?query=New%20York
```

### Response
#### Success Response (200)
- **places** (array) - A list of place suggestions.
  - **name** (string) - The name of the place.
  - **description** (string) - A descriptive name for the place.
  - **id** (string) - The unique identifier for the place.

#### Response Example
```json
{
  "places": [
    {
      "name": "New York City",
      "description": "New York, NY, USA",
      "id": "ChIJp8Mp6fYEaQARufjO2_yP6Lw"
    }
  ]
}
```

#### Error Response (400)
- **error** (string) - A message describing the bad request.

#### Response Headers
- **X-RateLimit-Limit** (integer) - The maximum number of requests that can be made in 5 minutes.
- **X-RateLimit-Remaining** (integer) - The remaining requests within the current rate limit window.
- **X-RateLimit-Reset** (integer) - The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.
```

--------------------------------

TITLE: Custom Form Fields for Billing Address (JavaScript/HTML)
DESCRIPTION: This snippet demonstrates the structure for defining custom input fields for a billing address form. It includes common address components like street lines, city, state, and zip code, using specific input names compatible with AddressZen's API.

SOURCE: https://docs.addresszen.com/docs/integrations/magento

LANGUAGE: javascript
CODE:
```
[
  {
    'line_1': 'input[name="billing_street0"]',
    'line_2': 'input[name="billing_street1"]',
    'city': 'input[name="billing_city"]',
    'state': 'input[name="billing_state"]',
    'zip_plus_4_code': 'input[name="billing_zipcode"]'
  }
]
```

--------------------------------

TITLE: GET /autocomplete/addresses
DESCRIPTION: Retrieves address suggestions based on a provided query. Supports various filters and bias options for refining search results. Rate limiting and cost details are also provided.

SOURCE: https://docs.addresszen.com/docs/api/find-address

LANGUAGE: APIDOC
CODE:
```
## GET /autocomplete/addresses

### Description
This endpoint provides address suggestions in order of relevance based on a provided query. It is designed to aid real-time address autofill implementations.

### Method
GET

### Endpoint
/autocomplete/addresses

### Query Parameters
- **query** (string) - Required - The search query for address suggestions.
- **postcode** (string) - Optional - Filters results by postcode. Supports multiple terms separated by commas.
- **postcode_outward** (string) - Optional - Filters results by postcode outward. Supports multiple terms separated by commas.
- **su_organisation_indicator** (string) - Optional - Filters results by organisation indicator. Supports multiple terms separated by commas.
- **postcode_area** (string) - Optional - Filters results by postcode area. Supports multiple terms separated by commas.
- **bias_postcode_area** (string) - Optional - Biases results towards specified postcode areas. Supports multiple terms separated by commas.

### Request Example
```json
{
  "query": "10 downing street",
  "postcode": "sw1a2aa",
  "bias_postcode_area": "SW,SE"
}
```

### Response
#### Success Response (200)
- **suggestions** (array) - A list of address suggestions. The format is subject to change and should be used as-is.

**Response Headers**
- **X-RateLimit-Limit** (integer) - The maximum number of requests that can be made in 5 minutes.
- **X-RateLimit-Remaining** (integer) - The remaining requests within the current rate limit window.
- **X-RateLimit-Reset** (integer) - The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.

#### Response Example
```json
{
  "suggestions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "address_line_1": "10 Downing Street",
      "address_line_2": "",
      "city": "London",
      "postcode": "SW1A 2AA"
    }
  ]
}
```

#### Error Response (400)
- **error** (string) - Description of the bad request.

#### Error Example
```json
{
  "error": "Invalid query parameter provided."
}
```
```

--------------------------------

TITLE: Instantiate Address Lookup
DESCRIPTION: Sets up the Address Lookup service by instantiating it with your API key and specifying the output fields to be mapped to your HTML elements.

SOURCE: https://docs.addresszen.com/docs/address-lookup/npm

LANGUAGE: javascript
CODE:
```
import { AddressLookup } from "@addresszen/address-lookup";

const controller = AddressLookup.setup({
  apiKey: "zenkey",
  outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      city: "#city",
      state: "#state",
      zip_plus_4_code: "#zipcode",
  },
});
```

--------------------------------

TITLE: Biasing - Multiple Postcode Outward Codes
DESCRIPTION: Allows scoping multiple terms for the same bias attribute, separated by commas. This example boosts results for outward codes E1, E2, and E3.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET /addresses?bias_postcode_outward=e1,e2,e3
```

--------------------------------

TITLE: GET /addresses
DESCRIPTION: Extracts a list of complete addresses matching the query, ordered by relevance. Supports optional limit and page parameters. If a postcode is provided, it returns all addresses for that postcode, ignoring limit and page.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: APIDOC
CODE:
```
## GET /addresses

### Description
Extracts a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

### Method
GET

### Endpoint
/addresses

### Query Parameters
- **limit** (integer) - Optional - The maximum number of addresses to return.
- **page** (integer) - Optional - The page number for pagination.
- **postcode** (string) - Optional - Filters addresses by a specific postcode.
- **q** (string) - Optional - The search query string for addresses.
- **lat** (number) - Optional - Latitude for reverse geocoding.
- **lon** (number) - Optional - Longitude for reverse geocoding.
- **postcode_outward** (string) - Optional - Filters addresses by postcode outward codes (comma-separated).
- **postcode_area** (string) - Optional - Filters addresses by postcode area (comma-separated).
- **su_organisation_indicator** (string) - Optional - Filters by SU Organisation indicator.
- **bias_postcode_area** (string) - Optional - Biases results by postcode area (comma-separated).
- **bias_postcode_outward** (string) - Optional - Biases results by postcode outward codes (comma-separated).
- **uprn** (integer) - Optional - Filters addresses by UPRN.

### Request Example
```json
{
  "request": "GET /addresses?postcode=SW1A 2AA&limit=5"
}
```

### Response
#### Success Response (200)
- **addresses** (array) - A list of address objects.
- **total_results** (integer) - The total number of matching addresses.

#### Response Example
```json
{
  "addresses": [
    {
      "full_address": "10 Downing Street, London, SW1A 2AA"
    }
  ],
  "total_results": 1
}
```

### Error Handling
- **4020** - No lookups remaining.
- **4021** - Daily or individual lookup limit breached.
- **400** - Bad Request
- **404** - Postcode Not Found
```

--------------------------------

TITLE: List Configurations API
DESCRIPTION: Lists configurations associated with an API key.

SOURCE: https://context7_llms

LANGUAGE: APIDOC
CODE:
```
## GET /docs/api/list-configs.md

### Description
Lists all configurations linked to the current API key.

### Method
GET

### Endpoint
/docs/api/list-configs.md

### Response
#### Success Response (200)
- **configurations** (array) - List of configuration names.

#### Response Example
{
  "configurations": ["default_config", "secondary_config"]
}
```

--------------------------------

TITLE: Create Licensee API
DESCRIPTION: Creates a licensee for a specified API Key.

SOURCE: https://context7_llms

LANGUAGE: APIDOC
CODE:
```
## POST /docs/api/create-licensee.md

### Description
Creates a licensee associated with an API Key.

### Method
POST

### Endpoint
/docs/api/create-licensee.md

### Parameters
#### Request Body
- **api_key** (string) - Required - The API Key to associate the licensee with.
- **licensee_details** (object) - Required - Details about the licensee.

### Request Example
{
  "api_key": "YOUR_API_KEY",
  "licensee_details": {
    "name": "Example Corp",
    "email": "contact@example.com"
  }
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **licensee_id** (string) - The ID of the newly created licensee.

#### Response Example
{
  "message": "Licensee created successfully.",
  "licensee_id": "LIC12345"
}
```

--------------------------------

TITLE: ShopWired Integration Basic Configuration
DESCRIPTION: Provides the essential configuration snippet for the AddressZen ShopWired integration, primarily setting the API key.

SOURCE: https://docs.addresszen.com/docs/integrations/shopwired

LANGUAGE: javascript
CODE:
```
<script>
  window.idpcConfig = {
    apiKey: "Your API Key goes here"
  };
</script>
```

--------------------------------

TITLE: Filtering - Restrict Address Search by Postcode
DESCRIPTION: Narrows down search results by applying filters to address attributes. For example, restricting results to a specific postcode by appending the 'postcode' filter.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET /addresses?postcode=SW1A 2AA
```

--------------------------------

TITLE: Filtering - Multiple Postcode Outward Codes
DESCRIPTION: Allows scoping results using multiple terms for the same filter, separated by commas. This example restricts results to outward codes E1, E2, and E3.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET /addresses?postcode_outward=e1,e2,e3
```

--------------------------------

TITLE: GET /umprn/:umprn
DESCRIPTION: Retrieves a multiple occupancy address identified by its UMPRN (Unique Property Reference Number). UMPRNs are unique numeric codes for multiple residence households.

SOURCE: https://docs.addresszen.com/docs/api/umprn

LANGUAGE: APIDOC
CODE:
```
## GET /umprn/:umprn

### Description
Retrieves a multiple occupancy address identified via its UMPRN (Unique Property Reference Number).

UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.

### Method
GET

### Endpoint
/umprn/:umprn

### Parameters
#### Path Parameters
- **umprn** (integer) - Required - The Unique Property Reference Number to look up.

### Request Example
(No request body for GET requests)

### Responses
#### Success Response (200)
- **address** (string) - The multiple occupancy address associated with the UMPRN.

#### Response Example
```json
{
  "address": "123 Multiple Occupancy Lane, Any Town, AT1 2BC"
}
```

#### Error Responses
- **404**: UMPRN not found. (Example response: "UMPRN not found")
- **4020**: No lookups remaining. (Example response: "no lookups remaining")
- **4021**: Daily or individual lookup limit breached. (Example response: "daily (or individual) lookup limit breached")
```

--------------------------------

TITLE: Get Key Usage Statistics
DESCRIPTION: Retrieves the number of lookups consumed for a given API key within a specified date range. Supports a maximum interval of 90 days. Defaults to the last 21 days if no dates are provided. Can be filtered by tags.

SOURCE: https://docs.addresszen.com/docs/api/key-usage

LANGUAGE: HTTP
CODE:
```
GET /keys/:key/usage
```

--------------------------------

TITLE: GET /addresses - Extract Address List
DESCRIPTION: Retrieves a list of complete addresses matching a query, ordered by relevance. Supports optional limit and page parameters. If a valid postcode is provided, the entire address list for that postcode is returned, ignoring limit and page.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET 
/addresses
```

--------------------------------

TITLE: GET /udprn/:udprn
DESCRIPTION: Retrieves address details using the Unique Delivery Point Reference Number (UDPRN). UDPRNs are eight-digit unique numeric codes identifying UK premises in the Postcode Address File.

SOURCE: https://docs.addresszen.com/docs/api/udprn

LANGUAGE: APIDOC
CODE:
```
## GET /udprn/:udprn

### Description
Retrieves an address as identified by its Unique Delivery Point Reference Number (UDPRN).

### Method
GET

### Endpoint
/udprn/:udprn

### Parameters
#### Path Parameters
- **udprn** (string) - Required - The Unique Delivery Point Reference Number for the address.

### Request Example
```
GET /udprn/25962203
```

### Response
#### Success Response (200)
- **address** (object) - The address details.
- **udprn** (string) - The UDPRN of the address.

#### Response Example
```json
{
  "address": {
    "building_name": "Example House",
    "sub_building_name": "Flat 1",
    "department_name": "Sales",
    "organisation_name": "Example Corp",
    "po_box_number": "PO Box 123",
    "address_line1": "1 Example Street",
    "address_line2": "Example Road",
    "address_line3": "Example Village",
    "town_city": "Example Town",
    "county": "Exampleshire",
    "postcode": "EX1 2MP"
  },
  "udprn": "25962203"
}
```

#### Error Response (404)
- **error** (string) - Description of the error, e.g., "UDPRN not found".

#### Error Response Example
```json
{
  "error": "UDPRN not found"
}
```
```

--------------------------------

TITLE: Biasing - Boost Addresses by Postcode Area
DESCRIPTION: Boosts certain address results based on address attributes. This example boosts addresses in postcode areas 'SW' and 'SE'. Unmatched addresses may still appear but will rank lower.

SOURCE: https://docs.addresszen.com/docs/api/addresses

LANGUAGE: HTTP
CODE:
```
GET /addresses?bias_postcode_area=SW,SE
```

--------------------------------

TITLE: Versioning
DESCRIPTION: Understand how the AddressZen API is versioned and how to utilize different versions for compatibility.

SOURCE: https://docs.addresszen.com/docs/api/api-reference

LANGUAGE: APIDOC
CODE:
```
## Versioning

This API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version.

Please note that the following changes are backwards-compatible:

* Adding new properties to existing API responses
* Adding new API endpoints
* Adding new optional request parameters to existing API endpoints
* Changing the order of properties in existing API responses
* Changing the autocomplete address suggestion format
```