### Install and Initialize Postcode Lookup Plugin (JavaScript)

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/formassembly

Loads the Postcode Lookup library and sets up the plugin with configuration. Requires an API key and mapping of output fields to HTML elements. The setup is triggered on DOMContentLoaded.

```javascript
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled"></script>

<script>
	document.addEventListener("DOMContentLoaded", function () {
		IdealPostcodes.PostcodeLookup.setup({
			apiKey: "YOUR_API_KEY",
			context: "#idpc",
			buttonClass: "postcode-search-button",
			inputClass: "idpc-input",
			selectClass: "idpc-select",
			outputFields: {
				line_1: 'input[name="tfa_2"]',
				line_2: 'input[name="tfa_3"]',
				line_3: 'input[name="tfa_4"]',
				post_town: 'input[name="tfa_5"]',
				postcode: 'input[name="tfa_6"]',
			},
		});
	});
</script>
```

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

### Initialize Ideal Postcodes Lookup Script

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/forminator

This script initializes the Ideal Postcodes lookup service. It includes the bundled JavaScript library and sets up the lookup with an API key, context element, and output field mappings. The output fields can be customized based on the desired address data.

```javascript
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled"></script>

<script>
	IdealPostcodes.PostcodeLookup.setup({
		apiKey: "ak_test",
		context: "#idpc",
		outputFields: {
			line_1: 'input[name="text-1"]',
			line_2: 'input[name="text-2"]',
			line_3: 'input[name="text-3"]',
			post_town: 'input[name="text-4"]',
			postcode: 'input[name="text-5"]',
		},
	});
</script>
```

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

### Initialize Ideal Postcodes Address Finder in WordPress

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/forminator

This snippet shows how to load the Address Finder script and initialize it with a test API key. It maps address components to specific input fields within a Forminator form. Ensure your input field names match the 'outputFields' configuration.

```html
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled"></script>

<script>
	document.addEventListener("DOMContentLoaded", function () {
		IdealPostcodes.AddressFinder.setup({
			apiKey: "ak_test",
			outputFields: {
				line_1: 'input[name="text-1"]',
				line_2: 'input[name="text-2"]',
				line_3: 'input[name="text-3"]',
				post_town: 'input[name="text-4"]',
				postcode: 'input[name="text-5"]',
			},
		});
	});
</script>
```

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

### Address Finder Setup Configuration

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/configure

Details the minimum configuration required for the Address Finder's `setup` method, including API Key and Address Targets.

```APIDOC
## Configure Address Finder

Address Finder exports a [`setup`](https://address-finder.ideal-postcodes.co.uk/modules/Controller.html#Setup) method to apply address verification to a form. The `setup` method requires the following configuration at minimum:

### API Key

- **apiKey** (string) - Required - API Key from your Ideal Postcodes account. Typically begins `ak_`

### Address Targets

- **outputFields** (object) - Required - Specify where to send address data given a selected address. `outputFields` is an object which maps an address attribute to an input field. The input field can be identified by CSS selector or DOM element reference.

**Example `outputFields` configuration:**
```json
{
  "line_1": "#line_1",
  "line_2": "#line_2",
  "line_3": "input[name='line_3']",
  "post_town": "#post_town",
  "postcode": "#postcode"
}
```

**Note:**
- Assigning up to 3 address lines, post town and postcode fields is sufficient for identifying a UK premise.
- More address attributes can be extracted by including more properties in the `outputFields` object, matching the Address response object properties (e.g., `thoroughfare`). A full list can be found at [@ideal-postcodes/api-typings](https://api-typings.ideal-postcodes.co.uk/interfaces/address.html).
- Dynamic assignment can be achieved using the [`onAddressRetrieved`](https://address-finder.ideal-postcodes.co.uk/interfaces/Controller.ControllerOptions.html#onAddressRetrieved) callback.
- Fields assigned with a query selector are evaluated lazily when an address attribute needs to be piped to a field.
```

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

### Bundler Integration (npm Install and JavaScript Use)

Source: https://docs.ideal-postcodes.co.uk/docs/postcode-lookup/script

This code demonstrates how to install the postcode lookup package using npm and then import and use the PostcodeLookup class within a project managed by a bundler like Webpack or Parcel. It includes setup with an API key and output field mappings.

```bash
npm install --save @ideal-postcodes/postcode-lookup-bundled
```

```javascript
import { PostcodeLookup } from "@ideal-postcodes/postcode-lookup-bundled";

const controller = PostcodeLookup.setup({
  apiKey: "ak_test",
  context: "#context",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});
```

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

### GET /keys/:key - Support for Sublicensee Keys

Source: https://docs.ideal-postcodes.co.uk/docs/changelog

The `/keys/:key` API now supports sublicensee keys that start with the prefix `sl_`.

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

### Description
Retrieves details for a given API key, now including support for sublicensee keys prefixed with `sl_`.

### Method
GET

### Endpoint
`/keys/:key`

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

### Response
#### Success Response (200)
- **key** (string) - The API key.
- **status** (string) - The status of the key.
- **access_level** (string) - The access level granted by the key.
- **datasets** (array) - An array of datasets the key has access to (e.g., "PAF", "Multiple Residence").

#### Response Example
```json
{
  "key": "sl_abcdef12345",
  "status": "active",
  "access_level": "standard",
  "datasets": ["PAF", "Multiple Residence"]
}
```
```

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

### Install Address Finder using npm

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/npm

Installs the `@ideal-postcodes/address-finder` package into your project using npm. This is the primary method for integrating the Address Finder library.

```bash
npm install @ideal-postcodes/address-finder
```

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

### Start of Validity Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

The time at which a version of a verblijfsobject becomes valid in reality, based on the source document's effective date.

```string
2023-01-01T00:00:00Z
```

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

### Example Postcode Lookup URL with Sublicensing Key

Source: https://docs.ideal-postcodes.co.uk/docs/guides/sublicensing

This example shows how a standard postcode lookup URL changes when using a Sublicensing Key instead of a standard API key. The 'api_key' parameter is replaced with a licensee-specific key.

```HTTP
/v1/autocomplete/addresses?api_key=sk_i98n29d8dj3K
```

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

### Email Validation API Request

Source: https://docs.ideal-postcodes.co.uk/docs/guides/email-validation

An example GET request to the Ideal Postcodes Emails API for validating an email address. Requires your API key and the email address to validate as a query parameter.

```http
https://api.ideal-postcodes.co.uk/v1/emails?api_key=YOUR_KEY&query=support@ideal-postcodes.co.uk
```

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

### Address Line One Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

Shows an example of the first line of an address. This field can be an empty string if no data is available.

```string
Herengracht 255
```

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

### AddressBase Core Field Examples

Source: https://docs.ideal-postcodes.co.uk/docs/data/addressbase-core

Illustrates the data types and example values for key fields in the AddressBase Core schema, such as unique identifiers and address components.

```text
id: "paf_8387729"
dataset: "ab"
line_1: "Prime Minister &amp; First Lord of Treasury"
line_2: "10 Downing Street"
premise: "10"
uprn: "some_uprn_string"
udprn: 12345678
parent_uprn: "parent_uprn_string"
usrn: 987654
toid: "osgb1234567890123456"
classification_code: "some_code"
eastings: 500000
northings: 100000
latitude: 51.5074
longitude: -0.1278
single_address_line: "10 Downing Street, London"
street_name: "Downing Street"
```

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

### Install Postcode Lookup via npm

Source: https://docs.ideal-postcodes.co.uk/docs/postcode-lookup/npm

This command installs the `@ideal-postcodes/postcode-lookup` package using npm, making its functionality available in your project for postcode lookups and address finding.

```bash
npm install @ideal-postcodes/postcode-lookup
```

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

### Install OpenAPI Package with npm

Source: https://docs.ideal-postcodes.co.uk/docs/libraries/open-api

Installs the Ideal Postcodes OpenAPI package using npm. This package provides the OpenAPI v3 specification for the Ideal Postcodes API, enabling developers to consume the API descriptions and export API typings.

```bash
npm install @ideal-postcodes/openapi
```

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

### Property Status Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

An example of the status of a verblijfsobject within the registry.

```string
Hoofdfunctie
```

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

### Bundler Integration (npm install)

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/script

Installs the address-finder-bundled package via npm for use with bundlers like parcel, webpack, or rollup. This allows for local management of the dependency.

```bash
npm install --save @ideal-postcodes/address-finder-bundled
```

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

### Install Address Finder using npm

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/react

Installs the Address Finder package as a project dependency using npm. This is the first step to using the component in your React application.

```bash
npm install --save @ideal-postcodes/address-finder
```

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

### Clone Repository (Manual Installation)

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/magento

Manually installs the extension by cloning the Git repository. This method requires placing the extension files into the specified Magento directory.

```bash
$ git clone --depth=1 https://github.com/idealpostcodes/magento.git
```

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

### Building Name Example - IE Address Format

Source: https://docs.ideal-postcodes.co.uk/docs/data/ecad

Shows an example of the 'building_name' field in the IE Address (ECAD) format, representing the name of a building.

```text
Rose Cottage
```

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

### Implementing Place Autocomplete

Source: https://docs.ideal-postcodes.co.uk/docs/guides/places

Explains the two-step process for retrieving full place information: first, get suggestions via the /places endpoint, and second, retrieve the complete place details using the ID provided in the suggestion.

```APIDOC
## GET /places

### Description
Retrieves a list of place suggestions based on a query.

### Method
GET

### Endpoint
/places

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

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

#### Response Example
```json
{
  "suggestions": [
    {
      "name": "Paris",
      "description": "Paris, France",
      "id": "country:fr:paris"
    },
    {
      "name": "Paris, Texas",
      "description": "Paris, Texas, USA",
      "id": "us_state:tx:paris"
    }
  ]
}
```
```

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

### Service Status API Response Example

Source: https://docs.ideal-postcodes.co.uk/docs/guides/status-api

This snippet provides an example of the JSON response from the Service Status API. It includes the status and a message for each tracked service, indicating whether they are up or down.

```json
{
	"Ideal Postcodes Website": {
		"status": 1,
		"message": "Up"
	},
	"Ideal Postcodes API": {
		"status": 1,
		"message": "Up"
	},
	"Postcodes.io API": {
		"status": 1,
		"message": "Up"
	}
}
```

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

### Identification of Occurrence Example (String)

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

An example of the identifier for an instance of a verblijfsobject's history, which can be an empty string if not available.

```string

```

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

### Final Magento Installation Steps

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/magento

Executes the necessary Magento commands to enable and configure the Ideal Postcodes extension after manual or Composer installation.

```bash
magento module:enable Idealpostcodes_Ukaddresssearch
magento setup:upgrade
magento setup:di:compile
magento setup:static-content:deploy -f
```

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

### Postcode Lookup via npm Package

Source: https://context7_llms

Install and use the Postcode Lookup package from npm (@ideal-postcodes/postcode-lookup). This allows for seamless integration into modern JavaScript build processes.

```bash
npm install @ideal-postcodes/postcode-lookup

```

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

### API: Access Available Datasets via GET /keys/:key/details

Source: https://docs.ideal-postcodes.co.uk/docs/changelog

Retrieves details about available datasets associated with an API key by making a GET request to the /keys/:key/details endpoint.

```http
GET /keys/:key/details

```

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

### Available Datasets API

Source: https://docs.ideal-postcodes.co.uk/docs/changelog

Information about available datasets is now accessible through the `GET /keys/:key/details` API.

```APIDOC
## October 2023

### Description
Available datasets accessible through `GET /keys/:key/details` API.

### Method
GET

### Endpoint
/keys/:key/details

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

#### Response
#### Success Response (200)
- **datasets** (array of objects) - A list of available datasets and their details.
```

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

### Province Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

Illustrates the format for a province name.

```string
North Holland
```

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

### Address Finder Output Fields Configuration Example

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/calculated-field-forms

An example of configuring the `outputFields` for the Ideal Postcodes Address Finder. This demonstrates how to map additional address components like 'uprn' to specific input fields within your form by referencing their 'name' attributes.

```javascript
outputFields: {
  line_1: 'input[name="fieldname1_1"]',
  line_2: 'input[name="fieldname2_1"]',
  line_3: 'input[name="fieldname3_1"]',
  post_town: 'input[name="fieldname4_1"]',
  postcode: 'input[name="fieldname5_1"]'
  uprn: 'input[name="fieldname6_1"]'
}
```

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

### Example API Key Format

Source: https://docs.ideal-postcodes.co.uk/docs/guides/api-key

This snippet shows the typical format of an API Key used for authenticating with the Ideal Postcodes API. API Keys are unique strings that begin with 'ak_'.

```text
ak_ksqa49sjSdAEDq9I88
```

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

### Purpose of Use Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

Illustrates the purpose for which a verblijfsobject is used.

```string
Woonfunctie
```

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

### Create Configuration API

Source: https://context7_llms

Creates a new configuration object. Requires appropriate authentication.

```APIDOC
## [POST] /config

### Description
Creates a configuration object.

### Method
POST

### Endpoint
/config

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

### Request Example
```json
{
  "name": "my_config",
  "settings": {
    "some_setting": "some_value"
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the created configuration.

#### Response Example
```json
{
  "id": "some_config_id"
}
```
```

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

### Example Custom Address Fields Configuration (JSON)

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/zoho-crm

An example JSON configuration for custom address fields in Zoho CRM. It demonstrates mapping specific Zoho CRM input IDs (like Mailing Street and Mailing Zip) to the address components required by the Ideal Postcodes service. This includes handling fields for contacts and accounts.

```json
[
	{
		"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"
	}
]
```

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

### Phone Number Validation API Request

Source: https://docs.ideal-postcodes.co.uk/docs/guides/phone-validation

Example of a GET request to the Phone Numbers API to validate a phone number. Requires an API key and the phone number with its country code as a query parameter.

```bash
https://api.ideal-postcodes.co.uk/v1/phone_numbers?api_key=YOUR_KEY&query=+4402071128019
```

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

### Get Postcode Outward Code Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/paf

Retrieves the outward code of a postcode, which is the first part of the postcode used for sorting mail to the correct local delivery area. For example, in 'ID1 1QD', 'ID1' is the outward code.

```text
postcode_outward
```

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

### List Configurations API

Source: https://context7_llms

Lists configurations associated with a key. Returns an array of configuration objects.

```APIDOC
## [GET] /configs

### Description
Lists configurations associated with a key.

### Method
GET

### Endpoint
/configs

### Response
#### Success Response (200)
- **configs** (array) - An array of configuration objects.

#### Response Example
```json
{
  "configs": [
    {
      "id": "some_config_id",
      "name": "my_config"
    }
  ]
}
```
```

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

### Instantiate Address Finder

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/npm

Sets up an instance of the Address Finder with a provided API key and configures output fields for address elements. This requires importing the `AddressFinder` class.

```javascript
import { AddressFinder } from "@ideal-postcodes/address-finder";

const controller = AddressFinder.setup({
  apiKey: "ak_test",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});
```

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

### GET /v1/phone_numbers

Source: https://docs.ideal-postcodes.co.uk/docs/guides/phone-validation

Retrieves information about a phone number, including its validity, formatted versions, and network details. The phone number should be provided as a query parameter.

```APIDOC
## GET /v1/phone_numbers

### Description
Validates a phone number and returns comprehensive details.

### Method
GET

### Endpoint
/v1/phone_numbers

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key for authentication.
- **query** (string) - Required - The phone number to validate, including the country code.

### Request Example
```
https://api.ideal-postcodes.co.uk/v1/phone_numbers?api_key=YOUR_KEY&query=+4402071128019
```

### Response
#### Success Response (200)
- **valid** (boolean) - Indicates if the phone number is valid.
- **national_format** (string) - The phone number in its national format.
- **international_format** (string) - The phone number in its international format.
- **iso_country** (string) - The 3-character ISO country code.
- **iso_country_2** (string) - The 2-character ISO country code.
- **country** (string) - The full name of the country of origin.
- **network_code** (string) - The 5-digit network provider code.
- **name** (string) - The full name of the network provider.
- **network_type** (string) - The type of the network (e.g., 'mobile' or 'landline').

#### Response Example
```json
{
  "valid": true,
  "national_format": "020 7112 8019",
  "international_format": "442071128019",
  "iso_country": "GBR",
  "iso_country_2": "GB",
  "country": "United Kingdom",
  "network_code": "48001",
  "name": "BT",
  "network_type": "landline"
}
```
```

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

### Example UDPRN API Search Request

Source: https://docs.ideal-postcodes.co.uk/docs/data/search-by-udprn

Demonstrates the API endpoint structure for searching an address by its UDPRN. Requires a UDPRN and an API key for authentication.

```HTTP
/v1/udprn/[UDPRN]?api_key=iddqd
```

```HTTP
/v1/udprn/23747771?api_key=iddqd
```

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

### Set Geolocation Bias in JavaScript

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/bias-by-geolocation

Configures the AddressFinder setup in JavaScript to prioritize addresses within a specified radius from a given longitude and latitude. This example sets the bias to '10 Downing St'.

```javascript
AddressFinder.setup({
  apiKey: "ak_test",
  queryOptions: {
      // Set geolocation bias to 10 Downing St
      bias_lonlat: "-0.1276,51.5034,100"
  },
      line_1: "#line_1",
      line_2: "#line_2",
      line_3: "#line_3",
      post_town: "#post_town",
      postcode: "#postcode"
  }
  });
```

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

### Install Address Finder Plugin with JavaScript

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/wix

This snippet includes the necessary JavaScript to initialize the Address Finder API on a form. It requires an API key and maps form input fields to address components. The script dynamically creates a lookup context and inserts it into the DOM.

```javascript
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled"></script>

<script>
	IdealPostcodes.PostcodeLookup.watch(
		{
			apiKey: "API_KEY_HERE",
			context: "div.idpc_lookup",
			outputFields: {
				line_1: 'input[name="address-line 1"]',
				line_2: 'input[name="address-line 2"]',
				line_3: 'input[name="address-line 3"]',
				post_town: 'input[name="city"]',
				postcode: 'input[name="postcode"]',
			},
		},
		{
			getScope: () => document.getElementById("PAGES_CONTAINER"),
			//The anchor below is used to locate the parent container
			//to place the postcode lookup input and button
			anchor: 'input[name="address-line 2"]',
			onAnchorFound: (options) => {
				const { scope } = options;
				const target = scope.querySelector(options.config.outputFields.line_1);
				if (target === null) return;
				if (target.parentElement?.querySelector('.idpc_lookup[idpc="true"]'))
					return;
				const postcodeField = document.createElement("div");
				postcodeField.className = "idpc_lookup field";
				options.config.context = postcodeField;
				console.log(target.parentNode.parentNode.parentNode);
				target.parentNode.parentNode.parentNode.insertBefore(
					postcodeField,
					target.parentNode.parentNode
				);
				return postcodeField;
			},
		}
	);
</script>
```

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

### Setup Multiple Address Finder Instances (JavaScript)

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/multiple

Demonstrates setting up two independent instances of Address Finder. Each instance is configured with a unique input field (`#first_line` and `#second_line`) and maps address components to specific output fields in the HTML form. This allows users to initiate an address search from either line of the address.

```javascript
AddressFinder.setup({
    apiKey: "ak_test",
    inputField: "#first_line",
    outputFields: {
        line_1: "#first_line",
        line_2: "#second_line",
        line_3: "#third_line",
        post_town: "#post_town",
        postcode: "#postcode"
    }
});
AddressFinder.setup({
    apiKey: "ak_test",
    inputField: "#second_line",
    outputFields: {
        line_1: "#first_line",
        line_2: "#second_line",
        line_3: "#third_line",
        post_town: "#post_town",
        postcode: "#postcode"
    }
});
```

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

### Add UPRN Field to Address Finder Configuration

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/forminator

Demonstrates how to extend the Address Finder configuration to include an additional output field, 'uprn', mapping it to a specific HTML input element. This allows for capturing the Unique Property Reference Number.

```javascript
outputFields: {
  line_1: 'input[name="text-1"]',
  line_2: 'input[name="text-2"]',
  line_3: 'input[name="text-3"]',
  post_town: 'input[name="text-4"]',
  postcode: 'input[name="text-5"]'
  uprn: 'input["name-text-6"]'
}
```

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

### Initial Input Field Structure

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/how-it-works

Demonstrates the HTML structure of a single text input field before the Address Finder script modifies it.

```html
<input type="text" id="line_1" name="line_1">
```

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

### Instantiate Postcode Lookup AddressFinder

Source: https://docs.ideal-postcodes.co.uk/docs/postcode-lookup/npm

This JavaScript code snippet demonstrates how to set up the `AddressFinder` from the `@ideal-postcodes/postcode-lookup` package. It requires an API key and a configuration object to map address output fields to specific HTML element IDs.

```javascript
import { AddressFinder } from "@ideal-postcodes/postcode-lookup";

const controller = AddressFinder.setup({
  apiKey: "ak_test",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});
```

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

### Initialize Ideal Postcodes Address Finder

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/hubspot-pages

Initializes the Address Finder tool with an API key and maps output fields to HTML input elements. Uses the `watch` method to ensure elements are loaded before initialization.

```javascript
IdealPostcodes.AddressFinder.watch({
	apiKey: "ak_test",
	outputFields: {
		line_1: "input[name='address_line_one']",
		line_2: "input[name='address_line_two']",
		line_3: "input[name='address_line_three']",
		post_town: "input[name='city']",
		postcode: "input[name='zip']",
	},
});
```

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

### Area Type Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

An example illustrating the nature of an openbare ruimte object.

```string
Gracht
```

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

### BAG Openbare Identifier Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

An example of the unique identifier for a BAG openbare ruimte object.

```string
GM0363000003630011
```

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

### Identification of Occurrence Example (Number)

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

An example of the identifier for an instance of a verblijfsobject's history, represented as a number.

```number
1
```

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

### Create Licensee

Source: https://docs.ideal-postcodes.co.uk/docs/api/licensees

Creates a new licensee for the specified API key.

```APIDOC
## POST /api/licensees

### Description
Create a licensee for the specified API Key.

### Method
POST

### Endpoint
/api/licensees

### Parameters
#### Query Parameters
- **api_key** (string) - Required - The API key to associate the new licensee with.

#### Request Body
- **name** (string) - Required - The name of the licensee.
- **email** (string) - Required - The email address of the licensee.

### Request Example
```json
{
  "name": "New Client Inc",
  "email": "client@newclient.com"
}
```

### Response
#### Success Response (201)
- **licensee_key** (string) - The unique identifier for the newly created licensee.
- **name** (string) - The name of the licensee.
- **email** (string) - The email address of the licensee.

#### Response Example
```json
{
  "licensee_key": "lic_def456",
  "name": "New Client Inc",
  "email": "client@newclient.com"
}
```
```

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

### Sublicensing Overview

Source: https://docs.ideal-postcodes.co.uk/docs/guides/sublicensing

Explains the concept of sublicensing keys, how they work, and their benefits for platform vendors.

```APIDOC
## Sublicensing

Sublicensing Keys allow you to license multiple organisations or individuals under the same key, all managed, controlled and billed to you under the same account. This enables you to create multiple alternate Licensees under a single Key and query the API including a Licensee key to charge a lookup to a particular Licensee. Sublicensing Keys are ideal for platform vendors providing services to multiple clients.

### How it Works

1. **Enquire**: Contact us to create a Sublicensing Key.
2. **Create Licensees**: Create a Licensee on your Sublicensing Key for each client.
3. **Query API**: Perform API requests, supplying the Licensee key for the relevant client.

### Getting a Key

Contact us to convert an existing key into a Sublicensing Key. This key will have an embedded limit on daily requests and does not require a prepaid balance.

### Creating a Licensee

Licensees can be created via the API or dashboard, requiring the Licensee's name and address. Licensees must agree to Royal Mail's terms of use.

### Querying the API with Licensees

For methods incurring a lookup cost (e.g., `/v1/postcodes/`, `/v1/addresses/`), provide a Licensee key. Each Licensee receives a random key for identification.

**Example**: Postcode lookup
```
/v1/autocomplete/addresses?api_key=sk_i98n29d8dj3K
```

### Billing

Each Licensee must procure 100 lookups ahead of any request. Usage is rounded up to the nearest 100 lookups per month per Licensee.

### Monitoring Usage

Use `/keys/:key/usage` and `/keys/:key/lookups` with a Licensee in the query string to monitor usage by individual Licensees.

### Updating Licensee Information

Use the Licensees API to update Licensee information. For organization name changes, contact us.
```

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

### Address Finder with Suggestions

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/how-it-works

Shows the HTML structure of the Address Finder UI when it displays a list of address suggestions. Each suggestion is an `<li>` element within a `<ul>`.

```html
<div class="idpc_autocomplete" id="idpcaf1" aria-haspopup="listbox">
  <input type="text" id="line_1" autocomplete="none" aria-autocomplete="list" aria-controls="idpcaf2" aria-activedescendant="" autocorrect="off" autocapitalize="off" spellcheck="false" role="combobox" aria-expanded="false" aria-owns="idpcaf2">
  <ul class="idpc_ul" id="idpcaf2" aria-label="Select your address" role="listbox" style="display: none;">
    <li aria-selected="false" tabindex="-1" aria-posinset="1" aria-setsize="10" role="option" id="idpcaf2_0">123 Space, 123 Cheltenham Road, Bristol, BS6</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="2" aria-setsize="10" role="option" id="idpcaf2_1">123 News, 123 Morrison Street, Edinburgh, EH3</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="3" aria-setsize="10" role="option" id="idpcaf2_2">Salon 123, 123 High Street, Herne Bay, CT6</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="4" aria-setsize="10" role="option" id="idpcaf2_3">123 Cleaners, 123 Shirland Road, London, W9</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="5" aria-setsize="10" role="option" id="idpcaf2_4">123 Bargates, Christchurch, BH23</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="6" aria-setsize="10" role="option" id="idpcaf2_5">123 Broadway, Cardiff, CF24</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="7" aria-setsize="10" role="option" id="idpcaf2_6">123 Greenways, Gloucester, GL4</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="8" aria-setsize="10" role="option" id="idpcaf2_7">123 Holloway, Birmingham, B31</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="9" aria-setsize="10" role="option" id="idpcaf2_8">123 Hornbeams, Harlow, CM20</li>
    <li aria-selected="false" tabindex="-1" aria-posinset="10" aria-setsize="10" role="option" id="idpcaf2_9">123 Kingsway, Hereford, HR1</li>
  </ul>
  <div style="border:0px;padding:0px;clip:rect(0px,0px,0px,0px);height:1px;margin-bottom:-1px;margin-right:-1px;overflow:hidden;position:absolute;white-space:nowrap;width:1px">
    <div id="idpcaf3" role="status" aria-live="polite" aria-atomic="true">10 addresses available</div>
    <div id="idpcaf4" role="status" aria-live="polite" aria-atomic="true"></div>
  </div>
</div>
```

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

### Postal Code Example

Source: https://docs.ideal-postcodes.co.uk/docs/data/kadaster

Provides an example of a postal code, which is determined by PostNL and associated with a specific street name and house number combination.

```string
1012 AB
```

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

### Create Licensee API

Source: https://context7_llms

Creates a licensee for the specified API Key. Requires the API Key in the request.

```APIDOC
## [POST] /licensee

### Description
Creates a licensee for the specified API Key.

### Method
POST

### Endpoint
/licensee

### Parameters
#### Request Body
- **name** (string) - Required - The name of the licensee.
- **api_key** (string) - Required - The API key to associate with the licensee.

### Request Example
```json
{
  "name": "My Licensee",
  "api_key": "some_api_key"
}
```

### Response
#### Success Response (201)
- **licensee_key** (string) - The key of the created licensee.

#### Response Example
```json
{
  "licensee_key": "some_licensee_key"
}
```
```

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

### Bundler Integration (Usage)

Source: https://docs.ideal-postcodes.co.uk/docs/address-finder/script

Demonstrates how to import and use the Address Finder within a project managed by a bundler. It imports the AddressFinder class and sets it up with an API key and output field configuration.

```javascript
import { AddressFinder } from "@ideal-postcodes/address-finder-bundled";

const controller = AddressFinder.setup({
  apiKey: "ak_test",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});
```

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

### List Licensees API

Source: https://context7_llms

Returns a list of licensees for a key.

```APIDOC
## [GET] /licensees

### Description
Returns a list of licensees for a key.

### Method
GET

### Endpoint
/licensees

### Response
#### Success Response (200)
- **licensees** (array) - An array of licensee objects.

#### Response Example
```json
{
  "licensees": [
    {
      "licensee_key": "some_licensee_key",
      "name": "My Licensee"
    }
  ]
}
```
```

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

### Integrating Address Finder with a Framework (Template)

Source: https://docs.ideal-postcodes.co.uk/docs/guides/llms

A general prompt template for integrating the Address Finder into a specified framework. Users should replace placeholders with their framework and specific requirements.

```text
"Based on the Ideal Postcodes documentation, show me how to integrate Address Finder
into a [framework] application with [specific requirements]"
```

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

### Load and Initialize Postcode Lookup Plugin

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/formidable

Loads the bundled Postcode Lookup plugin and sets up its initialization with an API key, context selector, and output field mappings. The setup is triggered after the DOM is fully loaded.

```html
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled@2"></script>

<script>
	document.addEventListener("DOMContentLoaded", function () {
		IdealPostcodes.PostcodeLookup.setup({
			apiKey: "ak_test",
			context: "#lookup_field",
			outputFields: {
				line_1: "#field_z9ghk",
				line_2: "#field_j0ep",
				line_3: "#field_jmuiw",
				post_town: "#field_qgsnb",
				postcode: "#field_h2n4z",
			},
			buttonClass: "lookup-button",
		});
	});
</script>
```

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

### Configuring API Key Restrictions for Multi-Tenant Applications

Source: https://docs.ideal-postcodes.co.uk/docs/guides/llms

A prompt template for designing API key strategies for complex multi-tenant applications. It specifies requirements like tenant subdomains, daily usage limits, and frontend integration in React, requesting guidance from Ideal Postcodes security documentation.

```text
I need to configure API key restrictions for a multi-tenant application where:
- Each tenant has their own subdomain
- I want to limit daily usage per tenant
- Frontend integration on React

Using the Ideal Postcodes security documentation, help me design the proper API key strategy.
```

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

### Install via Composer

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/magento

Installs the Ideal Postcodes Magento extension using Composer. This command adds the necessary package to your Magento project.

```bash
$ composer require idealpostcodes/module-ukaddresssearch
```

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

### Prompting LLM for Address Finder Integration

Source: https://docs.ideal-postcodes.co.uk/docs/guides/llms

An example prompt demonstrating how to request code generation from an LLM for integrating Ideal Postcodes' Address Finder into an HTML form. It specifies the desired functionality, data sources, and constraints.

```text
I'm building a checkout form and need to add Address Finder. Here's my current HTML structure:

[paste your form HTML]

Using the Ideal Postcodes documentation at https://docs.ideal-postcodes.co.uk/llms.txt,
help me integrate Address Finder with the following requirements:
- Single line address display
- UK addresses only
- Include UPRN data
```

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

### Initialize Multiple Postcode Lookup Fields (JavaScript)

Source: https://docs.ideal-postcodes.co.uk/docs/postcode-lookup/multiple

Initializes two independent Postcode Lookup fields using the PostcodeLookup.setup() method. Each instance can have a unique API key and output field mappings, ensuring isolated behavior and configurations.

```javascript
// Initialize each lookup field individually. You can specify completely different configurations. Each is isolated from the other.
// Hook up the first lookup field
PostcodeLookup.setup({
apiKey: "ak_test",
context: "#lookup_field",
outputFields: {
  line_1: "#first_line",
  line_2: "#second_line",
  line_3: "#third_line",
  post_town: "#post_town",
  postcode: "#postcode"
}
});
// Hookup the second lookup field
PostcodeLookup.setup({
apiKey: "ak_test",
context: "#lookup_field_2",
outputFields: {
  line_1: "#first_line_2",
  line_2: "#second_line_2",
  line_3: "#third_line_2",
  post_town: "#post_town_2",
  postcode: "#postcode_2"
}
});
```

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

### Retrieve Configuration API

Source: https://context7_llms

Retrieves a configuration object by name.

```APIDOC
## [GET] /config/{config_name}

### Description
Retrieve configuration object by name

### Method
GET

### Endpoint
/config/{config_name}

### Parameters
#### Path Parameters
- **config_name** (string) - Required - Name of the configuration to retrieve

### Request Example
```
/config/my_config
```

### Response
#### Success Response (200)
- **config** (object) - The configuration object.

#### Response Example
```json
{
 "id": "config123",
 "name": "my_config",
 "settings": { "setting1": "value1" }
}
```
```

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

### Building Group Example - IE Address Format

Source: https://docs.ideal-postcodes.co.uk/docs/data/ecad

Provides an example for the 'building_group' field in the IE Address (ECAD) format, which denotes a collection of buildings with a common name.

```text
Marrian Terrace
```

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

### Initialize Address Finder in Webflow

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/webflow

This script initializes the Address Finder service for Webflow forms. It requires the Address Finder bundled script and maps input fields to specific output elements. Ensure your API key and input field IDs are correctly configured.

```javascript
<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled"></script>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    IdealPostcodes.AddressFinder.setup({
      apiKey: "ak_test",
      outputFields: {
        line_1: '#field-1',
        line_2: '#field-2',
        line_3: '#field-3',
        post_town: '#field-4',
        postcode: '#field-5'
      }
    });
  });
</script>
```

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

### GET Postcode Lookup API Endpoint

Source: https://docs.ideal-postcodes.co.uk/docs/api/postcodes

This snippet details the GET request format for looking up addresses associated with a specific postcode. The API is case and space insensitive for postcode searches and returns a JSON response.

```HTTP
GET 
/postcodes/:postcode
```

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

### Eircode Example - IE Address Format

Source: https://docs.ideal-postcodes.co.uk/docs/data/ecad

Provides an example of a valid Eircode format as used in the IE Address (ECAD) system. Eircodes are mandatory and typically appear on the last line of a postal address.

```text
A65 R2AF
```

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

### Initialize Address Finder in Jotform

Source: https://docs.ideal-postcodes.co.uk/docs/integrations/jotform

This script initializes the Ideal Postcodes Address Finder plugin within a Jotform HTML block. It requires your API key and the field IDs of your address input fields to map correctly.

```javascript
document.addEventListener("DOMContentLoaded", function () {
		IdealPostcodes.AddressFinder.watch({
			apiKey: "ak_test",
			outputFields: {
				line_1: "#input_3",
				line_2: "#input_4",
				line_3: "#input_5",
				post_town: "#input_6",
				postcode: "#input_7",
			},
		});
	});
```

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

### GET Request for UMPRN Lookup

Source: https://docs.ideal-postcodes.co.uk/docs/api/umprn

This snippet shows the HTTP GET request format to retrieve a multiple occupancy address using its unique UMPRN. It specifies the endpoint structure and the expected UMPRN parameter.

```HTTP
GET /umprn/:umprn
```

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

### Implementing Specific Features with Address Finder (Template)

Source: https://docs.ideal-postcodes.co.uk/docs/guides/llms

A prompt template to request assistance with implementing a specific feature using the Ideal Postcodes Address Finder. It requires listing the feature and its associated requirements.

```text
"Using the Ideal Postcodes Address Finder documentation, help me implement
[specific feature] with these requirements: [list requirements]"
```