# Batch Processing Source: https://docs.loqate.com/ai-agents/cli/batch Verify or parse CSV files of contact data in bulk. Both `verify` and `parse` support batch processing via the `-b` flag, accepting CSV, TSV, and pipe-delimited files. ## Usage ```bash theme={null} lqt verify -b contacts.csv --policy shipping -o jsonl --summary ``` ## Supported file formats * **CSV** — comma-separated (default) * **TSV** — tab-separated * **Pipe-delimited** — pipe (`|`) separated ## Column mapping Reach automatically maps common column names to verification fields. Use any of the following column headers: ### Address fields | Recognized columns | | :- | | `address`, `address1`, `address_line_1`, `street` | | `address2`, `address_line_2` | | `city`, `locality` | | `state`, `admin_area`, `administrative_area`, `province`, `region` | | `postcode`, `postal_code`, `zip`, `zip_code` | | `country`, `country_code` | ### Contact fields | Recognized columns | | :- | | `email`, `email_address` | | `phone`, `phone_number`, `telephone` | ### Other fields | Recognized columns | | :- | | `name`, `full_name`, `first_name`, `last_name` | | `organization`, `company`, `org` | ## Example CSV ```csv theme={null} address,email,phone,country "125 Summer St, Boston, MA 02110",user@example.com,+16175551234,US "10 Downing Street, London, SW1A 2AA",info@gov.uk,+442071234567,GB "1600 Pennsylvania Ave, Washington DC 20500",contact@whitehouse.gov,+12025551234,US ``` ## Output formats Use `-o` to control the output format: | Format | Description | Best for | | :- | :- | :- | | `json` | Single JSON array | Small batches, debugging | | `jsonl` | One JSON object per line | Streaming, large batches, piping to other tools | | `table` | Human-readable table | Terminal review | ## Summary statistics Add `--summary` to get aggregate statistics after the batch completes: ```bash theme={null} lqt verify -b contacts.csv --policy standard -o jsonl --summary ``` The summary includes counts of `accept`, `review`, and `reject` outcomes, plus error counts. # CLI Installation Source: https://docs.loqate.com/ai-agents/cli/installation Install the lqt CLI on macOS, Linux, or Windows. The `lqt` CLI is a single Go binary with no dependencies. Pre-built binaries are available for all major platforms. ## Install > [tab] macOS (Apple Silicon) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_arm64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] macOS (Intel) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_amd64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Linux (x86\_64) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_amd64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Linux (ARM64) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_arm64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Windows > > Download `lqt_windows_amd64.zip` from the [latest release](https://github.com/gbgplc/lqt/releases/latest), extract `lqt.exe`, and add it to your PATH. Verify the installation: ```bash theme={null} lqt version ``` ## Set your API key > [tab] macOS / Linux > > ```bash theme={null} > export LOQATE_API_KEY=your-key-here > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > $env:LOQATE_API_KEY="your-key-here" > ``` > [!TIP] > > Don't have an API key? [Sign up for a free trial](https://account.loqate.com) with 45 days of access. ## Available commands | Command | Description | | :- | :- | | `lqt verify` | Verify addresses, emails, and phone numbers with policy-driven recommendations | | `lqt parse` | Parse and standardize contact data using Claude Haiku (no Loqate credits consumed) | | `lqt policy list` | Display available policies and their thresholds | | `lqt policy show` | Inspect a specific policy's configuration | | `lqt policy validate` | Validate a custom policy JSON file | | `lqt mcp` | Start the MCP server (stdio or HTTP mode) | | `lqt tool-description` | Export JSON schema for agent frameworks (LangChain, OpenAI, etc.) | | `lqt version` | Display the installed version | ## Global flags | Flag | Description | | :- | :- | | `-k, --key` | Override the Loqate API key | | `-o, --output` | Output format: `json`, `jsonl`, or `table` | | `-v, --verbose` | Enable verbose logging | | `--no-color` | Disable colored output | # Parse Command Source: https://docs.loqate.com/ai-agents/cli/parse Parse and standardize contact data using Claude Haiku — no Loqate credits consumed. The `parse` command standardizes contact data using Claude Haiku. It splits unstructured addresses into components, normalizes phone numbers, and validates email format — without making Loqate API calls or consuming credits. ## Usage ```bash theme={null} lqt parse [flags] ``` ## Flags | Flag | Description | | :- | :- | | `-a, --address` | Address to parse into components | | `-e, --email` | Email to validate format | | `-p, --phone` | Phone number to normalize | | `-c, --country` | Country hint (ISO 2-letter code) | | `-b, --batch` | Path to a CSV/TSV file for batch parsing | | `-o, --output` | Output format: `json`, `jsonl`, or `table` | | `--anthropic-key` | Override the Anthropic API key | ## Examples ### Parse an address ```bash theme={null} lqt parse -a "221B Baker Street London NW1 6XE United Kingdom" ``` ### Parse with a country hint ```bash theme={null} lqt parse -a "125 Summer St Boston MA 02110" -c US -o json ``` ### Batch parsing ```bash theme={null} lqt parse -b addresses.csv -o jsonl ``` ## Requirements The `parse` command requires an **Anthropic API key** for Claude Haiku access: > [tab] macOS / Linux > > ```bash theme={null} > export ANTHROPIC_API_KEY=your-key-here > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > $env:ANTHROPIC_API_KEY="your-key-here" > ``` > [!NOTE] > > The `parse` command does not call Loqate APIs and does not consume any Loqate account credits. It uses Claude Haiku for address standardization only. ## When to use parse vs verify | Use case | Command | | :- | :- | | Standardize address format before storage | `parse` | | Split unstructured address into components | `parse` | | Confirm an address is real and deliverable | `verify` | | Get a confidence score and recommendation | `verify` | | Pre-process data before batch verification | `parse`, then `verify` | # Verify Command Source: https://docs.loqate.com/ai-agents/cli/verify Verify addresses, emails, and phone numbers with policy-driven recommendations. The `verify` command validates contact data against Loqate APIs and returns a confidence score, match-level data, and a policy-aware recommendation. ## Usage ```bash theme={null} lqt verify [flags] ``` ## Flags | Flag | Description | | :- | :- | | `-a, --address` | Full address string | | `-e, --email` | Email address | | `-p, --phone` | Phone number (E.164 format recommended) | | `-c, --country` | ISO 2-letter country code | | `--policy` | Policy to apply: `strict`, `shipping`, `standard`, `permissive` | | `--policy-file` | Path to a custom policy JSON file | | `-b, --batch` | Path to a CSV/TSV file for batch processing | | `-o, --output` | Output format: `json`, `jsonl`, or `table` | | `-k, --key` | Override the Loqate API key | | `--field` | Pass extended Loqate input fields | | `--option` | Pass additional API options | | `--summary` | Display summary statistics (batch mode) | ## Examples ### Verify an address ```bash theme={null} lqt verify -a "10 Downing Street, London, SW1A 2AA, GB" -o json ``` ### Verify with a specific policy ```bash theme={null} lqt verify -a "10 Downing St, London, GB" --policy shipping -o json ``` ### Verify address, email, and phone together ```bash theme={null} lqt verify \ -a "221B Baker St, London, GB" \ -e "sherlock@example.com" \ -p "+442071234567" \ --policy strict \ -o json ``` ### Human-readable table output ```bash theme={null} lqt verify -a "125 Summer St, Boston, MA 02110, US" -o table ``` ## Response fields ### Address | Field | Description | | :- | :- | | `confidence` | Score between 0 and 1 | | `recommendation` | `accept`, `review`, or `reject` based on the active policy | | `avc` | Address Verification Code (e.g., `V44-I44-P7-100`) | | `verification_status` | `V` (verified), `P` (partially verified), `U` (unverified), `R` (reverified) | | `match_level` | `premise`, `street`, `locality`, `administrative_area`, or `country` | ### Email | Field | Description | | :- | :- | | `confidence` | Score between 0 and 1 | | `recommendation` | `accept`, `review`, or `reject` | | `response_code` | Loqate email validation response | | `risk` | `low`, `medium`, or `high` | | `flags` | Array of risk indicators (e.g., `disposable_domain`) | ### Phone | Field | Description | | :- | :- | | `confidence` | Score between 0 and 1 | | `recommendation` | `accept`, `review`, or `reject` | | `verified` | Whether the phone number is valid | | `number_type` | `mobile`, `landline`, `voip`, etc. | ### Overall | Field | Description | | :- | :- | | `recommendation` | Lowest-confidence field's recommendation | | `confidence` | Lowest confidence score across all verified fields | | `policy` | Name of the policy that was applied | ## Exit codes The CLI returns exit codes that agents and scripts can use for control flow: | Code | Meaning | | :- | :- | | `0` | `ACCEPT` — all fields passed the policy threshold | | `1` | `REVIEW` — one or more fields need human review | | `2` | `REJECT` — one or more fields failed the policy threshold | | `3` | `ERROR` — a request or configuration error occurred | # Loqate for AI Agents Source: https://docs.loqate.com/ai-agents/introduction Verify addresses, emails, and phone numbers from agentic systems — with confidence scores, policy-aware recommendations, and full audit trails. **Integrate Loqate into AI agents, LLM tool loops, and automated workflows.** Loqate for Agents provides developer tools purpose-built for agentic systems. Verify contact data in real time with deterministic scoring, policy-driven decisioning, and structured output that agents can act on without human intervention. > [card] [Overview](/ai-agents/overview) > > What is Reach and how it fits into agentic workflows > [card] [Quick Start](/ai-agents/quickstart) > > Install the CLI and run your first verification in under 2 minutes > [card] [CLI Reference](/ai-agents/cli/installation) > > Install and use the `lqt` command-line tool > [card] [MCP Server](/ai-agents/mcp/overview) > > Connect Loqate to Claude, Cursor, VS Code, and other MCP clients > [card] [Policies](/ai-agents/reference/policies) > > Built-in and custom policy frameworks for decisioning > [card] [Configuration](/ai-agents/reference/configuration) > > Authentication, environment variables, and key resolution *** ## Why Loqate for Agents? Traditional verification APIs return raw data that requires human interpretation. Loqate for Agents wraps verification in a decisioning layer — every response includes a confidence score (0–1), a policy-aware recommendation (`accept`, `review`, or `reject`), and a match-level assessment. This means your agent can make decisions autonomously based on structured, deterministic output. * **Deterministic scoring** — same input, same score, every time, across CLI, MCP, and API * **Policy-driven decisions** — four built-in policies (strict, shipping, standard, permissive) plus custom policy support * **Agent-native interfaces** — CLI for tool loops, MCP for direct agent integration, JSON output for pipelines * **245+ countries and territories** supported * **No new contract required** — uses your existing Loqate API key > [!TIP] > > Visit [agents.gbg.com/reach.html](https://agents.gbg.com/reach.html) for product information, demos, and the latest updates on Reach. # MCP Server Source: https://docs.loqate.com/ai-agents/mcp/overview Run Reach as an MCP server for Claude, Cursor, VS Code, and other MCP-compatible clients. The `lqt` binary includes a built-in MCP (Model Context Protocol) server that exposes Loqate verification as tools that AI agents can call directly. This means your agent can verify addresses, emails, and phone numbers without shelling out to the CLI — the MCP client handles tool invocation natively. ## Two modes | Mode | Command | Best for | | :- | :- | :- | | **Stdio** | `lqt mcp` | Local agents — Claude Code, Cursor, VS Code. Communicates over stdin/stdout. | | **HTTP** | `lqt mcp --http :8080` | Hosted deployments. Includes per-IP rate limiting, request logging, and a `/health` endpoint. | ## Setup by client > [tab] Claude Code > > Add Reach as a local MCP server: > > ```bash theme={null} > claude mcp add loqate -- lqt mcp > ``` > > Set your API key as an environment variable in your shell profile, or pass it in the MCP config: > > ```json .claude/settings.json theme={null} > { > "mcpServers": { > "loqate": { > "command": "lqt", > "args": ["mcp"], > "env": { > "LOQATE_API_KEY": "your-key-here" > } > } > } > } > ``` > > Verify the connection: > > ```bash theme={null} > claude mcp list > ``` > [tab] Claude Desktop > > Add to your Claude Desktop MCP configuration file: > > > [tab] macOS > > > > Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: > > > [tab] Windows > > > > Edit `%APPDATA%\Claude\claude_desktop_config.json`: > > ```json theme={null} > { > "mcpServers": { > "loqate": { > "command": "lqt", > "args": ["mcp"], > "env": { > "LOQATE_API_KEY": "your-key-here" > } > } > } > } > ``` > [tab] Cursor > > Add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global config): > > ```json .cursor/mcp.json theme={null} > { > "mcpServers": { > "loqate": { > "type": "stdio", > "command": "lqt", > "args": ["mcp"], > "env": { > "LOQATE_API_KEY": "your-key-here" > } > } > } > } > ``` > > Restart Cursor, then ask: "What Loqate tools do you have available?" > [tab] VS Code > > Create `.vscode/mcp.json` in your project: > > ```json theme={null} > { > "servers": { > "loqate": { > "type": "stdio", > "command": "lqt", > "args": ["mcp"], > "env": { > "LOQATE_API_KEY": "your-key-here" > } > } > } > } > ``` ## Remote MCP server If you prefer not to install the CLI, you can connect to the hosted MCP endpoint: ``` https://reach.prod.fabric.gbgplatforms.com/mcp ``` > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http loqate-reach https://reach.prod.fabric.gbgplatforms.com/mcp > ``` > [tab] Cursor > > ```json theme={null} > { > "mcpServers": { > "loqate-reach": { > "url": "https://reach.prod.fabric.gbgplatforms.com/mcp" > } > } > } > ``` > [!WARNING] > > The remote MCP server (HTTP mode) exposes 6 of the 9 tools. `parse_address`, `set_policy`, and `recommend_policy` are only available in stdio mode. See [Available Tools](/ai-agents/mcp/tools#tool-availability-by-mode) for the full breakdown. > [!NOTE] > > When using the remote MCP server, your API key can be configured at the organization level (Claude Desktop, Claude Code, Cursor) or passed per-session. See [Configuration](/ai-agents/reference/configuration) for details. ## HTTP mode For hosted or shared deployments, run the MCP server in HTTP mode: ```bash theme={null} lqt mcp --http :8080 ``` HTTP mode adds: * Per-IP rate limiting * Request logging * `/health` endpoint for load balancers and monitoring # MCP Tools Source: https://docs.loqate.com/ai-agents/mcp/tools The nine MCP tools available when running Reach as an MCP server. When running `lqt mcp` (stdio) or `lqt mcp --http :8080` (HTTP), Reach exposes nine tools that MCP-compatible clients can invoke. ## Verification tools ### verify\_address Verifies a postal address and returns a confidence score, AVC match level, and policy-aware recommendation. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `address` | string | yes | Full address string | | `country` | string | no | ISO 2-letter country code | | `policy` | string | no | Policy name or `default` | ### verify\_email Validates an email address for deliverability, disposable domain detection, and fraud risk. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `email` | string | yes | Email address to validate | | `policy` | string | no | Policy name or `default` | ### verify\_phone Validates a phone number, detecting number type and carrier information. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `phone` | string | yes | Phone number (E.164 recommended) | | `country` | string | no | ISO 2-letter country code | | `policy` | string | no | Policy name or `default` | ### verify\_contact Combined verification — verifies address, email, and phone in a single call with a unified confidence score. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `address` | string | no | Full address string | | `email` | string | no | Email address | | `phone` | string | no | Phone number | | `country` | string | no | ISO 2-letter country code | | `policy` | string | no | Policy name or `default` | > [!NOTE] > > At least one of `address`, `email`, or `phone` must be provided. ## Parsing tools ### parse\_address Parses an unstructured address into standardized components using Claude Haiku. Does not consume Loqate credits. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `address` | string | yes | Address to parse | | `country` | string | no | Country hint | ## Policy tools ### list\_policies Returns all available policies (four built-in plus any custom policies registered in the session). **Parameters:** None ### show\_policy Displays the thresholds and rules for a specific policy. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `name` | string | yes | Policy name | ### set\_policy Registers a custom policy for the current session. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `policy` | object | yes | Policy definition (see [Policies](/ai-agents/reference/policies)) | ### recommend\_policy Recommends a policy based on a described use case. **Parameters:** | Parameter | Type | Required | Description | | :- | :- | :- | :- | | `use_case` | string | yes | Description of your verification use case | ## Tool availability by mode | Tool | Stdio (9 tools) | HTTP (6 tools) | | :- | :-: | :-: | | `verify_address` | Yes | Yes | | `verify_email` | Yes | Yes | | `verify_phone` | Yes | Yes | | `verify_contact` | Yes | Yes | | `parse_address` | Yes | No | | `list_policies` | Yes | Yes | | `show_policy` | Yes | Yes | | `set_policy` | Yes | No | | `recommend_policy` | Yes | No | > [!NOTE] > > HTTP mode exposes fewer tools because `parse_address`, `set_policy`, and `recommend_policy` require local state or an Anthropic API key that may not be available in hosted environments. # Overview Source: https://docs.loqate.com/ai-agents/overview Reach is Loqate's agent-native verification tool — a CLI and MCP server that verifies addresses, emails, and phone numbers with deterministic scoring and policy-driven recommendations. ## What is Reach? Reach is GBG's agent-native identity and address verification product. It verifies addresses, emails, and phone numbers in real time — returning a confidence score, a policy-aware recommendation, and a full audit trail in one command. Reach is delivered as a single binary (`lqt`) that serves three interfaces from one verification engine: | Interface | Best for | How it works | | :- | :- | :- | | **CLI** | Tool loops, scripts, CI/CD | Single Go binary. Pipes JSON into agent frameworks. | | **MCP Server** | Claude, Cursor, VS Code, agent frameworks | Stdio mode for local agents, HTTP mode for hosted deployments. | | **Claude Agent Skill** | Claude users | Plain language interface installed via `npx skills add`. | All three interfaces share the same scoring engine — same input produces the same confidence score and recommendation regardless of which interface you use. ## How it works Every verification request follows the same flow: **1. Submit contact data** Send an address, email, phone number — or any combination — via the CLI, MCP tool, or skill. **2. Verification** Reach calls the Loqate APIs to verify each field and compute a confidence score between 0 and 1. **3. Policy evaluation** The confidence score is evaluated against the active policy's thresholds to produce a recommendation: `accept`, `review`, or `reject`. **4. Structured response** A JSON response is returned with per-field scores, an overall recommendation, match-level data, and an audit trail your agent can act on. ## Verification capabilities > [card] Address Verification > > Confidence scoring, AVC match level, verification status, premise-level matching across 245+ countries. > [card] Email Validation > > Disposable domain detection, fraud risk flags, deliverability assessment, catch-all detection. > [card] Phone Validation > > Number type detection (mobile/landline), carrier identification, E.164 normalization. > [card] Combined Verification > > Verify address, email, and phone in a single request with a unified confidence score and recommendation. ## Example output A single `verify` call returns structured JSON that agents can parse and act on: ```json theme={null} { "address": { "confidence": 0.95, "recommendation": "accept", "avc": "V44-I44-P7-100", "verification_status": "V", "match_level": "premise" }, "email": { "confidence": 0.15, "recommendation": "reject", "response_code": "Valid", "risk": "high", "flags": ["disposable_domain"] }, "phone": { "confidence": 0.93, "recommendation": "accept", "verified": true, "number_type": "mobile" }, "overall": { "recommendation": "reject", "confidence": 0.15 }, "policy": "strict" } ``` The `overall.recommendation` is the lowest-confidence field's recommendation — if any field fails the policy threshold, the overall recommendation reflects that. *This is an illustrative example. See the [lqt documentation](https://github.com/gbgplc/lqt) for full schema and response details.* ## What you need * A **Loqate API key** — [sign up](https://account.loqate.com) or use an existing key * The **`lqt` binary** — [installation guide](/ai-agents/cli/installation) * Optionally, an **Anthropic API key** for the `parse` command (address parsing via Claude Haiku) The CLI and MCP server are free. Verification calls consume credits from your Loqate account. # Quick Start Source: https://docs.loqate.com/ai-agents/quickstart Install the Reach CLI and verify your first address in under 2 minutes. Get up and running with Reach in three steps. ## 1. Install the CLI > [tab] macOS (Apple Silicon) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_arm64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] macOS (Intel) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_amd64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Linux (x86\_64) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_amd64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Linux (ARM64) > > ```bash theme={null} > curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_arm64.tar.gz | tar xz > sudo mv lqt /usr/local/bin/ > ``` > [tab] Windows > > Download `lqt_windows_amd64.zip` from the [latest release](https://github.com/gbgplc/lqt/releases/latest), extract `lqt.exe`, and add it to your PATH. Verify the installation: ```bash theme={null} lqt version ``` ## 2. Set your API key > [tab] macOS / Linux > > ```bash theme={null} > export LOQATE_API_KEY=your-key-here > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > $env:LOQATE_API_KEY="your-key-here" > ``` > [!TIP] > > Don't have an API key? [Create one](https://account.loqate.com) — Loqate offers a free trial with 45 days of access. ## 3. Verify an address ```bash theme={null} lqt verify -a "125 Summer Street, Boston, MA 02110, US" -o json ``` You'll get a structured response with a confidence score and recommendation: ```json theme={null} { "address": { "confidence": 0.97, "recommendation": "accept", "avc": "V44-I44-P6-100", "verification_status": "V", "match_level": "premise" }, "overall": { "recommendation": "accept", "confidence": 0.97 }, "policy": "standard" } ``` ## Next steps > [card] [Verify email and phone](/ai-agents/cli/verify) > > Combine address, email, and phone verification in a single command. > [card] [Set up MCP](/ai-agents/mcp/overview) > > Connect Reach to Claude, Cursor, or VS Code as an MCP server. > [card] [Choose a policy](/ai-agents/reference/policies) > > Pick from built-in policies or create a custom one for your use case. > [card] [Batch processing](/ai-agents/cli/batch) > > Verify CSV files of contact data in bulk. # Configuration Source: https://docs.loqate.com/ai-agents/reference/configuration Authentication, environment variables, and key resolution for the Reach CLI and MCP server. ## Authentication Reach requires a Loqate API key for verification. The `parse` command additionally requires an Anthropic API key for Claude Haiku access. ### Loqate API key Set your API key using any of these methods (listed in resolution order): | Method | Example | | :- | :- | | CLI flag | `lqt verify -k YOUR_KEY -a "..."` | | Environment variable | `export LOQATE_API_KEY=your-key-here` (macOS/Linux) or `$env:LOQATE_API_KEY="your-key-here"` (PowerShell) | | Key file | Create a `.loqate-key` file containing just the key | > [!TIP] > > Don't have an API key? [Sign up for a free trial](https://account.loqate.com) with 45 days of access. ### Anthropic API key (parse command only) Required only for the `parse` command and the `parse_address` MCP tool: | Method | Example | | :- | :- | | CLI flag | `lqt parse --anthropic-key YOUR_KEY -a "..."` | | Environment variable | `export ANTHROPIC_API_KEY=your-key-here` (macOS/Linux) or `$env:ANTHROPIC_API_KEY="your-key-here"` (PowerShell) | ## Environment variables | Variable | Description | | :- | :- | | `LOQATE_API_KEY` | Loqate API key for verification | | `ANTHROPIC_API_KEY` | Anthropic API key for the `parse` command | | `LOQATE_POLICY` | Default policy name (`strict`, `shipping`, `standard`, `permissive`) | | `LOQATE_VERIFY_URL` | Custom verification endpoint URL | | `LOQATE_VERIFY_KEY` | Custom verification endpoint key | ## Custom endpoints For customers with a dedicated or on-premise Loqate deployment, override the verification endpoint: > [tab] macOS / Linux > > ```bash theme={null} > export LOQATE_VERIFY_URL=https://your-custom-endpoint.example.com > export LOQATE_VERIFY_KEY=your-custom-key > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > $env:LOQATE_VERIFY_URL="https://your-custom-endpoint.example.com" > $env:LOQATE_VERIFY_KEY="your-custom-key" > ``` Or via CLI flags: ```bash theme={null} lqt verify --verify-url https://your-endpoint.example.com --verify-key your-key -a "..." ``` ## MCP API key provisioning When using the remote MCP server, API keys can be provisioned at different levels: ### Organization level For Claude Desktop, Claude Code, and Cursor, an administrator can set the API key in the organization's project instructions. All team members inherit access automatically. ### User level Individual users can configure their API key in their client's settings or user preferences. ### Session level Pass the API key directly in the chat for single-session use. The key is used for that session only and is not stored. ## Costs * The **CLI and MCP server** are free to use * **Verification calls** (`verify` command and verification MCP tools) consume credits from your Loqate account * The **`parse` command** does not consume Loqate credits (it uses Claude Haiku via your Anthropic key) * No new contract or procurement is required — Reach uses your existing Loqate account # Policies Source: https://docs.loqate.com/ai-agents/reference/policies Built-in and custom policy frameworks for controlling verification decisioning. Policies define the thresholds that determine whether contact data is accepted, flagged for review, or rejected. Every `verify` call evaluates results against a policy to produce an actionable recommendation. ## Built-in policies Reach ships with four policies covering common use cases: | Policy | Address Confidence | Match Level | Email Confidence | Phone Required | Use case | | :- | :-: | :-: | :-: | :-: | :- | | **strict** | 0.90 | premise | 0.85 | yes | KYC, fraud prevention, compliance | | **shipping** | 0.70 | street | 0.50 | no | Physical delivery, e-commerce | | **standard** | 0.55 | street | 0.45 | no | General verification (default) | | **permissive** | 0.30 | locality | 0.30 | no | Lead capture, marketing | ## Choosing a policy > [accordion] strict — KYC and fraud prevention > > Requires premise-level address matching (0.90 confidence), high email confidence (0.85), and phone verification. Use for financial services, identity verification, and any flow where false positives are costly. > [accordion] shipping — Physical delivery > > Requires street-level matching (0.70 confidence) and moderate email confidence (0.50). Phone is optional. Use for e-commerce checkout, delivery address validation, and logistics. > [accordion] standard — General purpose > > The default policy. Requires street-level matching (0.55 confidence) and basic email confidence (0.45). Suitable for most use cases where you want verification without being overly restrictive. > [accordion] permissive — Lead capture > > Accepts locality-level matching (0.30 confidence) with minimal thresholds. Use for lead forms, newsletter signups, and scenarios where you want to capture data even if it's imprecise. ## Using a policy ### CLI ```bash theme={null} lqt verify -a "10 Downing St, London, GB" --policy shipping -o json ``` ### Environment variable > [tab] macOS / Linux > > ```bash theme={null} > export LOQATE_POLICY=shipping > lqt verify -a "10 Downing St, London, GB" -o json > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > $env:LOQATE_POLICY="shipping" > lqt verify -a "10 Downing St, London, GB" -o json > ``` ### Policy resolution order When multiple policy sources are present, Reach resolves in this order: 1. `--policy-file` flag (custom policy JSON file) 2. `--policy` flag (named built-in policy) 3. `LOQATE_POLICY` environment variable 4. `.loqate-policy.json` file in the current directory 5. `standard` (default) ## Custom policies Create a JSON file to define your own thresholds: ```json custom-policy.json theme={null} { "name": "my-ecommerce-policy", "description": "Balanced policy for e-commerce checkout", "address": { "min_confidence": 0.65, "min_match_level": "street", "reject_verification_status": ["U", "R"] }, "email": { "min_confidence": 0.50, "allow_catch_all": true, "reject_disposable": true }, "phone": { "min_confidence": 0.40, "required": false } } ``` ### Custom policy fields #### Address | Field | Type | Description | | :- | :- | :- | | `min_confidence` | number | Minimum confidence score (0–1) to accept | | `min_match_level` | string | Minimum match level: `premise`, `street`, `locality`, `administrative_area`, `country` | | `reject_verification_status` | array | Verification statuses to auto-reject (e.g., `["U", "R"]`) | #### Email | Field | Type | Description | | :- | :- | :- | | `min_confidence` | number | Minimum confidence score (0–1) to accept | | `allow_catch_all` | boolean | Whether to accept catch-all email domains | | `reject_disposable` | boolean | Whether to reject disposable/temporary email domains | #### Phone | Field | Type | Description | | :- | :- | :- | | `min_confidence` | number | Minimum confidence score (0–1) to accept | | `required` | boolean | Whether phone verification is mandatory | ### Validate a custom policy ```bash theme={null} lqt policy validate custom-policy.json ``` ### Use a custom policy ```bash theme={null} lqt verify -a "10 Downing St, London, GB" --policy-file custom-policy.json -o json ``` ### Register via MCP In an MCP session, use the `set_policy` tool to register a custom policy for the current session. This is useful when your agent needs to switch policies based on context. # IBM watsonx Orchestrate Agent Source: https://docs.loqate.com/ai-agents/wxo/overview Reach as a native watsonx Orchestrate (WXO) agent — a data-quality agent that verifies and cleanses address, email, and phone data from inside WXO chats, collaborations, and workflows. **GBG Reach** is available as a native [IBM watsonx Orchestrate](https://www.ibm.com/products/watsonx-orchestrate) (WXO) agent. It brings the Reach verification engine — addresses, emails, and phone numbers with policy-aware decisioning — directly into watsonx Orchestrate. > [!NOTE] > > This is the same Reach product documented elsewhere in this section. The difference is the delivery surface: instead of the `lqt` CLI or a standalone MCP server, verification runs as a first-class WXO agent that you discover and add from inside watsonx Orchestrate — no code or local install required. ## How it relates to Reach The WXO agent is powered by the same hosted Reach engine that drives the [MCP server](/ai-agents/mcp/overview). The policy logic, confidence scoring, and AVC codes all run server-side, so a verification in watsonx Orchestrate returns the same result as the equivalent CLI or MCP call. You interact with it entirely through watsonx Orchestrate — in chat, as a collaborator, or as a step in a workflow. ## Capabilities > [card] Address Verification > > Verify, standardise, and cleanse postal addresses from free-form text or structured fields. > [card] Email Validation > > Check deliverability and format, with disposable-domain and risk detection. > [card] Phone Validation > > Validate and format phone numbers, E.164 preferred with country-code fallback. > [card] Combined Contact > > Verify address, email, and phone together with an overall accept / review / reject recommendation. > [card] Document Upload > > Paste a block of records or upload a CSV directly in the watsonx Orchestrate chat. > [card] Policy Decisioning > > Built-in `strict`, `shipping`, `standard`, and `permissive` policies control accept / review / reject thresholds. ## Structured output Every verification returns a structured report that collaborator agents and workflows can act on without human interpretation: ```json theme={null} { "summary": "Verified 1 record: Jane Doe accepted", "results": [ { "type": "contact", "name": "Jane Doe", "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA", "email": "jane.doe@example.com", "phone": "+16502530000", "decision": "accept", "confidence": 0.95, "policy": "standard", "reason": "All fields verified and standardised" } ] } ``` ## What you need * Access to an **IBM watsonx Orchestrate** instance * A **Loqate subscription**, provisioned and purchased through watsonx Orchestrate. Your Loqate API key is issued as part of that process — you don't need a separate Loqate account. ## Next steps > [card] [Usage](/ai-agents/wxo/usage) > > Discover and add the agent, then use it in chat, as a collaborator, or in a workflow. > [card] [Policies](/ai-agents/reference/policies) > > Built-in and custom decisioning policies. # Usage Source: https://docs.loqate.com/ai-agents/wxo/usage Discover and add the Reach agent in watsonx Orchestrate, then use it in chat, as a collaborator, or as a step in an agentic workflow. The Reach agent is discovered and added from inside watsonx Orchestrate — there's nothing to install locally. Once added, you can use it three ways, all returning the same structured [verification report](/ai-agents/wxo/overview#structured-output). ## Add the agent to your instance Reach is published as a native agent in the watsonx Orchestrate agent catalog. From your instance, browse the catalog, select **GBG Reach**, and add it. The **Loqate API key** the agent uses to authenticate is issued when you provision and purchase Loqate through watsonx Orchestrate — there's no separate Loqate account to set up. > [!NOTE] > > Discovering and adding a native agent is a standard watsonx Orchestrate workflow. For the exact steps in your environment — including the agent catalog and connection credentials — follow the [watsonx Orchestrate documentation](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base), using the version that matches your instance. ## 1. Interactive chat The simplest pattern — talk to the agent directly. It detects the data type, runs the right verification, and returns a decision with a confidence score. ```text theme={null} You: Verify this email: jane.doe@example.com Reach: jane.doe@example.com → accept (confidence 0.95, policy: standard) Deliverable, format valid, no risk flags. ``` You can also paste a block of records, or **upload a CSV**, and ask the agent to verify every row in one go. ## 2. Agent-to-agent (collaborator) Add Reach as a **collaborator** of another agent so a supervisor agent can hand off verification mid-conversation. The supervisor stays in control of the dialogue; when the user asks to verify, validate, or cleanse an address, email, or phone number, it delegates to Reach and receives a structured result back. This is configured in watsonx Orchestrate by listing Reach among the agent's collaborators — no code required. ## 3. As part of an agentic workflow For bulk, scheduled, or headless work, use Reach as a step inside a watsonx Orchestrate flow. A typical contact-cleansing flow reads records from your system of record, verifies and standardises each one through Reach, then writes the cleansed records back: ```text theme={null} [Read contacts] → for each record → [Reach: verify & standardise] → [Write cleansed records] ``` Reach supplies the verification step in the middle; the read and write-back steps connect to your own systems (CRM, data store, spreadsheet). Reach's structured output — decision, confidence, standardised fields, and reason per record — flows straight into the next step. ## Policies Every verification is evaluated against a policy that sets the accept / review / reject thresholds. Reach ships with `strict`, `shipping`, `standard` (the default), and `permissive`. You can ask the agent which policies are available or to explain a specific one, and you can name a policy in your request (for example, "verify these addresses using the strict policy"). > [!TIP] > > See [Policies](/ai-agents/reference/policies) for the full breakdown of each policy's thresholds and when to use it. # Capture Find: Filters Source: https://docs.loqate.com/api-reference/address-capture/filters Filter address search results by postcode, locality, thoroughfare, organization, and more. Use IS and ISN'T filters to refine address matches. Using Filters as part of a [Capture Find](/api-reference/address-capture/find) call you can include or exclude certain type of addresses or locations from the address matches presented back to the end user. All Filters are currently operating on the basis of an exact match. Multiple filters can be provided in the same request. `&Filters=:` - this is an **IS** filter and will limit matches to the subset where this field value is as specified `&Filters=!:` - this is an **ISN'T** filter and will exclude any matches where this field value is as specified ## Example This will return matches that are in Nottingham, UK and exclude addresses with NG11 7EP postcode: ``` &Filters=Locality:Nottingham&Filters=!Postcode:NG11 7EP ``` ## Available filters The following filters are supported: | Filter | Description | | :- | :- | | Postcode | Postal code / Postcode / ZIP Code. Values can be specified regardless of casing or spaces. In the US it is possible to specify ZIP Code without the Zip+4 part and the results will include all records with the primary ZIP Code specified. | | Locality | The most common population centre within a country (i.e. USA City, Canadian Municipality). | | DependentLocality | A smaller population centre, dependent on the contents of the Locality field (i.e. District). | | Thoroughfare | The name of the street or thoroughfare. | | OrganisationName | The name of the company listed at this address. | | Language | The three character alpha country code as defined by the ISO 639-2/B specification. *Note that using this filter can return blank results if the search term you're using isn't available in the language you're filtering by. For example, if you're searching for the word "strasse" and using 'countries=de', using the filter Language:eng (i.e. setting the language filter to English) will return a blank result.* | | AdministrativeArea (US addresses only) | The most common administrative district within a country (i.e. US State). | | SubAdministrativeArea (US addresses only) | The smallest administrative region within a country (i.e. US County). | | Attributes.CommercialResidential (US addresses only) | Address type. Allowed values are "Commercial" and "Residential". | | Attributes.HasSubPremise (US addresses only) | In the US, some addresses belong to a building that has a number of sub premises in it, (e.g. apartments or suites). By default, Capture will return an address of the building and a container with sub premises listed inside of it. You can exclude those building addresses where further sub premises exist by specifying a filter of HasSubpremises = NO. Allowed values are "YES" and "NO". | | HomeNation (UK addresses only) | This filter will restrict the results to addresses from the specified country within the UK. You can specify multiple values, and also invert the meaning to exclude selected countries (e.g. \&Filters=!HomeNation:Northern Ireland ) Allowed values are "England", "Scotland", "Wales", "Northern Ireland", "Channel Islands", "Isle of Man". | | Attributes.PostalAddress (AddressBase Premium Only) | Available only if AddressBase Premium has been enabled on your account for GB lookups. Filters addresses based on their postal delivery status. Allowed values are "D" (Royal Mail PAF), "N" (Not a postal address), "C" (postal and linked to PAF) or "L" (postal and linked to local authority) | # Capture Find Source: https://docs.loqate.com/api-reference/address-capture/find capture_interactive_find get /Capture/Interactive/Find/v1.20/json6.ws Search for addresses and places with type-ahead functionality. Returns address IDs for use with Retrieve API to get formatted addresses. Find does not return formatted addresses. Keep calling Find, narrowing the results with each request, until an address ID is returned. You must then pass that ID to the Retrieve service, which is the only way to get the fully formatted address. Find requests alone never return the final address, so every integration must end with a [Retrieve](/api-reference/address-capture/retrieve) call. **This method does not consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # GeoLocation - Mainland UK Only Source: https://docs.loqate.com/api-reference/address-capture/geolocation capture_interactive_geolocation get /Capture/Interactive/GeoLocation/v1.00/json6.ws Find mainland UK addresses within a radius of latitude/longitude coordinates using Ordnance Survey data. Returns address IDs for use with Retrieve API. The GeoLocation service takes latitude longitude coordinates and returns addresses that are within a specified radius. This must be followed by a Retrieve to obtain a fully formatted address. > [!WARNING] > > This service is only available for mainland UK (England, Scotland and Wales) addresses, using Ordnance Survey data **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Get Property Intelligence (UK) in a Capture Retrieve call Source: https://docs.loqate.com/api-reference/address-capture/property-intelligence Request UK property attributes, such as bedrooms, age, energy rating and distance to water, alongside a standard address Retrieve. ## Overview Property Intelligence supplies data on residential properties in England, Wales and Scotland. Northern Ireland has limited coverage. The Isle of Man and Channel Islands are not covered. **1. Find the address.** Use [Capture Find](/api-reference/address-capture/find) to get the `Id` of a UK address. **2. Choose your fields** Pick fields from the [field reference](#field-reference). **3. Call Retrieve** Pass each field as `FieldNFormat={FieldName}` and read the values from `FieldN`. > [!NOTE] > > **Property Intelligence is a Premium Dataset.** Please contact your account manager to activate this on your account. ## Build a request ### Parameters | Parameter | Required | Description | | - | - | - | | `Field1Format` … `Field20Format` | For PI fields | A field name in braces, such as `{Bedrooms}`. Separate several names in one parameter with commas. | | `Fields` | Above 20 | Number of `FieldX` slots to return. The default is 20 and the maximum is 50. | > [!NOTE] > > **Field limit.** A request returns 20 by default and 50 `FieldX` slots at most. If you need more than 20, add `Fields=`. ### Example request ```text Example URL theme={null} https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws ?Key=AA11-AA11-AA11-AA11 &Id=GB|RM|B|53165155|ENG &Field1Format={PropertyTypeDescription} &Field2Format={Bedrooms} &Field3Format={AgeDescription} &Field4Format={EnergyRating} &Field5Format={Watercourse200M} &Field6Format={UPRN} ``` ```javascript JavaScript theme={null} const fields = ["PropertyTypeDescription", "Bedrooms", "AgeDescription", "EnergyRating"]; const params = new URLSearchParams({ Key: "AA11-AA11-AA11-AA11", Id: addressId }); fields.forEach((f, i) => params.set(`Field${i + 1}Format`, `{${f}}`)); // More than 20 fields? params.set("Fields", fields.length); const res = await fetch( `https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws?${params}`); const item = (await res.json()).Items[0]; // FieldN holds the value requested as FieldNFormat const result = Object.fromEntries(fields.map((f, i) => [f, item[`Field${i + 1}`]])); ``` ## Read the response Each requested field comes back in the matching `FieldN` property of `Items[0]`, alongside the standard address fields. Every value is a string. ```json theme={null} { "Items": [{ "Id": "GB|RM|B|53165155|ENG", "Line1": "14 Eden Grove", "PostalCode": "CW4 8FP", "Field1": "Detached", "Field2": "3", "Field3": "1980 to date (Modern)", "Field4": "C", "Field5": "No", "Field6": "10014460505" }] } ``` In this example, `Field1` is `PropertyTypeDescription`, `Field2` is `Bedrooms`, and so on in request order. ## Field reference Use the **Retrieve field** name inside braces in FieldNFormat. Retrieve returns every value as a string. Fields marked England & Wales only aren't populated for Scotland or Northern Ireland. ### Property identifiers and location | Retrieve field | Type | Description | | - | - | - | | `UPRN` | Integer | **UPRN.** Unique Property Reference Number from Ordnance Survey. | | `UDPRN` | Integer | **UDPRN.** Unique Delivery Point Reference Number from Royal Mail. | | `Easting` | Float | **Easting.** Ordnance Survey National Grid easting. | | `Northing` | Float | **Northing.** Ordnance Survey National Grid northing. | | `Latitude` | Float | **Latitude.** Latitude in ETRS89, converted from easting/northing using OSTN02. | | `Longitude` | Float | **Longitude.** Longitude in ETRS89, converted from easting/northing using OSTN02. | | `OA11CD` | Text | **Output area (Census 2011).** Census 2011 Output Area code from the ONS Postcode Directory. | | `LSOA11CD` | Text | **Lower super output area (Census 2011).** Census 2011 LSOA code from the ONS Postcode Directory. | | `OA21CD` | Text | **Output area (Census 2021).** Census 2021 Output Area code from the ONS Postcode Directory. | | `LSOA21CD` | Text | **Lower super output area (Census 2021).** Census 2021 LSOA code from the ONS Postcode Directory. | ### Property | Retrieve field | Type | Description | | - | - | - | | `PropertyTypeDescription` | Text | **Property type.** Detached, semi-detached, terraced or flat. | | `Floors` | Text | **Number of floors.** Estimated number of floors, based on building height. | | `Bedrooms` | Text | **Number of bedrooms.** Number of bedrooms. | | `Bathrooms` | Text | **Number of bathrooms.** Number of bathrooms. | | `TotalRooms` | Text | **Total rooms.** Number of rooms, excluding bathrooms and kitchens. | | `FloorArea` | Text | **Floor area (m²).** Liveable floor area in square metres. | | `Extensions` | Text | **Number of extensions.** Number of extensions; typically 1, up to 4. | | `FlatFloor` | Text | **Storey of flat.** Storey on which a flat sits. Empty where not a flat or not available; may be modelled from source text. *England & Wales only* | | `TopFloorFlat` | Text | **Top-floor flat.** Whether a flat is on the top floor of the building. *England & Wales only* | | `IsMultires` | Text | **Multi-residential.** Flags multi-residential properties. | ### Age and listing | Retrieve field | Type | Description | | - | - | - | | `AgeDescription` | Text | **Construction period.** Construction period of the building. | | `AgeEarliest` | Text | **Earliest year of period.** Earliest year of the construction period. Returned alongside AgeDescription. | | `AgeLatest` | Text | **Latest year of period.** Latest year of the construction period. Empty for 1980 to date. | | `YearBuilt` | Text | **Year built.** Year built. Only available for buildings in Land Registry Price Paid data, built after 1995. | | `ListedStatus` | Text | **Listed building.** Grade of listing, from Historic England, Cadw or Historic Environment Scotland. | ### Building geometry | Retrieve field | Type | Description | | - | - | - | | `Cadastral` | Text | **Cadastral polygon area (m²).** Area of the cadastral parcel the building sits in, from Land Registry. *England & Wales only* | | `Height` | Text | **Height (m).** Building height in metres. | | `Footprint` | Text | **Footprint (m²).** Approximate building footprint in square metres. | | `Volume` | Text | **Volume (m³).** Approximate building volume in cubic metres. | | `AvgRoofSlope` | Text | **Average roof slope.** Average roof slope. Can identify flat roofs. | | `FlatRoofFraction` | Text | **Flat roof fraction.** Estimated fraction of the building with a flat roof. | | `GeocodeMultiplicity` | Text | **Geocode multiplicity.** Number of property geocodes within the building footprint at 1.8 m above ground. | ### Sale history and value | Retrieve field | Type | Description | | - | - | - | | `LastTransactionPrice` | Text | **Last transaction price.** Price paid at the last Land Registry transaction (back to 1995). *England & Wales only* | | `LastTransactionDate` | Text | **Last transaction date.** Date of the last Land Registry transaction (back to 1995). *England & Wales only* | | `LastTransactionDurationType` | Text | **Last transaction duration type.** Duration type of the last transaction. *England & Wales only* | | `EstCurrentValue` | Text | **Estimated current value.** Estimated current value, based on Land Registry data. *England & Wales only* | | `NTransactions` | Text | **Number of transactions.** Number of Land Registry transactions (back to 1995). *England & Wales only* | | `EstimatedCouncilTax` | Text | **Estimated council tax band.** Council tax band estimated from price at reference years, using Land Registry data. | ### Energy and construction | Retrieve field | Type | Description | | - | - | - | | `WallType` | Text | **Wall type.** Type of wall construction. | | `MainFuel` | Text | **Main central heating fuel.** Main central heating fuel. | | `EnergyRating` | Text | **Energy rating.** Energy rating from the EPC. | | `EpcInspectionDate` | Text | **EPC inspection date.** Inspection date on the EPC. | | `Tenure` | Text | **Tenure.** Owner-occupier, rented or social housing. | ### Environment and risk | Retrieve field | Type | Description | | - | - | - | | `Watercourse200M` | Text | **Within 200 m of watercourse.** Whether a watercourse is within 200 metres. | | `DistanceToWater` | Text | **Distance to watercourse (m).** Distance to a watercourse, if within 200 metres. 0.0 when Watercourse200M is No. | | `DistanceToTree` | Text | **Distance to tree (m).** Distance from the nearest tree over 10 m tall to the property geocode. | | `BurglaryRate` | Text | **Burglary rate.** Burglaries per property per year, averaged over the LSOA. *England & Wales only* | ### Location and use | Retrieve field | Type | Description | | - | - | - | | `DistanceToRoad` | Text | **Distance to road (m).** Distance to the centre line of the nearest road. Not necessarily accessible. | | `RoadClass` | Text | **Road class.** Road class, from Ordnance Survey. | | `BusinessUsage` | Text | **Business usage.** Flags potential business usage. | | `PlanningClassification` | Text | **Planning classification.** Use class under the Town and Country Planning (Use Classes) Order 1987, for non-domestic properties. | | `CongestionZone` | Text | **Congestion zone.** Whether the property is in the London Congestion Zone. | ## Flat file reference Property Intelligence is also available as a flat file for GB. The data dictionary lists every field in the file with examples and fill rates. [Property Intelligence data dictionary](/location-solutions/premium-data-sets/property-intelligence-data-directory) # Capture Retrieve Source: https://docs.loqate.com/api-reference/address-capture/retrieve capture_interactive_retrieve get /Capture/Interactive/Retrieve/v1.30/json6.ws Get formatted address details using the ID from Capture Find. Returns address lines, postal codes, and geographic information. **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # International Batch Cleanse Source: https://docs.loqate.com/api-reference/address-verify/international-batch-cleanse cleansing_international_batch post /Cleansing/International/Batch/v1.20/json6.ws Validate global addresses individually or in batches up to 100 records. Returns verified addresses with standardization and quality indicators. **To enable the best customer experience, the recommendation is to send batches of less than 100 records which are homogenous in terms of the location.** Grouping the requests into countries enables the Verify engine to manage its resources more effectively. > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. # International Batch Cleanse (Oracle Cloud) Source: https://docs.loqate.com/api-reference/address-verify/international-batch-cleanse-oci cleansing_international_batch_oci post /Cleansing/International/Batch/v1.20/json6.ws Validate global addresses individually or in batches up to 100 records via the Oracle Cloud-hosted Loqate Verify service. Returns verified addresses with standardization and quality indicators. **To enable the best customer experience, the recommendation is to send batches of less than 100 records which are homogenous in terms of the location.** Grouping the requests into countries enables the Verify engine to manage its resources more effectively. > [!NOTE] > > This endpoint is hosted on Oracle Cloud Infrastructure at `https://oci.location.gbg.com`. We don't support API connections using HTTP - all calls should use HTTPS. # Batch Bank Validation Source: https://docs.loqate.com/api-reference/bank-validation/batch bank_batch get /BankAccountValidation/Batch/Validate/v1.00/json6.ws Validate multiple UK bank accounts and sort codes in bulk. Returns corrected details, IBAN, and branch information. **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Individual Bank Validation Source: https://docs.loqate.com/api-reference/bank-validation/individual bank_individual get /BankAccountValidation/Interactive/Validate/v2.00/json6.ws Verify UK bank account numbers and sort codes individually. Returns corrected BACS details, IBAN, branch information, and payment service support. **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # International Bank Validation Source: https://docs.loqate.com/api-reference/bank-validation/international bank_international get /InternationalBankValidation/Interactive/Validate/v1.00/json6.ws Validate international bank account numbers internationally - excluding US. Returns whether IBAN format is correct. **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Bank Validation: RetrieveBySortcode Source: https://docs.loqate.com/api-reference/bank-validation/retrievebysortcode bank_retrieve_by_sortcode get /BankAccountValidation/Interactive/RetrieveBySortcode/v1.00/json6.ws Get UK bank branch details using sort code only. Returns bank name, BIC codes, branch contact information, and supported payment service types. **This method will consume credit.** > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Common Errors Source: https://docs.loqate.com/api-reference/common-errors Troubleshoot common API errors across Loqate services. Find solutions for authentication issues, credit limits, key restrictions, and more. If an error occurs, an error table like the one below (but containing a single row) will be returned. To test for an error response, look for a 4-column table with columns "Error", "Description", "Cause" and "Resolution". Generic errors like these have IDs below 100. Specific errors have IDs starting at 1000. | Id | Error | Cause | Resolution | | - | - | - | - | | **-1** | Unknown error | The cause of the error is unknown but details have been passed to our support staff who will investigate. | These problems are typically short lived and are often resolved by trying again in a few minutes. | | **2** | Unknown key | The key you are using to access the service was not found. | Please check that the key is correct. It should be in the form AA11-AA11-AA11-AA11. | | **3** | Account out of credit | Your account is either out of credit or has insufficient credit to service this request. | Please check your account balance and top it up if necessary. | | **4** | Request not allowed from this IP | The request was disallowed from the IP address. | Check the security settings on the key first. If they look fine, please contact support as it may be from an IP address on our blacklist. | | **5** | Request not allowed from this URL | The request was disallowed from the URL. | Check the security settings on the key first. If they look fine, please contact support as it may be from a URL on our blacklist. | | **6** | Web service not available on this key | The requested web service is disallowed on this key. | Check the security settings on the key first. You can limit a key to certain web services. | | **7** | Web service not available on your plan | The requested web service is not currently available on your payment plan. | Some services are only available in specific regions due to licensing restrictions. Please contact us for more information. | | **8** | Key daily limit exceeded | The daily limit on the key has been exceeded. | Alter the daily limit on the key. Check the usage details first to see if usage is normal. | | **9** | Your account has been suspended | Your account has been suspended. This can be for a number of reasons including non-payment of an invoice. | Please contact us in order to resolve this issue. | | **10** | Surge protector triggered | An unusually large number of requests have been processed for your account so the surge protector has been enabled. | You can disable the surge protector at any time but this is only recommended if you are running through a batch of requests. | | **11** | No valid license available | The request requires a valid license but none were found. | Please check your purchase history. You may be using a license that is no longer valid or of an incorrect type. | | **12** | Management key required | To use this web service you require a management key. Management can be enabled on any key, but we advise you to use management keys with care. | Sign in to the website and create a new management key or change an existing key. | | **13** | Demo limit exceeded | The daily demonstration limit for this service or account has been exceeded. | The limit will be reset at midnight tonight. If you would like the limit increased, please contact us. | | **14** | Free service limit exceeded | You have used too many free web services. | Our web services are designed to operate in stages. The first is usually a Find service followed by a Retrieve. If you use too many Finds without the corresponding number of Retrieves you will receive this error. For more information, please contact us. | | **15** | Wrong type of key | The type of key you're using isn't supported by this web service. | This usually happens if you're using a user or server license with a web service that only supports transactional keys. Please use another key and try again. | | **16** | Key expired | The key you are trying to use has expired. | Please check that you are using the right key. A new one may have been issued if you recently renewed your key. Contact us if you have any questions. | | **17** | Individual User exceeded Lookup Limit | An Individual User has exceeded their daily lookup limit on the key and that user will be prevented from using your service until tomorrow (GMT). | Check the usage details. If required, increase the Lookup Limit per Individual User or add the specific Individual User's IP to the Limiter Exclusions. | | **18** | Missing or invalid parameters | A required parameter was not supplied of the value of a parameter cannnot be converted into the right type. | Check the parameters passed and their values against the specification for this service. | | **19** | Invalid JSON object | The JSON object sent in your request is invalid. | Please ensure your JSON object is syntactically correct and try again. | | **20** | Endpoint not available | The web service you are calling is not available on this endpoint. | Refer to our documentation pages to ensure you are calling a valid endpoint for the web service you are requesting. | | **21** | Sandbox Mode is not available on this endpoint | The License key used has Sandbox Mode enabled, but the testing functionality is not available on this endpoint. | Disable the Sandbox Mode on the License key. | | **22** | HTTPS requests only | As of 3rd September 2018 all new accounts must use HTTPS. | Ensure you consume all of our APIs over HTTPS and not HTTP. | | **23** | Agreement Not Signed | There are agreements associated with service which are not signed. | Please go to your account and check your agreements. | | **24** | Not enough credit for request | There is not enough credit on the account to process the request. | Please top up your account with credit. | | **25** | Unexpected error, please contact the help desk for more information | | | # Batch Email Validation Source: https://docs.loqate.com/api-reference/email-validation/batch-validate email_batch get /EmailValidation/Batch/Validate/v1.20/json6.ws Verify up to 100 email addresses per batch request. Returns validation status, identifies disposable mailboxes, and detects system addresses. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Bulk Email Validation Source: https://docs.loqate.com/api-reference/email-validation/bulk-validate Validate up to 100,000 email addresses asynchronously using three endpoints. Submit lists, check processing status, and retrieve validation results. This service is comprised of three endpoints. See the [Bulk Email Validation](/our-services/email-validation/bulk-email-validation) guide for details of how these endpoints interact. > [card] [Submit](/api-reference/email-validation/bulk-submit) > > First, submit a list of emails for validation. > [card] [Status](/api-reference/email-validation/bulk-status) > > Next, check the status of your submission. > [card] [Retrieve](/api-reference/email-validation/bulk-retrieve) > > Lastly, retrieve the results of your validation. # Individual Email Validation Source: https://docs.loqate.com/api-reference/email-validation/individual email_individual get /EmailValidation/Interactive/Validate/v2.00/json6.ws Verify individual email addresses in real-time. Returns validation status, risk score, and identifies disposable or temporary mailboxes with 97% accuracy. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # DistancesAndDirections: Directions Source: https://docs.loqate.com/api-reference/geocode/distances-and-directions/directions geocode_directions get /DistancesAndDirections/Interactive/Directions/v2.00/json6.ws Get turn-by-turn directions between coordinates or postcodes. Returns step-by-step instructions with road names, distances, and time for each segment. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # DistancesAndDirections: Distance Source: https://docs.loqate.com/api-reference/geocode/distances-and-directions/distance geocode_distance get /DistancesAndDirections/Interactive/Distance/v1.00/json6.ws Calculate total distance and travel time between coordinates or postcodes. Supports multiple waypoints and returns measurements in metres and seconds. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: International Geocode Source: https://docs.loqate.com/api-reference/geocode/geocoding/international-geocode international_geocode get /Geocoding/International/Geocode/v1.10/json6.ws Convert postal codes or place names to WGS84 coordinates for international locations. Returns latitude and longitude for geocoding worldwide. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: International PositionToCountry Source: https://docs.loqate.com/api-reference/geocode/geocoding/international-positiontocountry international_positiontocountry get /Geocoding/International/PositionToCountry/v1.00/json6.ws Identify which country contains specific coordinates. Returns country name and ISO codes from WGS84 latitude and longitude input. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: International RetrieveNearestPlaces Source: https://docs.loqate.com/api-reference/geocode/geocoding/international-retrievenearestplaces international_retrievenearestplaces get /Geocoding/International/RetrieveNearestPlaces/v1.00/json6.ws Find nearest places of interest within a specified radius from any center point. Returns locations with distances and coordinates in kilometres. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: International ReverseGeocode Source: https://docs.loqate.com/api-reference/geocode/geocoding/international-reversegeocode international_reversegeocode get /Geocoding/International/ReverseGeocode/v2.00/json6.ws Convert WGS84 coordinates to nearest street addresses internationally. Returns street number, name, city, province, and postal code. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: UK Find Source: https://docs.loqate.com/api-reference/geocode/geocoding/uk-find uk_find get /Geocoding/UK/Find/v2.00/json6.ws Search UK locations by postcode, place name, street or town. Returns location IDs for use with Retrieve to get full coordinates. This method does not consume credit. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: UK Geocode Source: https://docs.loqate.com/api-reference/geocode/geocoding/uk-geocode uk_geocode get /Geocoding/UK/Geocode/v2.10/json6.ws Convert UK postcodes, place names, or addresses to OS easting/northing and WGS84 coordinates. Returns grid references with accuracy indicators. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: UK Retrieve Source: https://docs.loqate.com/api-reference/geocode/geocoding/uk-retrieve uk_retrieve get /Geocoding/UK/Retrieve/v2.00/json6.ws Get OS easting/northing and WGS84 coordinates from UK location IDs. Returns grid references for locations found with UK Find API. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: UK RetrieveNearestPlaces Source: https://docs.loqate.com/api-reference/geocode/geocoding/uk-retrievenearestplaces uk_retrievenearestplaces get /Geocoding/UK/RetrieveNearestPlaces/v1.20/json6.ws Find nearest UK places of interest within a radius from postcodes or coordinates. Returns locations with distances in metres and OS grid references. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding: UK ReverseGeocode Source: https://docs.loqate.com/api-reference/geocode/geocoding/uk-reversegeocode uk_reversegeocode get /Geocoding/UK/ReverseGeocode/v1.10/json6.ws Convert UK coordinates to nearest postcode. Accepts latitude/longitude or easting/northing input and returns distance with OS grid references. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # GovernmentData: Postzon RetrieveByCoordinates Source: https://docs.loqate.com/api-reference/geocode/governmentdata/postzon-retrievebycoordinates postzon_retrievebycoordinates get /GovernmentData/Postzon/RetrieveByCoordinates/v1.20/json6.ws Find nearest UK postcode and government data from coordinates. Returns ONS codes, NHS areas, constituencies, wards, and administrative boundaries. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # GovernmentData: Postzon RetrieveByPostcode Source: https://docs.loqate.com/api-reference/geocode/governmentdata/postzon-retrievebypostcode postzon_retrievebypostcode get /GovernmentData/Postzon/RetrieveByPostcode/v1.50/json6.ws Get comprehensive UK government data for any postcode. Returns coordinates, ONS codes, NHS areas, constituencies, wards, and council information. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # GovernmentData: Postzon RetrieveByPostcodeOrPlace Source: https://docs.loqate.com/api-reference/geocode/governmentdata/postzon-retrievebypostcodeorplace postzon_retrievebypostcodeorplace get /GovernmentData/Postzon/RetrieveByPostcodeOrPlace/v1.00/json6.ws Search UK government data by postcode or place name. Returns coordinates, ONS codes, NHS areas, constituencies, and local authority information. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # IP2Country Source: https://docs.loqate.com/api-reference/geocode/ip2country/ip2country extras_web_ip2country get /Extras/Web/Ip2Country/v1.10/json6.ws Identify which country an IP address belongs to. Returns ISO 2 and ISO 3 codes along with full country name. > [!NOTE] > > We don't support API connections using HTTP - all calls should use HTTPS. > [!NOTE] > > When no IP address is provided, the service will return the country of the IP address of the request, and will not consume credit. # StoreFinder: FindPlaceNames Source: https://docs.loqate.com/api-reference/geocode/store-finder/findplacenames findplacenames get /StoreFinder/Interactive/FindPlaceNames/v1.10/json6.ws Search towns, cities, and points of interest by name or postal code. Supports fuzzy and partial matching. This method does not consume credit. > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # StoreFinder: RetrieveCoordinates Source: https://docs.loqate.com/api-reference/geocode/store-finder/retrievecoordinates retrievecoordinates get /StoreFinder/Interactive/RetrieveCoordinates/v1.10/json6.ws Get coordinates for places found with FindPlaceNames. Returns WGS84 latitude/longitude and OS easting/northing for UK location IDs. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # APIs overview Source: https://docs.loqate.com/api-reference/introduction Introduction to Loqate API authentication, base URLs, and key setup. All services require HTTPS connections and valid API keys. Loqate services can be accessed securely over HTTPS - we do not support API connections that use HTTP or a TLS protocol below version 1.2. > [!NOTE] > > **New Beta SDKs available!** Try our early-access TypeScript and .NET SDKs — built on our live APIs and part of our ongoing tooling overhaul. > > See the [SDK Overview](/sdks/overview) for details. ## Base URL Each API has a base URL on which the required data endpoint can be appended, such as json3.ws or xmle.ws. For SOAP, use wsdlnew\.ws. > [!WARNING] > > Customers located in **China** should use services.postcodeanywhere.co.uk as part of the base URL, rather than api.addressy.com. ## Authentication APIs require authentication in the form of a key, which can be created by adding a service in your account. Each key has its own security settings (URL & IP restriction, usage limits), and as many keys as necessary can be set up with these restrictions. See the [Creating API Keys page](/loqate-basics/create-an-api-key/) for more information. A key must be passed to the API as a parameter in order for the request to authenticate, otherwise an error will be returned. ## Common errors Each API has specific errors that may be returned, as well as a common set of errors relating to either account or key settings. See the [Common errors page](/api-reference/common-errors) for details. # Individual Phone Validation Source: https://docs.loqate.com/api-reference/phone-validation/individual-validate phone_individual get /PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws Validate mobile, landline, and VoIP numbers for 237 countries. Returns network operator, number type, and porting or roaming status. **This method will consume credit.** > [!NOTE] > > This endpoint also accepts POST requests with parameters supplied as application/x-www-form-urlencoded. # Geocoding Typeahead Source: https://docs.loqate.com/api-reference/store-finder/geocoding-typeahead geocoding_typeahead post /LocationServices/Geocoding/GlobalTypeAhead/v1.10/json6.ws Type-ahead suggestions for towns, cities, states, and postcodes across 17 countries. Returns coordinates when users select a location from results. The Global Geocoding API currently supports an initial set of 18 countries, with more scheduled for inclusion in the near future. See the 'List of available countries' section below for details of which territories are available. > [accordion] List of available countries > > | ISO Code | Country Name | > | :- | :- | > | AU | Australia | > | BE | Belgium | > | CZ | Czech Republic | > | DE | Germany | > | ES | Spain | > | FR | France | > | GB | United Kingdom | > | HU | Hungary | > | IE | Ireland | > | IT | Italy | > | JP | Japan | > | KR | Republic of Korea | > | NL | Netherlands | > | NZ | New Zealand | > | PL | Poland | > | PT | Portugal | > | RO | Romania | > | SL | Slovenia | > | SK | Slovakia | > | US | United States | Text searches using the "Input" field are always free. This method will consume credit per "addressID" search and co-ordinates returned. ### Use of geocodes/addresses Use of the output of the Global Geocoding API is temporary, and only for use as part of a Store Finder. It is not permitted to index or store results for other purposes, such as use in a checkout process. For further information please see the [Loqate Terms and Conditions](https://www.gbgplc.com/en/legal-and-regulatory/products/loqate-storefinder/legal-notices-loqate-storefinder/). # Global Distance Finder Source: https://docs.loqate.com/api-reference/store-finder/global-distance-finder global_distance_finder post /LocationServices/DistanceFinder/Nearby/v1.10/json6.ws Find road-based distances and travel times between locations. Returns up to 100 nearest points within 500km radius. Please note that there are no limits to how many points you can send us, however your results returned will be limited to the nearest 100 points within a maximum of a 500km radius. In general there is a linear correlation between number of points/distance and response times. Due to this we recommend limiting to the fewest points possible for your application. Travel times are calculated using historical traffic data. This API supports most international locations. Distance calculation is supported between countries (e.g. France to Germany) provided that those countries are within the same region (e.g. Europe, Africa, Asia). **This method will consume credit. It is charged per request regardless of the number of destinations.** # Global Geocoding Source: https://docs.loqate.com/api-reference/store-finder/global-geocoding global_geocoding post /LocationServices/Geocoding/Global/v1.10/json6.ws Convert addresses to coordinates or reverse geocode coordinates to addresses. Supports most international locations for Store Finder implementations. When reverse geocoding, multiple addresses will be returned if possible (with a maximum of 5). This is because, particularly in urban areas, it can be difficult to identify the specific property associated with a set of co-ordinates. **A note on multiple inputs** Please note that whilst the API can accept an input of multiple addresses/co-ordinates, response times will be quicker if only one is sent at a time. For the UK, only the first address/co-ordinate in the string will be parsed (i.e. only one geocoding/reverse geocoding result will be provided). If sending multiple addresses/co-ordinates, limiting these to one country will also improve performance. The Global Geocoding API supports most international locations. For a full list of coverage please see [data coverage documentation](/data-coverage/introduction/). **This method will consume credit. You will be charged per address geocoded.** ### Use of geocodes/addresses Use of the output of the Global Geocoding API is temporary, and only for use as part of a Store Finder. It is not permitted to index or store results for other purposes, such as use in a checkout process. For further information please see the [Loqate Terms and Conditions](https://www.gbgplc.com/en/legal-and-regulatory/products/loqate-storefinder/legal-notices-loqate-storefinder/). # Location Management: Create List Source: https://docs.loqate.com/api-reference/store-finder/location-management-create-list create_list post /LocationServices/LocationManagement/CreateList/v1.10/json6.ws Create location lists with coordinates, addresses, and opening hours. Optional geocoding converts addresses to coordinates for up to 500 locations. > [!NOTE] > > This endpoint requires the use of a Loqate **Management** key. Management keys are used to provide access to server-side functions in place of your standard API key, > ensuring that were any of your keys to be scraped from a customer facing website, they could not be used to edit or delete your Location Lists. For information on how to create > a Management key please see the [Setting Up Store Finder Keys](/our-services/store-finder/setting-up-store-finder-keys) guide. The Create List API allows you to create a list of locations, including their co-ordinates and their IDs. It can also store additional information such as a description of each location, opening times, and address, to provide more context. This API also supports the use of a “metaInfo” object which can be used to store any other relevant information such as contact details, accessibility information etc. When uploading a list, co-ordinates for each location are mandatory. If you do not have the co-ordinates of a location but have the address instead, we can geocode those for you. If the geocoding option is selected we will geocode every address in your request, any existing geocodes you send us will be overwritten. When Geocoding a list, if a geocode cannot be found for one of your locations then the request will fail. You will not be charged, and we will outline which address(es) had caused the issue. **Please note that each address geocoded is chargeable based on your [standard geocoding cost](https://www.loqate.com/en-gb/pricing/).** Geocoding supports most international locations. For a full list of coverage please see [data coverage documentation](/data-coverage/introduction/). # Location Management: Delete List or Point Source: https://docs.loqate.com/api-reference/store-finder/location-management-delete-list-or-point delete_list_or_point post /LocationServices/LocationManagement/DeleteListOrPoint/v1.10/json6.ws Permanently delete location lists or individual points using management keys. Deletions cannot be recovered once completed. > [!NOTE] > > This endpoint requires the use of a Loqate **Management** key. Management keys are used to provide access to server-side functions in place of your standard API key, > ensuring that were any of your keys to be scraped from a customer facing website, they could not be used to edit or delete your Location Lists. For information on how to create > a Management key please see the [Setting Up Store Finder Keys](/our-services/store-finder/setting-up-store-finder-keys) guide. The Delete List or Point API allows you to delete an existing list created using our [Create List endpoint](/api-reference/store-finder/location-management-create-list). **NOTE: any lists deleted via this endpoint are deleted permanently. We do not back up location lists.** # Location Management: Get List Source: https://docs.loqate.com/api-reference/store-finder/location-management-get-list get_list post /LocationServices/LocationManagement/GetLists/v1.10/json6.ws View existing location lists with complete details for all points including coordinates, addresses, and metadata. The Get List API allows you to view an existing list created using our [Create List](/api-reference/store-finder/location-management-create-list) endpoint. # Location Management: Update List or Point Source: https://docs.loqate.com/api-reference/store-finder/location-management-update-list-or-point update_list_or_point post /LocationServices/LocationManagement/UpdateListOrPoint/v1.10/json6.ws Update location lists or individual points with new information. Add up to 100 new points per request while preserving existing location data. > [!NOTE] > > This endpoint requires the use of a Loqate **Management key**. Management keys are used to provide access to server-side functions in place of your standard API key, > ensuring that were any of your keys to be scraped from a customer facing website, they could not be used to edit or delete your Location Lists. For information on how to create > a Management key please see the [Setting Up Store Finder Keys](/our-services/store-finder/setting-up-store-finder-keys) guide. The Update List or Point API allows you to update an existing list created using our [Create List](/api-reference/store-finder/location-management-create-list) endpoint. When updating a list or point, any fields left null will retain their original information. To add new points to a list, only supply the new values - the existing points will be unaffected. You can add a maximum of 100 points to an existing list per request. # Map Tile API Source: https://docs.loqate.com/api-reference/store-finder/mapping mapping_get_url post /LocationServices/Mapping/GetUrl/v1.00/json6.ws Generate signed URLs for map tiles and basemap data. Use with MapLibre or Leaflet to render interactive maps showing customer locations and stores. > [!WARNING] > > Please note that we are unable to serve map data for China. The Map Tile API takes an input of your Loqate key and returns a Signed URL, which is valid for one hour and can be used to provide secure access our tile server. Whilst the Signed URL is active you can make as many requests using that URL as needed. Our tile server provides access to basemap data, tiles and styling for a map. This can then be used with a map rendering library, such as [MapLibre](https://github.com/maplibre/maplibre-gl-js) or [Leaflet](https://leafletjs.com/examples/quick-start/), to add an interactive map to your application. Other functionality required for your map, such as pins for locations, can then be added afterwards via the map renderer. ### Mapping Concepts There are several key concepts that are important to understand when implementing a map using this API: * **Signed URL:** a secure URL generated for a specific session within a limited time period, with limited permissions. This contains authentication information within the query, thus reducing the time required to authenticate and reducing overall response times. You will receive two signed URLs, one for vector based tiles and another for raster based tiles * **Basemap data:** basemaps form the foundation for your map, providing geographic context stored as tile layers. These layers include the context required to display useful information such as the names of streets, buildings and land categorisation * **Vector tiles:** a format of tile that stores map data using vector shapes. As these are composed dynamically, they can be easily styled and smoothly zoom in and out as a user is navigating. These are generally faster to load than Raster tiles, but can be more demanding on the end user's hardware * **Raster tiles:** a format of tile that stores map data using grids of pixels, commonly as images. These tiles can be slower to load than vector tiles, but are generally less demanding on the end user's hardware * **Map Style:** a Map style is a JSON document that defines how the map will appear when rendered * **Map renderer:** library required to render a map within an application. Once you have defined your data source as the signed URL you receive from this API, the map rendering library will pull data from Loqate at run time, rendering the map data for you. Commonly used open source libraries for this include MapLibre, Leaflet and Amplify ### Application flow using a map renderer Signed URLs can be used to request individual map tiles if required, however for more complex applications you're likely to use a map renderer. The following diagram represents how an application could be designed to work with our API and a map renderer: ![Application Flow](https://mintcdn.com/loqate/VN7o3YzokUitxNJS/images/store-finder/application_flow_may_25.png?fit=max\&auto=format\&n=VN7o3YzokUitxNJS\&q=85\&s=f4b4a69f2cbea5e264aaeb07e4aea225) Here are the steps this flow takes: 1. Make a request to [https://api.addressy.com/LocationServices/Mapping/GetUrl/v1.00/json4.ws?key=\{\{license\_key}}](https://api.addressy.com/LocationServices/Mapping/GetUrl/v1.00/json4.ws?key=\{\{license_key}}) (adding in your own API key) 2. Receive multiple Signed URLs in the response (one for Raster tiles and one for Vector tiles) 3. Choose whether you want to use Raster tiles or Vector tiles, and pass the appropriate Signed URL to the map renderer 4. The map renderer will request basemap data from Loqate as needed (for instance this could be when a user scrolls on your map and the renderer interprets which tiles will be needed next) 5. Loqate will return the appropriate map data 6. The map renderer will then use this data to render the map on the screen of your browser **This method will consume credit each time a signed URL is generated.** > [accordion] Attribution Statement > > You must ensure attribution is visible when rendering a map as part of your application. Loqate uses map styling from [OpenMapTiles](https://osmfoundation.org/wiki/Licence/Attribution_Guidelines) > and open data from [OpenStreetMaps](https://www.openstreetmap.org/copyright). Attribution is provided by default as part of the map style configuration, > however if you choose to create your own map styling you must still ensure that this attribution is visible. For further information on copyright notices please > see the [Loqate Terms and Conditions](https://www.gbgplc.com/en/legal-and-regulatory/products/loqate-storefinder/legal-notices-loqate-storefinder/). # Country Process Source: https://docs.loqate.com/available-processes/country-process The Country process is designed to attempt to identify a country from supplied input data. It performs the following processes: 1. Check the `ForceCountry` option. If set, use this. 2. Check each of the fields specified in the `CountryFields` option. If a valid country is found, use this. 3. Check the `DefaultCountry` option. If set, use this as a candidate. 4. Check the address fields for potential candidates and duplicates identified through the previous processes. ## Relevant Options * ForceCountry * CountryFields * DefaultCountry [Click here](/available-processes/introduction/) for the full list of supported options and their descriptions. # Format Process Source: https://docs.loqate.com/available-processes/format-process The Format process is designed to output fields using the specified casing and output script. ## Relevant Options * UseSymbolicTransliteration * OutputCasing * OutputScript [Click here](/available-processes/introduction/) for the full list of supported options and their descriptions. [Click here](/support/character-scripts/) for a list of supported character sets. # Geocode Process Source: https://docs.loqate.com/available-processes/geocode-process The Geocode process adds latitude, longitude, and GeoAccuracy where possible, and is generally used with either [Verify](/available-processes/verify-process/) or [Search](/available-processes/search-process/). ## Relevant Options * GeocodeCountryList # GKRInfo Tool Source: https://docs.loqate.com/available-processes/gkrinfo-process Each GKR file has a set of parameters and corresponding values. The GKRInfo process is designed to provide information about the GKR files' parameters. The GKR files are read from the data folder provided. ## API Usage The following code walks through API usage. ### Initialize the server ```java theme={null} lqtServer srv = lqtServer.create(); srv.init("C:\\loqate\\data"); lqtProcessList lst = lqtProcessList.create(); lqtProcessOptions opts = lqtProcessOptions.create(); ``` ### Set the tool ```java theme={null} lst.add("GKRInfo", opts); ``` ### Execute the process ```java theme={null} lqtInputRecord rec = lqtInputRecord.create(); lqtProcessResult res = lqtProcessResult.create(); srv.process(rec, lst, res); ``` ### Dump the output from the GKRInfo ```java theme={null} FileWriter outputFile = new FileWriter("C:\\output.txt"); PrintWriter out = new PrintWriter(outputFile); for (int record = 0; record < res.getCount(); record++) { out.print( "\n"); for (long field=0; field < res.getFieldCount(record); field++) { out.print( res.getFieldName(record, field) + ": " +"\t"); out.print( res.getField(record, field) + "\n"); } } ``` ## Output Information The GKRInfo tool enumerates data files in the data folder and collects all GKR parameters and their values. Each data file's information is stored in a separate Record inside the ProcessResult structure. ### Common Parameters | Parameter | Description | | - | - | | `Name` | Name of the data file | | `DataVersion` | Release version | | `GKRVersion` | Version number of data format | | `Reference.FieldCount` | The fields that have available data in the Reference data file for the specific country | | `Reference.ContentType.()` | The actual fields | | `Reference.FieldBlank.()` | Count of records where the particular field is blank (output for each relevant field) | | `Reference.FieldDistinct.()` | Count of records where the particular field is unique and not blank (output for each relevant field) | Most other parameters vary by file and provide miscellaneous information about the respective files. ### Example Output The following example shows parameters and values for `context.lfs`: ``` Name context.lfs CompressionType 0 Context.MaxNodeSize 256 Context.NodeLookupPos 2036 Context.RecordLookupPos 167805 File.Build.Context 1357346307 File.Version.Context 1 DataVersion 2013Q1.0 GKRVersion 1 ``` # Available Processes Source: https://docs.loqate.com/available-processes/introduction Loqate provides multiple address processing functions. Choose the process that fits your use case. ## Core Processes > [card] [Parse](/available-processes/parse-process/) > > Break addresses into individual components > [card] [Match](/available-processes/match-process/) > > Compare and match addresses against reference data > [card] [Format](/available-processes/format-process/) > > Format addresses to local postal standards > [card] [Verify](/available-processes/verify-process/) > > Validate and correct addresses > [card] [Geocode](/available-processes/geocode-process/) > > Convert addresses to latitude/longitude coordinates > [card] [ReverseGeocode](/available-processes/reverse-geocode-process/) > > Convert coordinates to addresses ## Utility Processes > [card] [Country](/available-processes/country-process/) > > Retrieve country-specific information > [card] [GKRInfo](/available-processes/gkrinfo-process/) > > Query geographic knowledge repository data > [card] [Report](/available-processes/report-process/) > > Generate processing reports ## Regional Certification Processes > [card] [CASS (USA)](/support/usa-cass-v2/) > > USPS CASS-certified address validation > [card] [SERP (Canada)](/local-apis/serp-overview/) > > Canada Post SERP-certified processing > [card] [AMAS (Australia)](/support/address-matching-approval-system-amas/) > > Australia Post AMAS-certified validation ## Deprecated Processes > [card] [Search (Maintenance Mode)](/available-processes/search-process/) > > Legacy search functionality - use alternative processes for new implementations # Match Process Source: https://docs.loqate.com/available-processes/match-process The Match process is designed to find the most closely matching record or records from the relevant reference data source to the supplied componentized input data. ## Relevant Options * SuppressAdditionFields * MaxResults * RangeDecompose * VerifyMatchRules ([click here](/support/match-rules-syntax/) for syntax information) [Click here](/available-processes/introduction/) for the full list of supported options and their descriptions. # Parse Process Source: https://docs.loqate.com/available-processes/parse-process The Parse process is designed to transform fully or partially unstructured address data into correctly componentized information. ## Relevant Options * ToolInfo * ConfidenceThreshold * SuppressFields [Click here](/available-processes/introduction/) for the full list of supported options and their descriptions. # Query Process Source: https://docs.loqate.com/available-processes/query-process ## Overview The Query process is designed to perform SQL-like custom queries on the Loqate GKR. It enables searching and retrieving multiple results of specific address components that meet user-definable conditions. The query-conditions are expressed in our proprietary query-language, an example using our Verify SaaS service and the syntax and semantics are described below. ```json theme={null} { "Key": "{{LoqateKey}}", "Options": { "Process": "Query", "ServerOptions": { "Table": "rd_US_vfy", "QueryString": "(PostalCodePrimary LIKE \"60010%*\")", "OutputFields": "Locality", "QueryClause": "Distinct", "AliasPreference": "First", "RangefieldPreference": "Match", "MaxResults": 655 } } } ``` Query is a debug tool to be used to support submission of support cases, and please note this tool is in maintenance mode with no planned future developments or bug fixes. ## Query Syntax and Semantics A query has the following syntax: ``` ...(<(>QUERY-EXPRESSION <)> ... ``` The terminology used in the query syntax is described below. Parenthesis may be used optionally to nest and string simple queries into compound queries: | Term | Syntax/Values | Description | | - | - | - | | PREFIX TAG | `~` | Means phonetic similarity (optional) | | SUFFIX TAG | `%`, `*` | `%` means auto-complete word, `*` means auto-complete phrase | | QUERY-KEYWORD | `word` | Tags apply at word level to qualify search criteria | | CONDITION-OPERATORS | `LIKE`, `CONTAINS` | `LIKE` = Ordered-matching, `CONTAINS` = Unordered-matching | | QUERY-EXPRESSION | `FieldName CONDITION-OPERATOR "QUERY-KEYWORD(s)"` | Complete query expression | | LOGICAL-OPERATORS | Two pipes, `&&` | Two pipes = logical OR, `&&` = logical AND, used to form compound queries | ## Example Queries | Query | Matches | Does Not Match | | - | - | - | | `Thoroughfare LIKE "Bayhill Dr"` | `Bayhill Dr` | `Dr Bayhill`, `Bayhill Drive` | | `Thoroughfare CONTAINS "Bayhill Dr"` | `Bayhill Dr`, `Dr Bayhill` | `Bayhill Drive` | | `Thoroughfare LIKE "~Payhill Dr"` | `Bayhill Dr` | `Bayhill Tr` | | `Thoroughfare CONTAINS "Bay% Dr"` | `Dr Bayhill`, `Bayhill Dr`, `Bay Dr` | `Bay Drive`, `TromBay Dr` | | `Thoroughfare LIKE "Bay Dr%"` | `Bay Dr`, `Bay Drive` | `Bayhill Dr`, `Bay Drive Ct` | | `Thoroughfare LIKE "Bay Dr%*"` | `Bay Dr`, `Bay Dr Ct`, `Bay Drive`, `Bay Drive Ct` | | | `(Thoroughfare CONTAINS "Bay%") && (Locality LIKE "San Bruno")` | `Bayhill Drive San Bruno`, `Bay Dr San Bruno`, `Bayhill Dr San Bruno` | | ## Process Options The query tool uses the following process options: | Option | Required | Description | | - | - | - | | `Table` | Required | Reference (GKR) table to be queried | | `QueryString` | Required | String expressing the query in the query language | | `OutputFields` | Optional | Comma separated output field-names desired. Field-names are case sensitive. Reserved keyword `ALL` (or null) returns all field in output. | | `MaxResults` | Optional | Max number of output records desired. Defaults to `10`, valid values are 1-1000. | | `QueryClause` | Optional | `DISTINCT`/`UNIQUE`/null specifies output address component-set to be distinct, unique, or unconstrained across the output record results, respectively. | | `AliasPreference` | Optional | Specify to return, for non-rangefields: `FIRST` - the first alias in fields desired in the output; `EXHAUSTIVE` - all combinations of every alias; `UNPROCESSED` (null) - field-value entry as stored in the GKR | | `RangefieldPreference` | Optional | Specify to return, for rangefields: `MATCH` - the queried value verified in the range; `RANGE` - the range containing the queried value after verification; `FULL` - every value in the range containing the queried value; `RAW` (null) - the range-field containing the queried value as stored in the table | ## Output The results of the query are returned in the `ProcessResult` object. # Report Process Source: https://docs.loqate.com/available-processes/report-process The Report process generates reports during batch processing. ## Supported Reports * Data Quality Report (DQR) * CASS Report * PS3553 Report * SERP Report ## Usage The Report Process is invoked from lqtBatch using the following command-line options: | Option | Description | | - | - | | `-r` | List of reports to generate (delimited by pipe character) | | `-ri` | Report info file passed to the report generator (optional) | | `-ro` | Report output file name (optional - uses default if not specified) | ## Report Types | Supported Report | Definition | | - | - | | **DQR** | Data Quality Report | | **CASS** | CASS Stage File Report | | **PS3553** | CASS summary report that may be submitted to USPS together with the mailing list that was processed using the CASS Process | | **SERP** | SERP address accuracy report | ## Example ```bash theme={null} lqtBatch.exe -p v -r DQR -i c:\test\input.txt -d c:\test\data -ro myreport.txt ``` # Reverse Geocode Process Source: https://docs.loqate.com/available-processes/reverse-geocode-process This process will provide address or location suggestions based on a proximity search of an input country, and digital latitude/longitude. ## API Usage Set the process: ``` lst.add("ReverseGeocode", opts); ``` Define required parameters (example given): ``` rec.set("Country", "BEL"); rec.set("Latitude", "50.848510"); rec.set("Longitude", "4.387950"); ``` ## Relevant Options * MaxResults (when not set, the default value is 1) # Product Update June 2022 Source: https://docs.loqate.com/available-processes/search-process The Search function in Verify is now deprecated and in Maintenance Mode – no fixes will be made to any issues discovered. This means that no further development or fixes to the functionality will be undertaken by Loqate. The existing functionality will remain but strategically Loqate Capture+ is the API to use to search for addresses. You can find details on Address Capture [here](https://www.loqate.com/en-gb/address-verification/address-capture/) and to get started use [Address Capture Quick Setup Guide](/our-services/address-capture/address-capture-quick-start). ## Search Process The Search process is designed for interactive environments where full or partial address data is provided as input and a list of closely matching results is returned as output. ## Relevant Options * `MaxResults` * `ConfidenceThreshold` * `MinimumSimilarity` * `SuppressFields` * `SuppressAdditionFields` * `OutputCasing` * `OutputScript` * `OutputSortType` ## Algorithm Options **`SearchAutocompleteIndexCheck`:** (`Yes`, `No`, default `Yes`). Specifies whether or not to use the 'autocomplete index' algorithm (useful for guaranteed response times of queries like '4916 est' in the USA). Related to this is the `AutocompleteIndexOnly` option (`Yes`, `No`, default `No`) which if set to `Yes` stops the use of any other search algorithms so gives a guaranteed response time in all situations. **`SearchLikeFieldCheck`:** (`Yes`, `No`, default `Yes`). Specifies whether or not to use the 'like field' algorithm (looks for an exact field match in the address field, useful for single items like postcodes, building names, organization names, etc) **`SimpleParse`:** (`Yes`, `No`, default `Yes`). Specifies whether or not to use the 'simple parse' algorithm (looks for something like premise + street in the address field, but is not particularly tolerant of invalid input data) **`CombinedSearchMethods`:** (`Yes`, `No`, default `Yes`). Specifies whether or not to use a word-based search algorithm (similar to a web search engine approach). # Verify Process Source: https://docs.loqate.com/available-processes/verify-process The Verify process is designed for batch environments, where the desire is to enter address information in address lines, address components or a combination of both and return the cleansed address data. Internally, the Verify process is implemented by running the Country, Parse, Match, and Format processes. ## Relevant Options * VerifyCountryList * MinimumVerificationLevel * MinimumMatchscore * MinimumPostcode * MaxResults * ConfidenceThreshold * SuppressFields * SuppressAdditionFields [Click here](/available-processes/introduction/) for the full list of supported options and their descriptions. Other options are relevant to the underlying Country, Parse, Match, and Format processes. # Country Data Coverage Source: https://docs.loqate.com/data-coverage/introduction You can also view the full Loqate international address line orders on the [Loqate International Address Formats](/data-coverage/loqate-international-address-formats/) page. Please visit the main Loqate site for product and coverage information about our [phone verification](https://www.loqate.com/en-us/phone-verification/) and [email verification](https://www.loqate.com/en-us/email-verification/) services. The countries listed below are supported by the Loqate products. The address verification and geocoding levels represent the highest component that is supported. These translate to the following: **Definition of Levels** * **L5+** Sub Building Coverage - Over 5% subbuilding data as % of the Premise data Delivery point (sub-building, such as suite, floor, apartment, etc) \[verify only] * **L5** Sub Building Coverage - less than 5% subbuilding data as % of the Premise data * **L4+** Premise Point Coverage > 75% (building name, house number) \[indicates building level for geocoding] * **L4** Premise Point Coverage >50% * **L4-** Premise Points below 50% coverage * **L3** Thoroughfare/Street * **L2** Locality (City/Town/Village etc) * **L1** Admin area (County, Province or State) The +/- provides a more granular indication of how good the data is at the stated level. This is only relevant for the verification level. Some details on Loqate’s continuous improvement process (PDH) can be found [here](/getting-started/country-improvement-program/). All country datasets listed below are shipped with both the installed and cloud Verify/Geocode product. | Country/territory name | Region | ISO2 | ISO3 | Verification | Geocode | PDH Process applied | Loqate Tier | | - | - | - | - | - | - | - | - | | **Afghanistan** | Asia | AF | AFG | L2 | L2 | Yes | 4. Base | | **Albania** | Eastern Europe | AL | ALB | L4- | L4 | | 4. Base | | **Algeria** | Middle East & Africa | DZ | DZA | L3 | L3 | | 4. Base | | **American Samoa** | North America | AS | ASM | L3 | L3 | | 4. Base | | **Andorra** | Western Europe | AD | AND | L4- | L4 | Yes | 4. Base | | **Angola** | Middle East & Africa | AO | AGO | L3 | L3 | Yes | 4. Base | | **Anguilla** | Central America & Caribbean | AI | AIA | L2 | L2 | Yes | 4. Base | | **Antarctica** | Pacific & Arctic | AQ | ATA | L2 | L2 | Yes | 4. Base | | **Antigua and Barbuda** | Central America & Caribbean | AG | ATG | L3 | L3 | Yes | 4. Base | | **Argentina** | South America | AR | ARG | L4- | L4 | Yes | 2. Core | | **Armenia** | Eastern Europe | AM | ARM | L3 | L3 | Yes | 4. Base | | **Aruba** | Central America & Caribbean | AW | ABW | L3 | L3 | | 4. Base | | **Australia** | Pacific & Arctic | AU | AUS | L5 | L4 | Yes | 1. Strategic | | **Austria** | Western Europe | AT | AUT | L5+ | L4 | Yes | 2. Core | | **Azerbaijan** | Eastern Europe | AZ | AZE | L4- | L4 | Yes | 4. Base | | **Bahamas** | Central America & Caribbean | BS | BHS | L4- | L4 | Yes | 4. Base | | **Bahrain** | Middle East & Africa | BH | BHR | L4+ | L4 | | 4. Base | | **Bangladesh** | Asia | BD | BGD | L3+ | L3 | Yes | 4. Base | | **Barbados** | Central America & Caribbean | BB | BRB | L3 | L3 | Yes | 4. Base | | **Belarus** | Eastern Europe | BY | BLR | L4- | L4 | Yes | 4. Base | | **Belgium** | Western Europe | BE | BEL | L5+ | L4 | Yes | 2. Core | | **Belize** | Central America & Caribbean | BZ | BLZ | L3 | L3 | Yes | 4. Base | | **Benin** | Middle East & Africa | BJ | BEN | L3 | L3 | Yes | 4. Base | | **Bermuda** | Central America & Caribbean | BM | BMU | L3 | L3 | Yes | 4. Base | | **Bhutan** | Asia | BT | BTN | L2 | L2 | Yes | 4. Base | | **Bolivia, Plurinational State of** | South America | BO | BOL | L3 | L3 | Yes | 4. Base | | **Bonaire, Sint Eustatius and Saba** | Central America & Caribbean | BQ | BES | L3 | L3 | Yes | 4. Base | | **Bosnia and Herzegovina** | Eastern Europe | BA | BIH | L3 | L3 | Yes | 4. Base | | **Botswana** | Middle East & Africa | BW | BWA | L3 | L3 | | 4. Base | | **Bouvet Island** | Pacific & Arctic | BV | BVT | L2 | L2 | Yes | 4. Base | | **Brazil** | South America | BR | BRA | L5+ | L4 | Yes | 2. Core | | **British Indian Ocean Territory** | Asia | IO | IOT | L2 | L2 | Yes | 4. Base | | **Brunei Darussalam** | Asia | BN | BRN | L4+ | L4 | | 4. Base | | **Bulgaria** | Eastern Europe | BG | BGR | L4- | L4 | Yes | 2. Core | | **Burkina Faso** | Middle East & Africa | BF | BFA | L3 | L3 | Yes | 4. Base | | **Burundi** | Middle East & Africa | BI | BDI | L3- | L3 | Yes | 4. Base | | **Cambodia** | Asia | KH | KHM | L3 | L3 | Yes | 4. Base | | **Cameroon** | Middle East & Africa | CM | CMR | L2 | L2 | | 4. Base | | **Canada** | North America | CA | CAN | L5+ | L4 | Yes | 1. Strategic | | **Cape Verde** | Central America & Caribbean | CV | CPV | L3 | L3 | | 4. Base | | **Cayman Islands** | Central America & Caribbean | KY | CYM | L3 | L3 | | 4. Base | | **Central African Republic** | Middle East & Africa | CF | CAF | L3 | L3 | | 4. Base | | **Chad** | Middle East & Africa | TD | TCD | L2 | L2 | Yes | 4. Base | | **Chile** | South America | CL | CHL | L4- | L4 | Yes | 3. Growth | | **China** | Asia | CN | CHN | L3+ | L2 | Premium Data Available | 4. Base | | **Christmas Island** | Pacific & Arctic | CX | CXR | L5 | L4 | | 4. Base | | **Cocos (Keeling) Islands** | Pacific & Arctic | CC | CCK | L5 | L4 | Yes | 4. Base | | **Colombia** | South America | CO | COL | L4- | L4 | Yes | 3. Growth | | **Comoros** | Middle East & Africa | KM | COM | L3 | L3 | Yes | 4. Base | | **Congo** | Middle East & Africa | CG | COG | L3 | L3 | | 4. Base | | **Congo, the Democratic Republic of the** | Middle East & Africa | CD | COD | L3 | L3 | Yes | 4. Base | | **Cook Islands** | Pacific & Arctic | CK | COK | L3 | L3 | | 4. Base | | **Costa Rica** | Central America & Caribbean | CR | CRI | L3 | L3 | Yes | 4. Base | | **Croatia** | Eastern Europe | HR | HRV | L4+ | L4 | Yes | 2. Core | | **Cuba** | Central America & Caribbean | CU | CUB | L3 | L3 | Yes | 4. Base | | **Curaçao** | Central America & Caribbean | CW | CUW | L2 | L2 | Yes | 4. Base | | **Cyprus** | Western Europe | CY | CYP | L4- | L4 | Yes | 4. Base | | **Czech Republic** | Eastern Europe | CZ | CZE | L4 | L4 | Yes | 2. Core | | **Côte d'Ivoire** | Middle East & Africa | CI | CIV | L3 | L3 | | 4. Base | | **Denmark** | Western Europe | DK | DNK | L5+ | L4 | Yes | 2. Core | | **Djibouti** | Middle East & Africa | DJ | DJI | L3 | L3 | | 4. Base | | **Dominica** | Central America & Caribbean | DM | DMA | L3 | L3 | Yes | 4. Base | | **Dominican Republic** | Central America & Caribbean | DO | DOM | L3 | L3 | Yes | 4. Base | | **Ecuador** | South America | EC | ECU | L3 | L3 | Yes | 4. Base | | **Egypt** | Middle East & Africa | EG | EGY | L4- | L4 | Yes | 4. Base | | **El Salvador** | Central America & Caribbean | SV | SLV | L3 | L3 | Yes | 4. Base | | **Equatorial Guinea** | Middle East & Africa | GQ | GNQ | L2 | L2 | Yes | 4. Base | | **Eritrea** | Middle East & Africa | ER | ERI | L3- | L3 | | 4. Base | | **Estonia** | Eastern Europe | EE | EST | L4- | L4 | Yes | 4. Base | | **Eswatini** | Middle East & Africa | SZ | SWZ | L3 | L3 | Yes | 4. Base | | **Ethiopia** | Middle East & Africa | ET | ETH | L3- | L3 | | 4. Base | | **Falkland Islands (Malvinas)** | South America | FK | FLK | L3 | L3 | | 4. Base | | **Faroe Islands** | Western Europe | FO | FRO | L4+ | L4 | | 4. Base | | **Fiji** | Pacific & Arctic | FJ | FJI | L3 | L3 | Yes | 4. Base | | **Finland** | Western Europe | FI | FIN | L4+ | L4 | Yes | 2. Core | | **France** | Western Europe | FR | FRA | L4+ | L4 | Yes | 2. Core | | **French Guiana** | South America | GF | GUF | L4+ | L4 | | 4. Base | | **French Polynesia** | Pacific & Arctic | PF | PYF | L3 | L3 | Yes | 4. Base | | **French Southern Territories** | Pacific & Arctic | TF | ATF | L2 | L2 | Yes | 4. Base | | **Gabon** | Middle East & Africa | GA | GAB | L2 | L2 | Yes | 4. Base | | **Gambia** | Middle East & Africa | GM | GMB | L3 | L3 | Yes | 4. Base | | **Georgia** | Eastern Europe | GE | GEO | L3 | L3 | Yes | 4. Base | | **Germany** | Western Europe | DE | DEU | L4+ | L4 | Yes | 1. Strategic | | **Ghana** | Middle East & Africa | GH | GHA | L3 | L3 | | 4. Base | | **Gibraltar** | Western Europe | GI | GIB | L4- | L4 | | 4. Base | | **Greece** | Western Europe | GR | GRC | L4- | L4 | Yes | 2. Core | | **Greenland** | Western Europe | GL | GRL | L3 | L3 | Yes | 4. Base | | **Grenada** | Central America & Caribbean | GD | GRD | L2 | L2 | Yes | 4. Base | | **Guadeloupe** | Central America & Caribbean | GP | GLP | L4+ | L4 | Yes | 4. Base | | **Guam** | North America | GU | GUM | L5+ | L4 | Yes | 4. Base | | **Guatemala** | Central America & Caribbean | GT | GTM | L3 | L3 | | 4. Base | | **Guernsey** | Western Europe | GG | GGY | L5+ | L3 | Yes | 4. Base | | **Guinea** | Middle East & Africa | GN | GIN | L3- | L3 | | 4. Base | | **Guinea-Bissau** | Middle East & Africa | GW | GNB | L2 | L2 | Yes | 4. Base | | **Guyana** | South America | GY | GUY | L3 | L3 | Yes | 4. Base | | **Haiti** | Central America & Caribbean | HT | HTI | L3 | L3 | Yes | 4. Base | | **Heard Island and McDonald Islands** | Pacific & Arctic | HM | HMD | L2 | L2 | Yes | 4. Base | | **Holy See (Vatican City State)** | Western Europe | VA | VAT | L3 | L3 | Yes | 4. Base | | **Honduras** | Central America & Caribbean | HN | HND | L3 | L3 | Yes | 4. Base | | **Hong Kong** | Asia | HK | HKG | L5+ | L4 | Yes | 3. Growth | | **Hungary** | Eastern Europe | HU | HUN | L4+ | L4 | Yes | 2. Core | | **Iceland** | Western Europe | IS | ISL | L4+ | L4 | Yes | 4. Base | | **India** | Asia | IN | IND | L4- | L4 | Yes | 2. Core | | **Indonesia** | Asia | ID | IDN | L4- | L4 | Yes | 3. Growth | | **Iran, Islamic Republic of** | Middle East & Africa | IR | IRN | L2 | L2 | Yes | 4. Base | | **Iraq** | Middle East & Africa | IQ | IRQ | L3- | L3 | Yes | 4. Base | | **Ireland** | Western Europe | IE | IRL | L4 | L4 | Yes | 2. Core | | **Isle of Man** | Western Europe | IM | IMN | L5+ | L3 | Yes | 4. Base | | **Israel** | Middle East & Africa | IL | ISR | L4- | L4 | Yes | 4. Base | | **Italy** | Western Europe | IT | ITA | L4+ | L4 | Yes | 2. Core | | **Jamaica** | Central America & Caribbean | JM | JAM | L3 | L3 | Yes | 4. Base | | **Japan** | Asia | JP | JPN | L4 | L4 | Yes | 2. Core | | **Jersey** | Western Europe | JE | JEY | L5+ | L3 | Yes | 4. Base | | **Jordan** | Middle East & Africa | JO | JOR | L4- | L4 | Yes | 4. Base | | **Kazakhstan** | Eastern Europe | KZ | KAZ | L4- | L4 | Yes | 4. Base | | **Kenya** | Middle East & Africa | KE | KEN | L3 | L3 | Yes | 4. Base | | **Kiribati** | Pacific & Arctic | KI | KIR | L2 | L2 | Yes | 4. Base | | **Korea, Democratic People's Republic of** | Asia | KP | PRK | L2 | L2 | Yes | 4. Base | | **Korea, Republic of** | Asia | KR | KOR | L5+ | L4 | Yes | 2. Core | | **Kosovo** | Eastern Europe | XK | XKX | L4+ | L4 | Yes | 4. Base | | **Kuwait** | Middle East & Africa | KW | KWT | L4 | L4 | | 4. Base | | **Kyrgyzstan** | Eastern Europe | KG | KGZ | L3 | L3 | Yes | 4. Base | | **Lao People's Democratic Republic** | Asia | LA | LAO | L2 | L2 | Yes | 4. Base | | **Latvia** | Eastern Europe | LV | LVA | L4- | L4 | Yes | 4. Base | | **Lebanon** | Middle East & Africa | LB | LBN | L3 | L3 | | 4. Base | | **Lesotho** | Middle East & Africa | LS | LSO | L3 | L3 | | 4. Base | | **Liberia** | Middle East & Africa | LR | LBR | L3 | L3 | | 4. Base | | **Libya** | Middle East & Africa | LY | LBY | L3 | L3 | | 4. Base | | **Liechtenstein** | Western Europe | LI | LIE | L4+ | L4 | Yes | 4. Base | | **Lithuania** | Eastern Europe | LT | LTU | L4 | L4 | Yes | 4. Base | | **Luxembourg** | Western Europe | LU | LUX | L4 | L4 | Yes | 4. Base | | **Macao** | Asia | MO | MAC | L4- | L4 | Yes | 4. Base | | **North Macedonia** | Eastern Europe | MK | MKD | L4- | L4 | Yes | 4. Base | | **Madagascar** | Middle East & Africa | MG | MDG | L3- | L3 | | 4. Base | | **Malawi** | Middle East & Africa | MW | MWI | L3 | L3 | | 4. Base | | **Malaysia** | Asia | MY | MYS | L5 | L4 | Yes | 3. Growth | | **Maldives** | Middle East & Africa | MV | MDV | L3- | L3 | | 4. Base | | **Mali** | Middle East & Africa | ML | MLI | L3 | L3 | Yes | 4. Base | | **Malta** | Western Europe | MT | MLT | L3 | L3 | Yes | 4. Base | | **Marshall Islands** | North America | MH | MHL | L3 | L3 | Yes | 4. Base | | **Martinique** | Central America & Caribbean | MQ | MTQ | L4+ | L4 | Yes | 4. Base | | **Mauritania** | Middle East & Africa | MR | MRT | L3 | L3 | | 4. Base | | **Mauritius** | Middle East & Africa | MU | MUS | L3 | L3 | | 4. Base | | **Mayotte** | Middle East & Africa | YT | MYT | L4+ | L4 | | 4. Base | | **Mexico** | Central America & Caribbean | MX | MEX | L4+ | L4 | Yes | 2. Core | | **Micronesia, Federated States of** | North America | FM | FSM | L3 | L2 | Yes | 4. Base | | **Moldova, Republic of** | Eastern Europe | MD | MDA | L4- | L4 | Yes | 4. Base | | **Monaco** | Western Europe | MC | MCO | L4- | L4 | | 4. Base | | **Mongolia** | Asia | MN | MNG | L3- | L3 | Yes | 4. Base | | **Montenegro** | Eastern Europe | ME | MNE | L3 | L3 | | 4. Base | | **Montserrat** | Central America & Caribbean | MS | MSR | L2 | L2 | Yes | 4. Base | | **Morocco** | Middle East & Africa | MA | MAR | L3 | L3 | | 4. Base | | **Mozambique** | Middle East & Africa | MZ | MOZ | L3 | L3 | Yes | 4. Base | | **Myanmar** | Asia | MM | MMR | L3 | L3 | Yes | 4. Base | | **Namibia** | Middle East & Africa | NA | NAM | L3 | L3 | | 4. Base | | **Nauru** | Asia | NR | NRU | L2 | L2 | Yes | 4. Base | | **Nepal** | Asia | NP | NPL | L3 | L3 | | 4. Base | | **Netherlands** | Western Europe | NL | NLD | L5+ | L4 | Yes | 2. Core | | **New Caledonia** | Pacific & Arctic | NC | NCL | L4- | L4 | Yes | 4. Base | | **New Zealand** | Pacific & Arctic | NZ | NZL | L5 | L4 | Yes | 2. Core | | **Nicaragua** | Central America & Caribbean | NI | NIC | L3 | L3 | Yes | 4. Base | | **Niger** | Middle East & Africa | NE | NER | L3 | L3 | | 4. Base | | **Nigeria** | Middle East & Africa | NG | NGA | L3 | L3 | | 4. Base | | **Niue** | Pacific & Arctic | NU | NIU | L2 | L2 | Yes | 4. Base | | **Norfolk Island** | Pacific & Arctic | NF | NFK | L4+ | L4 | | 4. Base | | **Northern Mariana Islands** | North America | MP | MNP | L3 | L3 | Yes | 4. Base | | **Norway** | Western Europe | NO | NOR | L4+ | L4 | Yes | 2. Core | | **Oman** | Middle East & Africa | OM | OMN | L3 | L3 | Yes | 4. Base | | **Pakistan** | Asia | PK | PAK | L2 | L2 | Yes | 4. Base | | **Palau** | North America | PW | PLW | L2 | L2 | Yes | 4. Base | | **Palestine, State of** | Middle East & Africa | PS | PSE | L2 | L2 | Yes | 4. Base | | **Panama** | Central America & Caribbean | PA | PAN | L3 | L3 | Yes | 4. Base | | **Papua New Guinea** | Pacific & Arctic | PG | PNG | L3- | L3 | Yes | 4. Base | | **Paraguay** | South America | PY | PRY | L3 | L3 | | 4. Base | | **Peru** | South America | PE | PER | L3 | L3 | Yes | 2. Core | | **Philippines** | Asia | PH | PHL | L3 | L3 | Yes | 3. Growth | | **Pitcairn** | Pacific & Arctic | PN | PCN | L2 | L2 | Yes | 4. Base | | **Poland** | Eastern Europe | PL | POL | L5+ | L4 | Yes | 2. Core | | **Portugal** | Western Europe | PT | PRT | L4+ | L4 | Yes | 2. Core | | **Puerto Rico** | North America | PR | PRI | L5+ | L4 | Yes | 4. Base | | **Qatar** | Middle East & Africa | QA | QAT | L4- | L4 | Yes | 4. Base | | **Republic of South Sudan** | Middle East & Africa | SS | SSD | L3- | L3 | Yes | 4. Base | | **Romania** | Eastern Europe | RO | ROU | L4 | L4 | Yes | 2. Core | | **Russian Federation** | Eastern Europe | RU | RUS | L4- | L4 | Yes | 4. Base | | **Rwanda** | Middle East & Africa | RW | RWA | L3 | L3 | Yes | 4. Base | | **Réunion** | Middle East & Africa | RE | REU | L4+ | L4 | Yes | 4. Base | | **Saint Barthélemy** | Central America & Caribbean | BL | BLM | L4+ | L4 | Yes | 4. Base | | **Saint Helena, Ascension and Tristan da Cunha** | Pacific & Arctic | SH | SHN | L3 | L3 | | 4. Base | | **Saint Kitts and Nevis** | Central America & Caribbean | KN | KNA | L3 | L3 | Yes | 4. Base | | **Saint Lucia** | Central America & Caribbean | LC | LCA | L3 | L3 | Yes | 4. Base | | **Saint Martin (French Part)** | Central America & Caribbean | MF | MAF | L4+ | L4 | | 4. Base | | **Saint Pierre and Miquelon** | North America | PM | SPM | L4+ | L4 | Yes | 4. Base | | **Saint Vincent and the Grenadines** | Central America & Caribbean | VC | VCT | L3 | L3 | Yes | 4. Base | | **Samoa** | Pacific & Arctic | WS | WSM | L2 | L2 | Yes | 4. Base | | **San Marino** | Western Europe | SM | SMR | L4+ | L4 | Yes | 4. Base | | **Sao Tome and Principe** | Middle East & Africa | ST | STP | L3 | L3 | Yes | 4. Base | | **Saudi Arabia** | Middle East & Africa | SA | SAU | L4+ | L4 | Yes | 3. Growth | | **Senegal** | Middle East & Africa | SN | SEN | L3 | L3 | Yes | 4. Base | | **Serbia** | Eastern Europe | RS | SRB | L4 | L4 | | 4. Base | | **Seychelles** | Middle East & Africa | SC | SYC | L3 | L3 | | 4. Base | | **Sierra Leone** | Middle East & Africa | SL | SLE | L3 | L3 | | 4. Base | | **Singapore** | Asia | SG | SGP | L4+ | L4 | Yes | 3. Growth | | **Sint Maarten** | Central America & Caribbean | SX | SXM | L3 | L3 | Yes | 4. Base | | **Slovakia** | Eastern Europe | SK | SVK | L4+ | L4 | Yes | 2. Core | | **Slovenia** | Eastern Europe | SI | SVN | L4 | L4 | Yes | 4. Base | | **Solomon Islands** | Pacific & Arctic | SB | SLB | L3 | L3 | Yes | 4. Base | | **Somalia** | Middle East & Africa | SO | SOM | L2 | L2 | Yes | 4. Base | | **South Africa** | Middle East & Africa | ZA | ZAF | L4- | L4 | Yes | 4. Base | | **South Georgia and the South Sandwich Islands** | South America | GS | SGS | L2 | L2 | Yes | 4. Base | | **Spain** | Western Europe | ES | ESP | L5 | L4 | Yes | 2. Core | | **Sri Lanka** | Asia | LK | LKA | L3 | L3 | Yes | 4. Base | | **Sudan** | Middle East & Africa | SD | SDN | L2 | L2 | Yes | 4. Base | | **Suriname** | South America | SR | SUR | L3 | L3 | Yes | 4. Base | | **Svalbard and Jan Mayen** | Western Europe | SJ | SJM | L4- | L4 | Yes | 4. Base | | **Sweden** | Western Europe | SE | SWE | L4+ | L4 | Yes | 2. Core | | **Switzerland** | Western Europe | CH | CHE | L4 | L4 | Yes | 2. Core | | **Syrian Arab Republic** | Middle East & Africa | SY | SYR | L2 | L2 | Yes | 4. Base | | **Taiwan, Province of China** | Asia | TW | TWN | L4 | L4 | Yes | 4. Base | | **Tajikistan** | Eastern Europe | TJ | TJK | L3- | L3 | Yes | 4. Base | | **Tanzania, United Republic of** | Middle East & Africa | TZ | TZA | L3- | L3 | | 4. Base | | **Thailand** | Asia | TH | THA | L4- | L4 | Yes | 3. Growth | | **Timor-Leste** | Asia | TL | TLS | L3 | L2 | Yes | 4. Base | | **Togo** | Middle East & Africa | TG | TGO | L3- | L3 | | 4. Base | | **Tokelau** | Pacific & Arctic | TK | TKL | L2 | L2 | Yes | 4. Base | | **Tonga** | Pacific & Arctic | TO | TON | L3 | L3 | Yes | 4. Base | | **Trinidad and Tobago** | Central America & Caribbean | TT | TTO | L3 | L3 | Yes | 4. Base | | **Tunisia** | Middle East & Africa | TN | TUN | L4- | L4 | Yes | 4. Base | | **Türkiye** | Eastern Europe | TR | TUR | L4+ | L4 | Yes | 2. Core | | **Turkmenistan** | Eastern Europe | TM | TKM | L3 | L3 | | 4. Base | | **Turks and Caicos Islands** | Central America & Caribbean | TC | TCA | L3- | L3 | | 4. Base | | **Tuvalu** | Pacific & Arctic | TV | TUV | L2 | L2 | Yes | 4. Base | | **Uganda** | Middle East & Africa | UG | UGA | L3 | L3 | | 4. Base | | **Ukraine** | Eastern Europe | UA | UKR | L4- | L4 | Yes | 4. Base | | **United Arab Emirates** | Middle East & Africa | AE | ARE | L4+ | L4 | Yes | 3. Growth | | **United Kingdom** | Western Europe | GB | GBR | L5+ | L4 | Yes | 1. Strategic | | **United States** | North America | US | USA | L5+ | L4 | Yes | 1. Strategic | | **United States Minor Outlying Islands** | North America | UM | UMI | L2 | L2 | Yes | 4. Base | | **Uruguay** | South America | UY | URY | L4- | L4 | Yes | 4. Base | | **Uzbekistan** | Eastern Europe | UZ | UZB | L3 | L3 | | 4. Base | | **Vanuatu** | Pacific & Arctic | VU | VUT | L3 | L3 | | 4. Base | | **Venezuela, Bolivarian Republic of** | South America | VE | VEN | L3 | L3 | Yes | 4. Base | | **Viet Nam** | Asia | VN | VNM | L4- | L4 | Yes | 4. Base | | **Virgin Islands, British** | Central America & Caribbean | VG | VGB | L3 | L3 | | 4. Base | | **Virgin Islands, U.S.** | North America | VI | VIR | L5+ | L4 | | 4. Base | | **Wallis and Futuna** | Pacific & Arctic | WF | WLF | L3 | L3 | Yes | 4. Base | | **Western Sahara** | Middle East & Africa | EH | ESH | L2 | L2 | Yes | 4. Base | | **Yemen** | Middle East & Africa | YE | YEM | L2 | L2 | Yes | 4. Base | | **Zambia** | Middle East & Africa | ZM | ZMB | L3 | L3 | | 4. Base | | **Zimbabwe** | Middle East & Africa | ZW | ZWE | L3 | L3 | | 4. Base | | **Åland Islands** | Western Europe | AX | ALA | L4+ | L4 | | 4. Base | ## Note on Russia *Following Russia’s invasion of Ukraine the availability of up to date Russian data ceased as data suppliers changed their risk appetite and stopped dealing with Russia. Until the situation improves GBG are unfortunately unable to reliably update current data relating to Russia.* Updated Sept 2026 # Loqate International Address Formats Source: https://docs.loqate.com/data-coverage/loqate-international-address-formats This page documents the latest Loqate international address format definitions for each country and territory, including the preferred line order, field composition, and native-script variants where available. To download this page as a **PDF**, use **Download PDF** from the dropdown menu next to the **Copy page** button at the top of this page. **Last Modified:** 24 February 2026 ## General Notes * Field values will only be populated where available and in accordance with local postal authority guidelines. * This file includes native script format where available, but more details on native scripts are available [here](/support/character-scripts/). * Country header format: Country Name ISO 3166-3, ISO 3166-2 ## Address Formats ### Afghanistan AFG, AF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Åland Islands ALA, AX | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Albania ALB, AL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode | | Line 9 | Locality | ### Algeria DZA, DZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### American Samoa ASM, AS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Andorra AND, AD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Angola AGO, AO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Anguilla AIA, AI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Antarctica ATA, AQ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Antigua and Barbuda ATG, AG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Argentina ARG, AR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise | | Line 4 | Building SubBuilding DoubleDependentLocality DependentLocality | | Line 5 | PostalCode Locality | ### Armenia ARM, AM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Aruba ABW, AW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Australia AUS, AU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | SubBuilding Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Austria AUT, AT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building/SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | PostalCode Locality | ### Azerbaijan AZE, AZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | | Line 9 | AdministrativeArea | ### Bahamas BHS, BS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea | ### Bahrain BHR, BH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Bangladesh BGD, BD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality – PostalCode | ### Barbados BRB, BB | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Belarus BLR, BY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise DependentThoroughfare Building SubBuilding | | Line 4 | DoubleDependentLocality | | Line 5 | PostalCode Locality | | Line 6 | | | Line 7 | DependentLocality | ### Belgium BEL, BE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Belize BLZ, BZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Benin BEN, BJ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Bermuda BMU, BM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Bhutan BTN, BT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Bolivia, Plurinational State of BOL, BO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Bonaire, Sint Eustatius and Saba BES, BQ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Bosnia and Herzegovina BIH, BA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Botswana BWA, BW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Bouvet Island BVT, BV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Brazil BRA, BR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality - AdministrativeArea | | Line 8 | PostalCode | ### British Indian Ocean Territory IOT, IO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Brunei Darussalam BRN, BN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Bulgaria BGR, BG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | ### Burkina Faso BFA, BF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Burundi BDI, BI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Cabo Verde, the Republic of CPV, CV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Cambodia KHM, KH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea PostalCode | ### Cameroon CMR, CM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Canada CAN, CA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Building | | Line 3 | Premise Thoroughfare SubBuilding | | Line 4 | PostBox Route DeliveryInstallation | | Line 5 | Locality AdministrativeArea PostalCode | ### Cayman Islands CYM, KY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Central African Republic CAF, CF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Chad TCD, TD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Chile CHL, CL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | PostalCodePrimary Locality DependentLocality | | Line 8 | AdministrativeArea | ### China CHN, CN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise DependentThoroughfare Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | PostalCode | ### China CHN, CN (Native) | Line | Value | | - | - | | Line 1 | PostalCode | | Line 2 | AdministrativeArea Locality DependentLocality DoubleDependentLocality Thoroughfare DependentThoroughfare Premise SubBuilding PostBox Organization | ### Christmas Island CXR, CX | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Cocos (Keeling) Islands CCK, CC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Colombia COL, CO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | | Line 9 | AdministrativeArea | ### Comoros COM, KM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Congo COG, CG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Congo, the Democratic Republic of the COD, CD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Cook Islands COK, CK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | ### Costa Rica CRI, CR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | AdministrativeArea Locality | | Line 9 | PostalCode | ### Côte d’Ivoire CIV, CI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Croatia HRV, HR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Cuba CUB, CU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise DependentThoroughfare Building SubBuilding | | Line 4 | DoubleDependentLocality | | Line 5 | DependentLocality | | Line 6 | PostalCode Locality AdministrativeArea | ### Curaçao CUW, CW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Cyprus CYP, CY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Czechia CZE, CZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Denmark DNK, DK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuildingFloor SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Djibouti DJI, DJ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Dominica DMA, DM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Dominican Republic DOM, DO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Ecuador ECU, EC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Building SubBuilding | | Line 3 | Thoroughfare Premise DependentThoroughfare | | Line 4 | DependentLocality | | Line 5 | PostalCode Locality | ### Egypt EGY, EG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | AdministrativeArea | | Line 9 | PostalCode | ### El Salvador SLV, SV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | | Line 9 | AdministrativeArea | ### Equatorial Guinea GNQ, GQ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Eritrea ERI, ER | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Estonia EST, EE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Eswatini SWZ, SZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Ethiopia ETH, ET | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Falkland Islands (Malvinas) FLK, FK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Faroe Islands FRO, FO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Fiji FJI, FJ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Finland FIN, FI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | | | Line 7 | PostalCode Locality | ### France FRA, FR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | SubBuilding Building | | Line 3 | Premise Thoroughfare | | Line 4 | DependentThoroughfare | | Line 5 | PostBox Town | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality LocalityExtra LocalityExtra\_Others | ### French Guiana GUF, GF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### French Polynesia PYF, PF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### French Southern Territories ATF, TF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Gabon GAB, GA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Gambia GMB, GM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Georgia GEO, GE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Germany DEU, DE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Thoroughfare Premise | | Line 3 | Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | PostalCode Locality | ### Ghana GHA, GH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Gibraltar GIB, GI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Greece GRC, GR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare PremiseExtra Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Greenland GRL, GL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Grenada GRD, GD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Guadeloupe GLP, GP | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Guam GUM, GU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Guatemala GTM, GT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Guernsey GGY, GG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding SubBuildingFloor Building | | Line 4 | Premise Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | PostalCode | ### Guinea GIN, GN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Guinea-Bissau GNB, GW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Guyana GUY, GY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Haiti HTI, HT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Heard Island and McDonald Islands HMD, HM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Holy See (Vatican City State) VAT, VA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Honduras HND, HN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Hong Kong HKG, HK | Line | Value | | - | - | | Line 1 | Attention Organization | | Line 2 | PostBox | | Line 3 | SubBuilding BuildingPhase | | Line 4 | Building BuildingPhaseExtra | | Line 5 | Premise Thoroughfare | | Line 6 | DependentThoroughfare | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | ### Hungary HUN, HU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Locality | | Line 3 | DependentLocality | | Line 4 | DeliveryAddress | ### Iceland ISL, IS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | ### India IND, IN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Indonesia IDN, ID | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Iran, Islamic Republic of IRN, IR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Iraq IRQ, IQ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Ireland IRL, IE | Line | Value | | - | - | | Line 1 | PostBox | | Line 2 | Department | | Line 3 | Organization | | Line 4 | SubBuilding Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | Locality | | Line 7 | DependentLocality | | Line 8 | DoubleDependentLocality | | Line 9 | PostTown | | Line 10 | AdministrativeArea | | Line 11 | PostalCode | ### Isle of Man IMN, IM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding SubBuildingFloor Building | | Line 4 | Premise Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | PostalCode | ### Israel ISR, IL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Italy ITA, IT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode SubAdministrativeArea AdministrativeArea | ### Jamaica JAM, JM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | AdministrativeArea | ### Japan JPN, JP | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Japan JPN, JP (Native) | Line | Value | | - | - | | Line 1 | 〒 PostalCode | | Line 2 | AdministrativeArea Locality DependentLocality DoubleDependentLocality Thoroughfare DependentThoroughfare Premise Building SubBuilding PostBox Organization | ### Jersey JEY, JE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding SubBuildingFloor Building | | Line 4 | Premise Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | PostalCode | ### Jordan JOR, JO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Kazakhstan KAZ, KZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | | Line 8 | SubAdministrativeArea | | Line 9 | AdministrativeArea | ### Kazakhstan KAZ, KZ (Native) | Line | Value | | - | - | | Line 1 | AdministrativeArea | | Line 2 | SubAdministrativeArea | | Line 3 | PostalCode Locality | | Line 4 | DependentLocality | | Line 5 | DoubleDependentLocality | | Line 6 | PostBox | | Line 7 | Thoroughfare Premise Building SubBuilding | | Line 8 | DependentThoroughfare | | Line 9 | Organization | ### Kenya KEN, KE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | | Line 10 | AdministrativeArea | ### Kiribati KIR, KI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | ### Korea, Democratic People’s Republic of PRK, KP | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Korea, Republic of KOR, KR | Line | Value | | - | - | | Line 1 | OrganizationPostBox | | Line 2 | BuildingNumber SubBuilding BuildingName | | Line 3 | PremiseNumber Thoroughfare | | Line 4 | DependentLocality | | Line 5 | Locality | | Line 6 | AdministrativeArea PostalCode | ### Korea, Republic of KOR, KR (Native) | Line | Value | | - | - | | Line 1 | PostalCode AdministrativeArea | | Line 2 | Locality DependentLocality Thoroughfare PremiseNumber BuildingName BuildingNumber SubBuilding PostBox | | Line 3 | Organization | ### Kosovo XKX, XK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Kuwait KWT, KW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Kyrgyzstan KGZ, KG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostalCode Locality | | Line 3 | PostBox | | Line 4 | Building SubBuilding | | Line 5 | Thoroughfare Premise | | Line 6 | DependentThoroughfare | | Line 7 | DoubleDependentLocality | | Line 8 | DependentLocality | ### Lao People’s Democratic Republic LAO, LA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Latvia LVA, LV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Lebanon LBN, LB | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Lesotho LSO, LS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Liberia LBR, LR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Libya LBY, LY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Liechtenstein LIE, LI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Lithuania LTU, LT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | LT-PostalCode SubAdministrativeArea | ### Luxembourg LUX, LU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | L-PostalCode Locality | ### Macao MAC, MO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise | | Line 4 | DependentThoroughfare | | Line 5 | Building | | Line 6 | SubBuilding | | Line 7 | DoubleDependentLocality | | Line 8 | DependentLocality | | Line 9 | Locality | ### Madagascar MDG, MG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Malawi MWI, MW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Malaysia MYS, MY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | | Line 9 | AdministrativeArea | ### Maldives MDV, MV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Mali MLI, ML | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Malta MLT, MT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | Locality | | Line 7 | PostalCode | ### Marshall Islands MHL, MH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Martinique MTQ, MQ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Mauritania MRT, MR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Mauritius MUS, MU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Mayotte MYT, YT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Mexico MEX, MX | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise DependentThoroughfare Building SubBuilding | | Line 4 | DoubleDependentLocality | | Line 5 | DependentLocality | | Line 6 | PostalCode SubAdministrativeArea AdministrativeArea | ### Micronesia, Federated States of FSM, FM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | Locality AdministrativeArea PostalCode | ### Moldova, Republic of MDA, MD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Monaco MCO, MC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | PostalCode Locality AdministrativeArea | ### Mongolia MNG, MN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Montenegro MNE, ME | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Montserrat MSR, MS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Morocco MAR, MA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Mozambique MOZ, MZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Myanmar MMR, MM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Namibia NAM, NA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Nauru NRU, NR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Nepal NPL, NP | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Netherlands NLD, NL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### New Caledonia NCL, NC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality LocalityExtra AdministrativeArea | ### New Zealand NZL, NZ | Line | Value | | - | - | | Line 1 | Department | | Line 2 | Organization | | Line 3 | SubBuilding | | Line 4 | Building | | Line 5 | Thoroughfare | | Line 6 | DependentThoroughfare | | Line 7 | DoubleDependentLocality | | Line 8 | DependentLocality | | Line 9 | Locality PostalCode | ### Nicaragua NIC, NI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode | | Line 9 | Locality AdministrativeArea | ### Niger NER, NE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Nigeria NGA, NG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Niue NIU, NU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Norfolk Island NFK, NF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### North Macedonia MKD, MK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Northern Mariana Islands MNP, MP | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Norway NOR, NO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Oman OMN, OM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode | | Line 9 | Locality | | Line 10 | AdministrativeArea | ### Pakistan PAK, PK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Palau PLW, PW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Palestine, State of PSE, PS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Panama PAN, PA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | | Line 9 | AdministrativeArea | ### Papua New Guinea PNG, PG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | | Line 9 | AdministrativeArea | ### Paraguay PRY, PY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Peru PER, PE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise | | Line 4 | DependentThoroughfare | | Line 5 | Building SubBuilding | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | | Line 10 | AdministrativeArea | ### Philippines PHL, PH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode AdministrativeArea | ### Pitcairn PCN, PN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Poland POL, PL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | PostalCode Locality | ### Portugal PRT, PT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode SubAdministrativeArea | ### Puerto Rico PRI, PR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | DependentLocality | | Line 3 | PostBox | | Line 4 | Building | | Line 5 | Premise Thoroughfare SubBuilding SubBuildingFloor | | Line 6 | DependentThoroughfare | | Line 7 | DoubleDependentLocality | | Line 8 | Locality PostalCode | ### Qatar QAT, QA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Republic of South Sudan SSD, SS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode | | Line 9 | Locality | ### Réunion REU, RE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality LocalityExtra | ### Romania ROU, RO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise Building SubBuilding | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | ### Russian Federation RUS, RU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | | Line 10 | PostalCode | ### Rwanda RWA, RW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Saint Barthélemy BLM, BL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | SubBuilding Building | | Line 3 | Premise Thoroughfare | | Line 4 | DependentThoroughfare | | Line 5 | PostBox | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Saint Helena, Ascension and Tristan da Cunha SHN, SH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | | Line 10 | PostalCode | ### Saint Kitts and Nevis KNA, KN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Saint Lucia LCA, LC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Saint Martin (French part) MAF, MF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Saint Pierre and Miquelon SPM, PM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Saint Vincent and the Grenadines VCT, VC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Samoa WSM, WS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### San Marino SMR, SM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Sao Tome and Principe STP, ST | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Saudi Arabia SAU, SA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | ShortAddressCode | | Line 3 | PostBox | | Line 4 | PremiseExtra Premise Thoroughfare | | Line 5 | SubBuilding Building | | Line 6 | SecondaryNumber DependentLocality | | Line 7 | PostalCode | | Line 8 | Locality | ### Senegal SEN, SN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality AdministrativeArea | ### Serbia SRB, RS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Seychelles SYC, SC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Sierra Leone SLE, SL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Singapore SGP, SG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Premise Thoroughfare | | Line 4 | Building BuildingPhase | | Line 5 | DependentThoroughfare | | Line 6 | Locality PostalCode | ### Sint Maarten (Dutch part) SXM, SX | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea | ### Slovakia SVK, SK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Slovenia SVN, SI | Line | Value | | - | - | | Line 1 | Building SubBuilding Organization | | Line 2 | PostBox | | Line 3 | Thoroughfare Premise | | Line 4 | DependentThoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | ### Solomon Islands SLB, SB | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | ### Somalia SOM, SO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### South Africa ZAF, ZA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### South Georgia and the South Sandwich Islands SGS, GS | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Spain ESP, ES | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Thoroughfare Premise Building SubBuildingType SubBuildingBlock BuildingStaircase SubBuildingFloor SubBuildingDoor | | Line 3 | DependentThoroughfare | | Line 4 | PostBox | | Line 5 | DependentLocality | | Line 6 | PostalCode Locality | | Line 7 | AdministrativeArea | ### Sri Lanka LKA, LK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### Sudan SDN, SD | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode | | Line 9 | Locality | ### Suriname SUR, SR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Svalbard and Jan Mayen SJM, SJ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Sweden SWE, SE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | PostalCode Locality | ### Switzerland CHE, CH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | SubBuilding Building | | Line 3 | Thoroughfare Premise | | Line 4 | DependentThoroughfare | | Line 5 | PostBox | | Line 6 | Locality AdministrativeArea | ### Syrian Arab Republic SYR, SY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Taiwan, Province of China TWN, TW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise DependentThoroughfare Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | PostalCode Locality | ### Taiwan, Province of China TWN, TW (Native) | Line | Value | | - | - | | Line 1 | PostalCode | | Line 2 | AdministrativeArea Locality DependentLocality DoubleDependentLocality Thoroughfare DependentThoroughfare Premise SubBuilding PostBox Organization | ### Tajikistan TJK, TJ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Tanzania, United Republic of TZA, TZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Thailand THA, TH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise DependentThoroughfare Thoroughfare | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality | | Line 8 | AdministrativeArea | | Line 9 | PostalCode | ### Timor-Leste TLS, TL | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Togo TGO, TG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Tokelau TKL, TK | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Tonga TON, TO | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea | ### Trinidad and Tobago TTO, TT | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Tunisia TUN, TN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Türkiye TUR, TR | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | DoubleDependentLocality | | Line 3 | Thoroughfare Building NoPremise | | Line 4 | PostBox | | Line 5 | PostalCode SubAdministrativeArea AdministrativeArea | ### Turkmenistan TKM, TM | Line | Value | | - | - | | Line 1 | OrganizationPostalCode Locality | | Line 2 | AdministrativeArea | | Line 3 | DeliveryAddress | ### Turks and Caicos Islands TCA, TC | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | AdministrativeArea | ### Tuvalu TUV, TV | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Uganda UGA, UG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Ukraine UKR, UA | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building | | Line 4 | Thoroughfare Premise SubBuilding | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality Locality | | Line 8 | AdministrativeArea | | Line 9 | PostalCode | ### United Arab Emirates ARE, AE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### United Kingdom GBR, GB | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Department | | Line 3 | PostBox | | Line 4 | SubBuilding Building | | Line 5 | Premise Thoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | | Line 9 | PostalCode | ### United States USA, US | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | Building | | Line 3 | Premise Thoroughfare SubBuilding | | Line 4 | DependentThoroughfare PostBox | | Line 5 | DoubleDependentLocality | | Line 6 | DependentLocality | | Line 7 | Locality AdministrativeArea PostalCode | ### United States Minor Outlying Islands UMI, UM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Uruguay URY, UY | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Uzbekistan UZB, UZ | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Vanuatu VUT, VU | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Venezuela, Bolivarian Republic of VEN, VE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality PostalCode | ### Viet Nam VNM, VN | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality DependentLocality | | Line 7 | Locality SubAdministrativeArea | | Line 8 | AdministrativeArea PostalCode | ### Virgin Islands, British VGB, VG | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Virgin Islands, U.S. VIR, VI | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality AdministrativeArea PostalCode | ### Wallis and Futuna WLF, WF | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | Building SubBuilding | | Line 4 | Thoroughfare Premise | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Western Sahara ESH, EH | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Yemen YEM, YE | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | ### Zambia ZMB, ZM | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | PostalCode Locality | ### Zimbabwe ZWE, ZW | Line | Value | | - | - | | Line 1 | Organization | | Line 2 | PostBox | | Line 3 | SubBuilding Building | | Line 4 | Premise Thoroughfare | | Line 5 | DependentThoroughfare | | Line 6 | DoubleDependentLocality | | Line 7 | DependentLocality | | Line 8 | Locality | # On-Premise Documentation Source: https://docs.loqate.com/documentation/introduction ## Available Processes > [card] [Parse](/available-processes/parse-process) > [card] [Match](/available-processes/match-process/) > [card] [Format](/available-processes/format-process/) > [card] [Verify](/available-processes/verify-process/) > [card] [Search](/available-processes/search-process/) > [card] [View All Available Processes](/available-processes/introduction/) ## Field Descriptions > [card] [Address Fields](/field-descriptions/addfields/) > [card] [Geocode Fields](/field-descriptions/geocode-fields/) > [card] [Unmatched Field](/field-descriptions/unmatched-field/) > [card] [CASS Fields](/support/cass2-output-field-descriptions/) > [card] [SERP Fields](/field-descriptions/serp-fields) > [card] [AMAS Fields](/field-descriptions/amas-fields/) ## Status Options > [card] [fieldStatus](/report-codes/fieldstatus) > [card] [processStatus](/field-descriptions/processstatus) > [card] [serverStatus](/field-descriptions/serverStatus/) ## Server Options > [card] [Server Options](/documentation/server-options/) ## Installed API Reference > [card] [C++/Java/.Net Functional Reference](/support/installed-api/) # Server Options Source: https://docs.loqate.com/documentation/server-options ## Server Options The following commands can be used to control and manipulate the Loqate process or output. These are considered advanced functions, and we recommend that server options are used in custom workflows. **CASS2 related server options added to the bottom of this list.** | Server Option | Description | | :- | - | | AddressLineSeparator | Used to specify the string which will separate the output address lines within the output Address field (default `
`). | | AutocompleteIndexOnly | This option allows the user to specify whether the search process should use Powersearch auto-complete index ONLY. The default is `OFF`. The option should be set to 0 or `OFF` to allow search tool to also use the parser and match tool when the auto-complete index cannot find any results. The option should be set to 1 or `ON` to allow the search tool to use the Powersearch auto-complete index files. This can also be used as a process option. | | CasingIgnoreFields | Used to specify the fields that should be ignored by the OutputCasing option. System default is "ID,PostalCode,PostalCodePrimary,PostalCodeSecondary,ISO3166-2,ISO3166-3,PostBox,PostBoxNumber,PostBoxType,\_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC,AQI,HyphenClass,MatchedFieldList,DPS,CountryCode,Outputstatus,FormattedAddress". Additionally, the following datasets also add AdministrativeArea to the default values: AUS, BRA, CAN, ITA, MEX, CHE, and USA. Currently system defaults cannot be overridden, but country-level values will be ignored when CasingIgnoreFields is used. Please re-use "AdministrativeArea" as a value to retain the default behavior. | | CassCompanyName | This option is set within the `loqate.ini` file. This will allow the Loqate engine to print the Company Name value in the CASS and PS3553 reports. Please note, if a value has not been specified, then the default value will be `LOQATE`. | | CassSoftwareName | This option is set within the `loqate.ini` file. This will allow the Loqate engine to print the CASS software name value in the CASS and PS3553 reports. Please note, if a value has not been specified, then the default value will be `LOQATE ENGINE`. | | CassSoftwareVersion | This option is set within the `loqate.ini` file. This will allow the Loqate engine to print the CASS software version in the CASS and PS3553 reports. Please note, if a value has not been specified, then the default value will be `20.13.04.N`. | | CertifiedCountryList | Used to specify a comma-delimited list of countries where data should be processed using the relevant certified process. e.g. "USA,CAN,AUS" to give CASS, SERP, and AMAS certified output respectively. | | CombinedSearchMethods | Specifies whether or not to use a word-based search algorithm similar to a web search engine approach. Default `Yes`. | | CombinedVerifyMethods | If this option is set to YES or `ON` or `TRUE` or 1, the word-based search algorithm similar to a web search engine approach will be enabled during verification process. Default `Yes`. | | ConfidenceThreshold | Used to specify the threshold at which to stop returning parse interpretations, as a percentage of the confidence of the top result. Default `90`. | | ConfigurationFilename | Used to specify the name of the file that will attempt to be opened during the call to `lqtServer::init`. Default `loqate.ini`. | | ConformToReference | Controls whether the output address fields should strictly conform to the values stored in the reference data. This option is particularly relevant when verifying **Premise** and **SubBuilding** fields. Options are “Yes” and “No” with the default being “No”. For example, given reference data: 14 Main St Ste 1 Input: 14A Main St Ste 1A Output with default **No**: 14A Main St Ste 1A Output with **Yes**: 14 Main St Ste 1 | | ContextResultCacheSize | Used to specify how many sets of context results should be cached in memory. This cache is a cost-based cache based on processing time, meaning that the slowest context analyses have their results cached. Default `0`. Values up to around 5,000 are relevant, but the memory usage and performance gain will be dependent on the supplied input data. | | ContextCountryCacheSize | Used to specify the number of MRU countries to generate ContextResult caches for. On an unsorted multi-country file a value of around 10 may be relevant, but the memory usage and performance gain will be dependent on the supplied input data. | | CountryFields | Used to specify the comma delimited list of fields to be searched for country information. This should be a subset of the ParseFields entry. | | CustomFields | Used to specify the comma delimited list of custom fields to be searched for during the parse process. | | CustomFieldConfidence | Used to specify the confidence to be applied to the recognition of any fields recognized through the CustomFields option. | | DataDirectory | Used to specify the directory in which to find the Global Knowledge Repository, if other than the directory of the `loqate.ini` configuration file specified during the `lqtServer::init` call. | | DefaultCountry | Used to specify the ISO 3166-1 alpha-3 code which should be used if no identifiable country can be found in an input record. | | DuplicateHandlingMask | Used to specify the duplicate handling level, between 0 and 15. Default is `0`. When option is set, duplicate components in the input address are removed if it meets a certain criteria. For more details, please click this [link](/support/duplicatehandlingmask-option). | | EnhancedCountryTool | This option allows users to enable the Automatic Country Identification. To enable the option, set the value of the option to "`ON`" or "`True`". To disable the option set the value to "`OFF`" or "`False`". Default `False`. | | FieldNameWeight | Used to specify the default field name weight, between 1 and 255. Default `10`. A larger value will give more precedence to the supplied field name, a smaller value will give more precedence to the GKR matches. Individual field name weights can also be declared using the syntax. For instance 'Organization=240,AdministrativeArea=100,50' would mean a field name weight of 240 for the Organization field, 100 for the AdministrativeArea field, and a default of 50 for all remaining fields. **This option is only used during the initial Parse process, and not during the Match process.** | | FieldStatus | This option produces a status code for every returned field. Default is "false"; to see this value, set the option to "true". Examples include Verified, Identified, or Added. Statuses are defined [here](/report-codes/fieldstatus). | | FlexiconCountryList | This option allows the user to specify a comma separated list of ISO 3166-1 alpha-3 country codes for which phonetic lexicons is enabled for parsing. Default value is empty which means that the phonetic lexicons are not enabled for any country by default. | | ForceCountry | Used to specify the ISO 3166-1 alpha-3 code which should be used for all input records. | | FormatFields | A list of default field formats for those fields that can be derived from a combination of other fields. This can be overridden on a per-country basis, and should only be changed if requested by Support staff. | | GeocodeCountryList | Used to specify a comma-delimited list of ISO 3166-1 alpha-3 codes of acceptable countries to geocode. Input records from other countries will not return geocodes. The default is to process data from all countries. | | GeocodeMatchRules | A list of default match rules specifying how fields can be combined when attempting to generate a geocode match. This can be overridden on a per-country basis, and should only be changed if requested by Support staff. | | IgnoreUnmatched | Allow unmatched input data within the address lines to be ignored during a Search process, meaning that a search can proceed matching only partial input data. Default `No`. We don't recommend you use this server option on a Verify process, as it may reduce the accuracy of otherwise valid results. | | LogFileName | Used to specify a filename for debug output. Must be specified before the `lqtServer::init` call. | | MatchScoreAbsoluteThreshold | Used to specify the minimum matchscore a record must reach in the Match process to be taken into account as a candidate for matching. Default value is `60` and the maximum value is 100. | | MatchScoreThresholdFactor | This is a value that is used as a factor of the highest matching result. The resulting value is then used as a cut-off for considering candidates for the results. The higher the value of the factor, the higher the chance of getting a good verification result. Default value is `95` and the maximum value is 100. | | MaximumGeoDistance | Used to specify the maximum GeoDistance a geocode can reach and still be returned as a result. Default is -1 (no limit). | | MaximumInstanceCount | Used to specify the maximum number of lqtServer instances to allow to run concurrently. Default is -1 (no limit). If using the single threaded library it is recommended to set this to 1 to ensure that no attempt to open multiple lqtServer instances can occur. | | MaxResults | Used to specify the maximum number of results to return in the ProcessResults structure. | | MinimumGeoAccuracyLevel | Used to specify the minimum GeoAccuracy level a geocode must reach in order to be returned as a result. Default is `0` (zero), valid values are 0-5. | | MinimumMatchscore | Used to specify the minimum matchscore a record must reach in order to avoid reversion. Default is `0` (zero), valid values are 0-100. | | MinimumPostcode | Used to specify the minimum postcode status a record must reach in order to avoid reversion. Default is `0` (zero), valid values are 0-8. | | MinimumSimilarity | Used to specify the minimum similarity score that is needed to make a match to a candidate result. Default value is `70`. | | MinimumVerificationLevel | Used to specify the minimum verification level a record must reach in order to avoid reversion. Default is `0` (zero), valid values are 0-5. | | NativeAddressLineReverse | Used to specify whether to reverse the order of the input address lines when processing non-Latin data. Usually this is set on a per-country basis automatically, but can be overridden by setting the server option as appropriate. When set to `False`, any input Address lines are concatenated for parsing in normal order (e.g. Address1 + Address2 + Address3), when set to `True` any input Address lines are concatenated for parsing in reverse order (e.g. Address3 + Address2 + Address1). | | NewSearchPrefered | If this option is set to `TRUE` or `ON`, New Search is executed before the Old Search during execution of the Search Process. Typically if the input is nearly complete, New Search is preferred to complete the search and the option should be set to `TRUE` or `ON`. If the input is quite partial and is not nearly a complete address, Old Search is preferred and the option should be set to `FALSE` or `OFF`. Default option is `FALSE` or `OFF`. | | OutputAddressFormat | Used to specify whether to output an extra field for the Address block fields with the suffix 'Format' showing how the hierarchical field positioning has occurred. Valid options are '`Yes`' or '`No`', default '`No`'. | | OutputCasing | Used to specify the letter case to use for output fields. Valid options are 'Upper', 'Title', or 'Lower'. The default will be Default: 'Title'; unless the postal authority prefer a different case. For example, the postal authority in Spain prefer to have the Locality formatted in upper case. | | OutputScript | Used to specify the language or character set (based on the ISO 15924 standard) in which the output should be encoded, from the following list of possible values: - Latn - Latin (English transliteration wherever possible) - Cyrl - Cyrillic (Russia) - Grek - Greek (Greece) - Hebr - Hebrew (Israel) - Hani - Kanji (Japan) - Hans - Simplified Chinese (China) - Arab - Arabic (United Arab Emirates) - Thai - Thai (Thailand) - Hang - Hangul (South Korea) - Native - Output in the native script wherever possible | | OutputSortType | Used to specify the order in which the Search output results should be sorted. To sort in alphabetical order use 'Alphabetical', or alternatively specify 'AVC' to sort from the highest verification level to the lowest verification level. The option can also be set to 'Similarity' giving an indication of the percentage of the input characters that have been matched in the output. Default 'AVC'. | | ParseFields | Specifies the list of fields to be parsed into word tokens. | | PreferPrimaryValidAlias | When option is set to "Yes", the engine will pick out the first valid alias it finds within the reference data. Default value is "No". | | QueryResultCacheSize | Used to specify how many sets of query results should be cached in memory. This cache is a cost-based cache based on query time, meaning that the slowest queries have their results cached. Default `0`. Values up to around 5,000 are relevant, but the memory usage and performance gain will be dependent on the supplied input data. | | RangeDecompose | Used to specify how to expand ranges such as premise numbers and sub building numbers. Valid values are 'Match' (returning only the value matching the input query), 'Range' (returning a human-readable range, e.g. '1-9 Odd'), or 'Full' (expanding out the range into its constituent numbers, e.g. '1', '2', '3', '4', '5'). | | ReferenceDatasetCacheSize | Used to specify the number of MRU reference datasets to cache. Default value is `5`. | | ReferencePageCacheSize | Used to specify the number of MRU pages to cache from each individual reference dataset. Default value is `12`, each page equates to approximately 5Mb of memory use. | | ReturnDataType | Valid values are Complete (default) or Verified. If set to Verified, the output from a Search process will only include data that has been verified against the available reference data. | | ReturnVerifiedFieldsOnly | This option will return only verified fields, meaning that it will remove anything that isn't verified from any field. SuppressUnmatched option will only suppress the unverified components in the Address field. Default `No`, meaning all fields will be returned. This can be specified on a per-country basis, with the added ability to specify fields to ignore during the check, using the following syntax. `ReturnVerifiedFieldsOnly=[:;;…;][,:;…;,…,]. e.g. ReturnVerifiedFieldsOnly=BE:SubBuilding;Premise,DE:SubBuilding;Premise,AT:SubBuilding;Premise or ReturnVerifiedFieldsOnly=US,CA,GB.` The former will return verified fields only in Belgium, Germany, and Austria, but will retain non-verified data in the Premise and SubBuilding fields, the latter will return verified fields only in USA, Canada, UK. | | SearchAutocompleteIndexCheck | Specifies whether or not to use the 'autocomplete index' algorithm integral to Address Powersearch (this will not function if Address Powersearch is not installed). This algorithm returns a list of suggestions in record time for entries like '4916 eas' in the US. For more information on Address Powersearch, please visit. Related to this option is the AutocompleteIndexOnly option which will prevent other algorithms from being called. Because the autocomplete index algorithm is much faster than the other algorithms, this guarantees a faster response time in all situations. Default `Yes`. | | SearchLikeFieldCheck | Specifies whether or not to use the 'like field' algorithm. This option looks for an exact field match in the address field which is useful for single items like postcodes, building names, organization names, etc. Default `Yes`. | | SearchMatchRules | A list of default match rules specifying how fields can be combined when attempting to generate a search. This can be overridden on a per-country basis, and should only be changed if requested by Support staff. | | SearchReferenceTypes | Specifies the list of lexicon tagged field types that should be searched for in the reference data during a parse process. This should only be changed if requested by Support staff. | | SimpleParse | Specifies whether or not to use the 'simple parse' algorithm. This option looks for something like premise + street in the address field, but is not particularly tolerant of invalid input data. Default `Yes`. | | StrictReferenceMatch | This option helps to output results that are identical to what is found within the reference data. For example, if an input address has a premise of "08", but the reference data contains "8", the Premise would be verified with an Premise Number output of "08". Turning on StrictReferenceMatch would have the output be "8". Default `No`. | | StrictRefMatchCountryList | This is a list of ISO2 countries that you would like to have the option StrictReferenceMatch turned on for. | | SuppressAdditionFields | Used to specify the comma-delimited list of fields that should not be added to an output result if they do not appear in the input record. | | SuppressAddressFields | Used to specify the comma-delimited list of fields that should be suppressed from the Address field output. | | SuppressFields | Used to specify the comma-delimited list of fields that should be suppressed from the output. | | SuppressMatchFields | Used to specify the comma-delimited list of fields that should be suppressed when determining the Address Verification Code. | | SuppressUnmatched | If this option is set to `TRUE` or `ON`, unverified fields will not be output in Address fields (Address, Address1, Address2, etc.). Default option is `FALSE` or `OFF`. | | TextFields | Specifies the list of field names, and the order in which they should be combined, to generate the combined word list for parsing. This should be a subset of the ParseFields entry. | | TransliterationIgnoreFields | Used to specify the fields that should not be transliterated. Default "ID,ISO3166-2,ISO3166-3,\_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC". | | ToolInfo | Specify `Yes` to output extra debug information viewable using the getFieldInfo method. | | UseCustomLexicons | Specify `Yes` to force the API to search for custom lexicons (lx\_\_c.lfs files) | | UseSymbolicTransliteration | Specify `No` to limit transliteration to complete field phrase matches. Default `Yes`. | | VerifyCountryList | Used to specify a comma-delimited list of ISO 3166-1 alpha-3 codes of acceptable countries to process. Input records from other countries will return the unprocessed Address Verification Code `U00-U00-P0-000`. The default is to process data from all countries. | | VerifyMatchRules | A list of default match rules specifying how fields can be combined when attempting to generate a verification match. This can be overridden on a per-country basis, and should only be changed if requested by Support staff. | ## Process Options | Server Option | Description | | - | - | | LogInput | Record the process input data to the specified debug log file. | | LogOutput | Record the process output data to the specified debug log file. | ## CASS2 Related Server Options | Server Option | Description | | - | - | | **CassAvcEnable** | `Yes`/`No` (Default: `No`). The default will Z00-00-00-000 (AVC) and Z (AQI), but computing the report values can be forced. Please note that if returned, these fields may not accurately reflect the changes made in the record during the CASS process. | | **CassUrbFirst** | `Yes`/`No` (Default: `No`). This specifies the Urbanization location on the address lines output (Puerto Rico only). The default will put the value after the address lines(s) with premise, thoroughfare, and sub-building. | | **CassZipFields** | `Yes`/`No` (Default: `No`). Populate "Finance" and "AutoZoneIndicator". If these fields are desired, customers will experience a moderate performance degradation (up to 20%). | | **CassCityAbbreviation** | `Yes`/`No` (Default: `No`). If a Locality name is longer than 13 characters, this option can be used to return the official, short version. Both short and long versions are valid according to CASS. | | **CassFalsePosDir** | `path_to_use` Allows you to control the directory where the `False` Positive file is created. For example: CassFalsePosDir='C:temp' or CassFalsePosDir='/opt/temp'. | | **CassUseUSPSPreferredCity** | `Yes`/`No` (Default: `No`). Setting this to `Yes` will return the USPS preferred city name. This server option only applies to on-premises installations. The default behaviour is for this option to be applied at the session level and will apply to all addresses. Use the CassMultiThreadedSettings to turn this server option on and off for individual addresses. | | **CassPreserveAlias** | `Yes`/`No` (Default: `No`). By default, Verify will convert a thoroughfare alias (as recognised by USPS data) provided in an input address into the official USPS-approved thoroughfare name. Choose ‘Yes’ to preserve the alias and prevent it from being converted. This server option only applies to on-premises installations. The default behaviour is for this option to be applied at the session level and will apply to all addresses. Use the CassMultiThreadedSettings to turn this server option on and off for individual addresses. | | **CassMultiThreadedSettings** | `Yes`/`No` (Default: `No`). Setting this to ‘Yes’ will enable CassUseUSPSPreferredCity and CassPreserveAlias server options to be applied for individual addresses. | ## SERP Related Server Options | Server Option | Description | | - | - | | **SerpWesternStyle** | `Yes`/`No` (Default: `No`). When `Yes`, the output Address/Delivery address lines will have the SubBuilding first, followed by a hyphen, the Premise, and remainder of the address. For example: Input: APT 200 – 6200 MCKAY AVE, BURNABY BC V5H 4L7 CAN. Output: Option '`No`' or blank: 6200 MCKAY AVE APT 200, BURNABY BC V5H 4L7. Option '`Yes`': 200-6200 MCKAY AVE, BURNABY BC V5H 4L7. This option only impacts addresses that are SerpStatusEx of 'V' (valid) or 'C' (correctable) | # Address Fields Source: https://docs.loqate.com/field-descriptions/addfields Loqate's address structure is based on the OASIS Extensible Address Language (xAL) version 2.0, adapted to suit a flattened record structure. Some countries have more complex addressing structures than others. As such, the use of individual fields will vary based on the input country and the available reference data. The following fields are recognized, `[in]` designates a field that can be used on input, `[out]` designates a field that may be present on output, and `[in,out]` designates that a field can be used for both input and output. Please Note that the `AdministrativeArea` should be the full name or the postal authority accepted code. For example, `New York` or `NY` in the US, and `VALLE DEL CAUCA` in Colombia (there is no postal abbreviation). ISO-3166 administrative area codes (e.g. `CO-VAC` for `VALLE DEL CAUCA` in Colombia) are not recognized on input and should not be used but can be returned in our output via our enhanced [ISO-3166 dataset](/field-descriptions/data-enhancement/data-enhancement-administrativearea-iso-2-code/) Field descriptions for our geocode and certified products can be accessed from [the main field descriptions menu](/field-descriptions/). ## Primary Address Fields Primary fields (also known as atomic fields) are always populated and verified when appropriate. | Field | Description | | - | - | | **Address \[in,out]** | This field holds the full address, correctly formatted for mailing in the relevant country, including line breaks specified using the `AddressLineSeparator` option. Do not use `Address` as input when running CASS. The preferred input for CASS is (`Address1` + `Locality` + `AdministrativeArea` + `PostalCode` + `Country`). However, (`Address1` + `Address2` + `Country`) will also work. | | **Address1, Address2, …, Address8 \[in,out]** | These fields can be used to specify input address line data, and on output will contain the correctly formatted address split into individual address lines for mailing in the relevant country. Examples of recommended input are listed below: - Address lines input: (`Address1`, `Address2`, `Address3` OR `Address`) + `Country` - Address lines + geographical: `Address1`, `Address2`, `Address3` + `Locality` + `AdministrativeArea` + `PostalCode` + `Country` **Note**: If the input values (Thoroughfare/premise) are entered on separate lines, the user may receive an unexpected outcome as this is not in a recommended input format. Example: - `Premise` + `Address1` + `Locality` + `Postalcode` + `Country` | | **ID \[in,out]** | Optional. This field will be passed through to the output unchanged. | | **DeliveryAddress \[in,out]** | This field holds the full address minus the `Organization`, `Locality`, `AdministrativeArea` hierarchy and `PostalCode` hierarchy fields, correctly formatted for mailing in the relevant country, including line breaks specified using the `AddressLineSeparator` option. | | **DeliveryAddress1, DeliveryAddress2, …, DeliveryAddress8 \[in,out]** | These fields contain the individual lines contained within the `DeliveryAddress` field. | | **Country \[in]** | This field is used to supply the country name or code (ISO 3166 2-character country code and ISO 3166 3-character country code). | | **CountryName \[out]** | This field holds the ISO 3166 official country name. | | **ISO3166-2 \[out]** | This field holds the ISO 3166 2-character country code. | | **ISO3166-3 \[out]** | This field holds the ISO 3166 3-character country code. | | **ISO3166-N \[out]** | This field holds the ISO 3166 3-digit numeric country code. | | **SuperAdministrativeArea \[in,out]** | This field holds the largest geographic data element within a country. | | **AdministrativeArea \[in,out]** | This field holds the most common geographic data element within a country. For instance, USA State, and Canadian Province. | | **SubAdministrativeArea \[in,out]** | This field holds the smallest geographic data element within a country. For instance, USA County. | | **Locality \[in,out]** | This field holds the most common population center data element within a country. For instance, USA City, Canadian Municipality. | | **DependentLocality \[in,out]** | This field holds a smaller population center data element, dependent on the contents of the `Locality` field. For instance, Turkish Neighborhood. | | **DoubleDependentLocality \[in,out]** | This field holds the smallest population center data element, dependent on both the contents of the `Locality` and `DependentLocality` fields. For instance, UK Village. | | **Thoroughfare \[in,out]** | This field holds the most common street or block data element within a country. For instance, USA Street. | | **DependentThoroughfare \[in,out]** | This field holds the dependent street or block data element within a country. For instance, UK Dependent Street. | | **Building \[in,out]** | This field contains the descriptive name identifying an individual location, should one exist. | | **Premise \[in,out]** | This field contains the alphanumeric code identifying an individual location, should one exist. | | **SubBuilding \[in,out]** | This field contains the secondary identifiers for a particular delivery point. For instance, `FLAT 1` or `SUITE 212`. | | **SubBuildingFloor \[in,out]** | This field contains the parsed floor information within the `SubBuilding` field, and includes the floor label (or type) and a numeric where applicable. For example, `L7` or `Fl 12`. This will be consistently populated for the following countries: Argentina, Australia, China, Denmark, Guernsey, Hong Kong, Isle of Man, Japan, Jersey, Kenya, South Korea, Lithuania, Macao, New Zealand, Portugal, Puerto Rico, Spain, and Taiwan. | | **HasSubPremise \[out]** | As part of the US PDH data an additional field will be returned named `HasSubPremise`. This field, in combination with the AVC code, will articulate whether the premise has any sub premises (a.k.a., SubBuilding) (e.g., apartments). This is particularly useful for customers and partners where accurate sub premise information is critical for ensuring a successful delivery. The `HasSubPremise` field will return a value of `Yes`, `No`, or blank. Additional information and examples are available on the separate [HasSubPremise page](/field-descriptions/hassubpremise). | | **PostalCode \[in,out]** | This field contains the complete postal code for a particular delivery point, should such detail be able to be determined. | | **PostalCodePrimary \[out]** | This field contains the primary postal code used for a particular country. For instance, USA Zip, Canadian Postcode, Indian PINcode. | | **PostalCodeSecondary \[out]** | This field contains secondary postal code information, if used in a particular country and if such detail is able to be determined and reference data is available. For instance, USA Zip Plus 4. | | **Organization \[in,out]** | This field contains the business name associated with a particular delivery point, should one exist. | | **PostBox \[in,out]** | This field contains the post box for a particular delivery point, should one exist. | | **AddressFormat \[out]** | If Server Option `OutputAddressFormat` is `Yes`, then this field will contain the fields used to construct the `Address` Field. For example, `Organization
DeliveryAddress
Locality AdministrativeArea PostalCode`. The default `
` line breaks can be changed with the `AddressLineSeparator` Server Option. | | **DeliveryAddressFormat \[out]** | If Server Option `OutputAddressFormat` is `Yes`, then this field will contain the fields used to construct the `DeliveryAddress` Field. For example, `Organization
DeliveryAddress
Locality AdministrativeArea PostalCode`. The default `
` line breaks can be changed with the `AddressLineSeparator` Server Option. | | **AVC (Address Verification Code) \[out]** | A response code which includes information associated with the parsing and matching of the address record. Use this to identify the level to which an address has been verified. See [the AVC page](/report-codes/address-verification-code/) for more information. | | **AQI (Address Quality Index) \[out]** | Offers a view of overall address quality (see [the AQI page](/report-codes/address-quality-index/) for more information), but is not used as a metric for deciding whether to accept an address which has been processed via Verify. **Please use the AVC to verify addresses.** | | **Sequence \[out]** | When multiple addresses are included in a single Verify request this counter will show the order of the addresses from the input. For example: `7` represents the 7th address in the input request. | ## Sub-Fields Sub-fields are populated when the level of parsing detail exists for the particular country. Sub-fields are only verified when they are supported by the reference data for the particular country. Therefore they are not guaranteed to be populated or verified in the output. For example, a Sub-field may be populated from the parsed input, but may not be able to be verified. Please check the associated [Field Status](/report-codes/fieldstatus/) to confirm. | Field | Description | | - | - | | **Unmatched \[out]** | This field can hold any information in the input address fields that is unable to be parsed to a particular address field. [Read more about the Unmatched field here](/field-descriptions/unmatched-field/). | | **MatchRuleLabel \[out]** | Loqate Engine uses a set of rules to match the input with the reference data. Each rule is identified by a match rule label. Please refer to the below links for more information regarding the Match Rules. - [Match Process](/available-processes/match-process/) - [Match Rule Syntax](/support/match-rules-syntax/) | | **HyphenClass \[out]** | [objfields](/field-descriptions/objfeilds/) | | **Contact \[in,out]** | This field can hold contact name information. | | **Function \[in,out]** | This field can hold function or job title information. | | **Department \[in,out]** | This field can hold organizational department information. | | **AdministrativeAreaName \[out]** | This field holds the name indicator within the `AdministrativeArea` field, should one exist. For example, Taipai where the `AdministrativeArea` is Taipai City. | | **AdministrativeAreaTrailingType \[out]** | This field holds the trailing `AdministrativeArea` type, should one exist. For example, City where the `AdministrativeArea` is Taipai City. | | **AdministrativeAreaType \[out]** | This field holds the `AdministrativeArea` type, should one exist. For example, City where the `AdministrativeArea` is Taipai City. | | **LocalityExtra \[out]** | This field is used to hold information that could be present along with the `Locality`. This information is not considered as part of the Postal authority data but is still necessary for parsing the address in order to obtain a complete delivery address. Available if a sufficient level of parsing detail exists within a particular country. Example: 12 rue de la Gare, 75019 PARIS CEDEX, France. CEDEX will be considered as Locality Extra. | | **LocalitySpecial** | The `LocalitySpecial` field combines both the `Locality` and `LocalityExtra` components, to capture specific locality information that includes essential details for accurate address parsing and delivery. For example, in the address "12 rue de la Gare, 75019 PARIS CEDEX, France," the term "Paris CEDEX" represents the `LocalitySpecial`. It encompasses both the primary locality (Paris) and the additional locality information (CEDEX) that is necessary for a complete and precise delivery address. | | **LocalityName \[out]** | This field holds the name indicator within the `Locality` field, should one exist. For example: Jeju where the `Locality` is Jeju-Si. | | **LocalityType \[out]** | This field holds the type indicator for `Locality`, should one exist. For example: Dist. where the `Locality` is Da'an Dist. | | **LocalityTrailingType \[out]** | This field holds the type indicator for `Locality`, should one exist. For example: Dist. where the `Locality` is Da'an Dist. | | **DependentLocalityName \[out]** | This field holds the name indicator within the `DependentLocality` field, should one exist. For instance, if `DependentLocality` contains `Dong Cheng Qu` `DependentLocalityName` contains `Dong Cheng` if a sufficient level of parsing detail exists for the particular country. | | **DependentLocalityType \[out]** | This field is used to hold the `DependentLocality` indicator within the `DependentLocality` field, should one exist. For instance, if `DependentLocality` contains `Dong Cheng Qu` `DependentLocalityType` contains `Qu` if a sufficient level of parsing detail exists for the particular country. | | **DependentLocalityLeadingType \[out]** | This field holds the leading dependent locality type indicator, should one exist. For example, `Rancheria San Jose Cacahuatepec` where the `DependentLocality` is Ciudad Renacimiento. | | **DoubleDependentLocalityName \[out]** | This field holds the name indicator within the `DoubleDependentLocality` field, should one exist. For instance, if `DoubleDependentLocality` contains `Xin Zhuang Zhen` `DoubleDependentLocalityName` contains `Xin Zhuang` if a sufficient level of parsing detail exists for the particular country. | | **DoubleDependentLocalityType \[out]** | This field is used to hold the `DoubleDependentLocality` indicator within the `DoubleDependentLocality` field, should one exist. For instance, if `DoubleDependentLocality` contains `Xin Zhuang Zhen` `DoubleDependentLocalityType` contains `Zhen` if a sufficient level of parsing detail exists for the particular country. | | **ThoroughfarePreDirection \[out]** | This field holds the prefix directional contained within the `Thoroughfare` field, should one exist. For instance, if `Thoroughfare` contains `N MAIN ST` `ThoroughfarePreDirection` contains `N` if a sufficient level of parsing detail exists for the particular country. | | **ThoroughfareType \[out]** | This field holds the type of thoroughfare should one exist. Examples include Road, Vei, St, Rua, Avenita, Pereulok, 路 | | **ThoroughfareLeadingType \[out]** | This field holds the leading thoroughfare type indicator within the `Thoroughfare` field, should one exist. For instance, if `Thoroughfare` contains `RUE DE LA GARE` `ThoroughfareLeadingType` contains `RUE` if a sufficient level of parsing detail exists for the particular country. | | **ThoroughfareName \[out]** | This field holds the name indicator within the `Thoroughfare` field, should one exist. For instance, if `Thoroughfare` contains `N MAIN ST` `ThoroughfareName` contains `MAIN` if a sufficient level of parsing detail exists for the particular country. | | **ThoroughfareTrailingType \[out]** | This field holds the trailing thoroughfare type indicator within the `Thoroughfare` field, should one exist. For instance, if `Thoroughfare` contains `N MAIN ST` `ThoroughfareTrailingType` contains `ST` if a sufficient level of parsing detail exists for the particular country. | | **ThoroughfarePostDirection \[out]** | This field holds the postfix directional contained within the `Thoroughfare` field, should one exist. For instance, if `Thoroughfare` contains `MAIN ST N` `ThoroughfarePostDirection` contains `N` if a sufficient level of parsing detail exists for the particular country. | | **DependentThoroughfarePreDirection \[out]** | This field holds the prefix directional contained within the `DependentThoroughfare` field, should one exist. For instance, if `DependentThoroughfare` contains `N MAIN ST` `DependentThoroughfarePreDirection` contains `N` if a sufficient level of parsing detail exists for the particular country. | | **DependentThoroughfareLeadingType \[out]** | This field holds the leading thoroughfare type indicator within the `DependentThoroughfare` field, should one exist. For instance, if `DependentThoroughfare` contains `RUE DE LA GARE` `DependentThoroughfareLeadingType` contains `RUE` if a sufficient level of parsing detail exists for the particular country. | | **DependentThoroughfareName \[out]** | This field holds the name indicator within the `DependentThoroughfare` field, should one exist. For instance, if `DependentThoroughfare` contains `N MAIN ST` `DependentThoroughfareName` contains `MAIN` if a sufficient level of parsing detail exists for the particular country. | | **DependentThoroughfareTrailingType \[out]** | This field holds the trailing thoroughfare type indicator within the `DependentThoroughfare` field, should one exist. For instance, if `DependentThoroughfare` contains `N MAIN ST` `DependentThoroughfareTrailingType` contains `ST` if a sufficient level of parsing detail exists for the particular country. | | **DependentThoroughfarePostDirection \[out]** | This field holds the postfix directional contained within the `DependentThoroughfare` field, should one exist. For instance, if `DependentThoroughfare` contains `MAIN ST N` `DependentThoroughfarePostDirection` contains `N` if a sufficient level of parsing detail exists for the particular country. | | **BuildingLeadingType \[out]** | This field holds the leading building type indicator within the `Building` field, should one exist. For instance, if `Building` contains `BLOC C` `BuildingLeadingType` contains `BLOC` if a sufficient level of parsing detail exists for the particular country. | | **BuildingName \[out]** | This field holds the name indicator within the `Building` field, should one exist. For instance, if `Building` contains `WESTMINSTER HOUSE` `BuildingName` contains `WESTMINSTER` if a sufficient level of parsing detail exists for the particular country. | | **BuildingType \[out]** | This field is used to hold the Building indicator within the `Building` field, should one exist. Examples include Place, 城. | | **BuildingTrailingType \[out]** | This field holds the trailing building type indicator within the `Building` field, should one exist. For instance, if `Building` contains `WESTMINSTER HOUSE` `BuildingTrailingType` contains `HOUSE` if a sufficient level of parsing detail exists within a particular country. | | **PremiseType \[out]** | This field contains the leading premise type indicator within the `Premise` field, should one exist. For instance, if `Premise` contains `Plot 7/7A` `PremiseType` contains `Plot` if a sufficient level of parsing detail exists within a particular country. | | **PremiseNumber \[out]** | This field contains the alphanumeric indicator within the `Premise` field, should one exist. For instance, if `Premise` contains `Plot 7/7A` `PremiseNumber` contains `7/7A` if a sufficient level of parsing detail exists within a particular country. | | **PremiseExtra \[out]** | This field is used to hold information that could be present as part of the `Premise` field. This information is not considered as part of the Postal authority data but is still necessary for parsing the address in order to obtain a complete delivery address. Available if a sufficient level of parsing detail exists within a particular country. Example: In French address, the Premise number could be followed by words bis and ter which will be considered as Premise Extra. 25 bis rue Emile Zola, 91190 GIF SUR YVETTE, France. Bis will be considered as `PremiseExtra`. | | **SubBuildingType \[out]** | This field contains the leading sub-building type indicator within the `SubBuilding` field, should one exist. For instance, if `SubBuilding` contains `FLAT 1` `SubBuildingType` contains `FLAT` if a sufficient level of parsing detail exists within a particular country. | | **SubBuildingLeadingType \[out]** | This field contains the sub-building type indicator within the `SubBuilding` field, should one exist. For instance, if `SubBuilding` contains `FLAT 1` `SubBuildingLeadingType` contains `FLAT` if a sufficient level of parsing detail exists within a particular country. | | **SubBuildingNumber \[out]** | This field contains the alphanumeric indicator within the `SubBuilding` field, should one exist. For instance, if `SubBuilding` contains `FLAT 1` `SubBuildingNumber` contains `1` if a sufficient level of parsing detail exists within a particular country. | | **SubBuildingName \[out]** | This field contains the descriptive name within the `SubBuilding` field. For instance, if `SubBuilding` contains `BASEMENT FLAT` `SubBuildingName` contains `BASEMENT FLAT`. | | **SubBuildingBlock \[out]** | This field contains the secondary identifiers for a particular delivery point. For instance – `BLOQUE 7`. | | **SubBuildingDoor \[out]** | This field contains the secondary identifiers for a particular delivery point. For instance `PUERTA D`. | | **SubBuildingStaircase \[out]** | This field contains the secondary identifiers for a particular delivery point. For instance `PUERTA D`. | | **Bolignummer (Norway only) \[out]** | The utility unit number consist of a letter followed by four numbers (Norway/NO/NOR only). Examples include: `H0001`, `L0002`, `U0004`, `K0032`. | | **DeliveryInstallationAreaName (Canada only) \[out]** | The name of a village, town, municipality, city, or metropolitan area that forms part of a Delivery Installation Name (Canada/CA/CAN only). Examples include: Ladysmith, Roxton Pond. | | **DeliveryInstallationType (Canada only) \[out]** | An abbreviation that represents the type of installation (Canada/CA/CAN only). Examples include: STN – Postal Station, PO – Post Office, BDP – Bureau De Poste. | | **DeliveryInstallationQualifierName (Canada only) \[out]** | When more than one delivery installation serves an area described by the Delivery Installation Area Name, the qualifier name uniquely identifies the delivery installation (Canada/CA/CAN only). Examples include: Cap-A-L'aigle, B, St Michel, 32, Bank Hunt Club. | | **RouteType (Canada only) \[out]** | A code that identifies the type of route service (Canada/CA/CAN only). Examples include: RR – Rural Route, SS – Suburban Service. | | **RouteNumber (Canada only) \[out]** | A number that identifies the specific Delivery Mode (Canada/CA/CAN only). Examples include: `22`, `62`, `404`. | | **BranchName (Canada only) \[out]** | Branch name of Department field (Canada/CA/CAN only). Examples include: Agence De Parcs Canada, Fisheries and Oceans, Ottawa District Office. | | **MakaniNumber (United Arab Emirates only) \[out]** | A Makani number is a 10-digit number which gives you the exact location of the entrance of a building (United Arab Emirates/AE/ARE only). For example: `3000595279`. | | **ShortAddressCode (Saudi Arabia only) \[out]** | A short address that consists of four letters followed by four numbers (Saudi Arabia/SA/SAU only). For example: `RGSA3808`. | | **Cluster (Indonesia Only)** | This field refers to a residential grouping commonly used in Indonesian addresses, similar to neighbourhood or resident association information. It helps identify specific housing areas within larger communities and represents local administrative divisions commonly known as RT (Rukun Tetangga) and RW (Rukun Warga). | | **OrganizationName \[out]** | This field contains the name indicator within the `Organization` field, should one exist. For instance, if `Organization` contains `Loqate Inc` `OrganizationName` contains `Loqate` if a sufficient level of parsing detail exists for the particular country. | | **OrganizationType \[out]** | This field contains the type indicator contained within the `Organization` field, should one exist. For instance, if `Organization` contains `Loqate Inc` `OrganizationType` contains `Inc` if a sufficient level of parsing detail exists for the particular country. | | **OrganizationTrailingType \[out]** | This field contains the trailing type indicator contained within the `Organization` field, should one exist. For example: Corp., Gmbh. | | **PostBoxType \[out]** | This field contains the type indicator contained within the `PostBox` field, should one exist. For instance, if `PostBox` contains `PO BOX 1234` `PostBoxType` contains `PO BOX` if a sufficient level of parsing detail exists for the particular country. | | **PostBoxNumber \[out]** | This field contains the alphanumeric indicator within the `PostBox` field, should one exist. For instance, if `PostBox` contains `PO BOX 1234` `PostBoxNumber` contains `1234` if a sufficient level of parsing detail exists for the particular country. | | **BoxBagLobbyName (New Zealand only) \[out]** | Box lobby name or New Zealand Post shop name (New Zealand/NZ/NZL only). Examples include: MAUNGATAPERE POSTCENTRE, NEWMARKET POSTSHOP, MOUNT COOK. | # AMAS Fields Source: https://docs.loqate.com/field-descriptions/amas-fields The table below is the list of AMAS specific output fields. | Field | Definition | | - | - | | **DPID** | Delivery Point Identifier is a unique 8-digit number which is assigned for every new address to the source address database | | **FloorType** | Type of floor or level | | **FloorNumber** | Floor or level number (including alpha characters) | | **LotNumber** | Allotment number | | **PostBoxNum** | Postal delivery number if the address is a postal delivery type | | **PostBoxNumberPrefix** | Postal delivery number prefix related to the postal delivery number | | **PostBoxNumberSuffix** | Postal delivery number suffix related to the postal delivery number | | **PrimaryPremise** | Thoroughfare number for a property (first number in a property ranged address) | | **PrimaryPremiseSuffix** | Suffix for the thoroughfare number | | **SecondaryPremise** | Second thoroughfare number (only used if the property has a ranged address eg 23-25) | | **SecondaryPremiseSuffix** | Suffix for the second thoroughfare number | | **PreSortZone** | Also known as Barcode Sort Plan (BSP) number. The number of one of 54 individual sort regions around Australia. To qualify for Australia Post's PreSort Letters Service, letters must be sorted based on this number | | **PrintPostZone** | Also known as a PreSort Indicator. To qualify for Australia Post's Print Post Service, letters must be sorted based on this number | | **Barcode** | Standard barcode based on the DPID | | **PrimaryAddressLine** | Primary address line in standardized format | | **SecondaryAddressLine** | Secondary address line in standardized format | ## AMAS Error Code Information For the AMAS process, the `ErrorCode` field lets us determine whether PPM rules have taken place. An `ErrorCode` of `4` indicates that all of the fields were matched correctly (i.e. no error), which means the DPID matches the entire input address and PPM has not been used. If the `ErrorCode` is `5` or `19`, the address is respectively not verified or partially verified at the `SubBuilding` level, and PPM has been used to match to the Primary Point address. If the `ErrorCode` is `20` or `21`, the address is only verified up to `Thoroughfare` or `Locality` respectively, and the output address and DPID both reflect this verification level. Although we cannot determine whether PPM has been used in this case, the output address does not contain information beyond what can be found with the DPID. If the `ErrorCode` is `211` through `216`, at least one field has been changed between the input and the output, likely because of a spelling error or a blank field. We cannot determine whether PPM has been used based on this `ErrorCode` alone, but we can use the corrected output address to fix the input spelling error and get a new `ErrorCode` that allows us to determine whether PPM has been used. The error codes correspond to the following spelling errors: | Error Code | Field Corrected | Description | | - | - | - | | `211` | Thoroughfare name | The street name was corrected | | `212` | Locality | The suburb/town name was corrected | | `213` | PostalCode | The postal code was corrected | | `214` | AdministrativeArea | The state/territory was corrected | | `215` | Thoroughfare type | The street type (ST, RD, etc) was corrected | | `216` | Thoroughfare direction | The street direction (N, S, etc) was corrected | # What are ISO2 codes for Administrative Areas? Source: https://docs.loqate.com/field-descriptions/data-enhancement/data-enhancement-administrativearea-iso-2-code **ISO 3166-2** is part of the [ISO 3166](http://en.wikipedia.org/wiki/ISO_3166) standard published by the International Organization for Standardization (ISO), and defines codes for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1. The official name of the standard is *Codes for the representation of names of countries and their subdivisions – Part 2: Country subdivision code. It was first published in 1998.* The purpose of ISO 3166-2 is to establish an international standard of short and unique alphanumeric codes to represent the relevant administrative divisions and dependent territories of all countries in a more convenient and less ambiguous form than their full names. Each complete ISO 3166-2 code consists of two parts, separated by a hyphen: * The first part is the code of the country * The second part is a string of up to three alphanumeric characters, which is usually obtained from national sources and stems from coding systems already in use in the country concerned, but may also be developed by the ISO itself. Each complete ISO 3166-2 code can then be used to uniquely identify a country subdivision in a global context. ## Coverage and Data Loqate previously supplied [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) values for administrative areas in the United States, Canada, Germany, Brazil, Colombia, France, and Argentina. From the 2022Q2.1 release onwards, `rd_WW_enh_ISO_ADMIN` file will cover 171 countries in total, which includes: AD, AE, AF, AG, AL, AM, AO, AR, AT, AU, AZ, BD, BE, BF, BG, BI, BJ, BN, BQ, BR, BS, BT, BW, BY, BZ, CA, CG, CH, CI, CL, CN, CO, CR, CU, CV, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, ER, ES, ET, FI, FJ, FR, GA, GB\*, GD, GE, GH, GL, GM, GN, GQ, GR, GT, GW, GY, HN, HR, HT, HU, ID, IE, IL, IN, IQ, IR, IS, IT, JM, JO, JP, KE, KG, KH, KM, KN, KP, KR, KW, KZ, LA, LB, LI, LK, LR, LS, LT, LU, LV, LY, MD, ME, MM, MN, MU, MV, MW, MX, MY, MZ, NA, NG, NI, NL, NO, NP, NR, NZ, OM, PA, PE, PG, PH, PK, PL, PT, PY, QA, RO, RS, RU, SA, SB, SC, SD, SE, SH, SK, SM, SN, SO, SR, SS, SV, SY, SZ, TD, TH, TJ, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, US, UY, UZ, VC, VE, VN, VU, WS, YE, ZA, ZM, ZW Using a combination of the `CountryName` and `AdministrativeArea` fields, the Loqate engine will add the ISO 3166-2 code to a field called `AdministrativeAreaISO2`. Each `AdministrativeAreaISO2` value refers to a unique combination of country and administrative area. The value in the `AdministrativeAreaISO2` consists of two parts, separated by a hyphen. The first part is the ISO 3166-1 alpha-2 code of the Country. The second part is multiple letters or numbers representing the `AdministrativeArea`. The Loqate engine will also return a field status for `AdministrativeAreaISO2`. For a valid code the field status will read `fsAdded`. > [!NOTE] > > Note that for GB, the ISO code returned is based on Royal Mail former postal county that they have declared static. Because of that, North Northamptonshire and West Northamptonshire will return the `AdministrativeArea` of Northamptonshire with code `GB-NTH`. > > The absence of comprehensive ISO 3166‑2 values is expected, as the default Loqate AdministrativeArea for GB is based on former postal counties, which do not have full or official ISO 3166‑2 coverage. ISO 3166‑2 codes are only defined for recognised official administrative subdivisions, not for postal constructs (see page 70 of the Royal Mail Programmer’s Guide: [https://www.poweredbypaf.com/wp-content/uploads/2024/11/Latest-Programmers\_guide\_Edition-7-Version-6-2.pdf](https://www.poweredbypaf.com/wp-content/uploads/2024/11/Latest-Programmers_guide_Edition-7-Version-6-2.pdf)). # Data Enhancement: Sample API Call Source: https://docs.loqate.com/field-descriptions/data-enhancement/data-enhancement-sample-api-call ## Overview `Enhance` is a follow-up process that can be called to append enhanced data to a verified address. The process will call up different enhancement data packs depending on how the API call is setup. The example below shows a Java API call appending the ISO 3166-2 field to Loqate's business address. ## Sample Java API Call ```java theme={null} import com.loqate.*; import java.io.*; import java.net.*; public class lqtSample { static { System.loadLibrary("lqtjava"); } public static void main(String args[]) { // Loqate objects lqtServer srv = lqtServer.create(); lqtInputRecord rec = lqtInputRecord.create(); lqtProcessResult res = lqtProcessResult.create(); // Initialize the server if (args.length > 0) srv.init(args[0]); else srv.init("./data"); // Create the process list lqtProcessList lst = lqtProcessList.create(); lqtProcessOptions opts = lqtProcessOptions.create(); lst.add("Verify", opts); lst.add("Geocode", opts); lst.add("Enhance", opts); try { // Open the Loqate session int session = srv.open(); // Process data try { // Set the relevant Loqate values rec.set("Address1", "999 baker way ste 320 san mateo ca 94404 usa"); //rec.set("Address2", "usa"); // Process the record srv.process(rec, lst, res); // Output the result System.out.println("Found " + res.getCount() + " records"); for (int i = 0; i < res.getCount(); i++) { System.out.println("Output record " + i); for (int j = 0; j < res.getFieldCount(i); j++) { System.out.println(res.getFieldName(i, j) + " : " + res.getField(i, j)); } } System.out.flush(); } catch (Exception e) { System.out.println("Exception: " + e); } // Close the session srv.close(session); } catch (Exception e) { System.out.println("Exception: " + e); } // Destroy the process list lqtProcessList.destroy(lst); lqtProcessOptions.destroy(opts); // Tidy up srv.shutdown(); lqtInputRecord.destroy(rec); lqtProcessResult.destroy(res); lqtServer.destroy(srv); } } ``` ## Output ```properties theme={null} AQI : A AVC : V55-I55-P7-100 Address : 999 Baker Way Ste 320\
San Mateo CA 94404-1566 Address1 : 999 Baker Way Ste 320 Address2 : San Mateo CA 94404-1566 AdministrativeArea : CA # Census output field below AdministrativeAreaISO2 : US-CA # ISO-2 Administrative Area code CensusClassCode : C1 CensusCode : 68252 CensusIndicator : Locality GNISFeatureID : 2411800 CountryName : United States DeliveryAddress : 999 Baker Way Ste 320 DeliveryAddress1 : 999 Baker Way Ste 320 GeoAccuracy : P4 GeoDistance : 0.0 ISO3166-2 : US ISO3166-3 : USA ISO3166-N : 840 Latitude : 37.560210 Locality : San Mateo Longitude : -122.285640 MatchRuleLabel : 1 PostalCode : 94404-1566 PostalCodePrimary : 94404 PostalCodeSecondary : 1566 Premise : 999 PremiseNumber : 999 SubAdministrativeArea : San Mateo SubBuilding : Ste 320 SubBuildingLeadingType : Ste SubBuildingNumber : 320 Thoroughfare : Baker Way Verify|Country|Parse|Lexicon:TABLE=lx_US3|RefLex:TABLE=rd_US_vfy;POSTCODECHECK=Yes;POSTCODEFIELD=PostalCodeIndex|Signal:MATCHTYPES=Address ``` # US Census Data Fields Source: https://docs.loqate.com/field-descriptions/data-enhancement/data-enhancement-us-census-data-fields US Census Data may be appended to one of the following three fields: * `AdministrativeArea` * `SubAdministrativeArea` * `Locality` The data takes the form of multiple value fields, which are outlined in the next section. For each value field, there is a corresponding status field named `ValueFieldName_Status` which indicates whether a value was returned for that value field or not. If a value is returned the status field will contain `fsAdded`. ## Value Fields ### CensusIndicator This field indicates the address level for which the census data was returned. Since CENSUS data currently only covers the United States, only 3 levels of data will be shown: `Locality`, `SubAdministrativeArea`, and `AdministrativeArea`. In the best case scenario the value will be `Locality`, the most accurate address level CENSUS data covers. If input `Locality` is not found in CENSUS data, it may return `SubAdministrativeArea` indicating it can only find CENSUS data for `SubAdministrativeArea` level. ### CensusCode Census Code defines that the Census data is referencing the Census Codes, previously known as the Federal Information Processing Standard (FIPS) code. Census Codes are used as the government codes currently published for Admin Places in the U.S. This data is also published as Census data for completeness. Census Codes and GNIS Feature IDs are published for Administrative Areas (Admin Level 1-4 in the U.S.) and all Zones with official government codes. ### CensusClassCode Census Class Code defines the census classification of a place. Census Class Code corresponding to the FIPS 55-3 standard. Census Class Codes are alphanumeric and defined at [http://geonames.usgs.gov/pls/gnispublic](http://geonames.usgs.gov/pls/gnispublic). Census Class Codes are published only for level 3 and 4 Administrative Areas and Zones. An example would be: `C1`: Identifies an active incorporated place that is not also recognized as an Alaska Native Village statistical area, and does not also serve as a primary county division; that is, it is included in and is part of a primary county division. For example, the city of Hammond, Indiana is within and part of North township; the city of Austin, Texas is within and part of several census county divisions in several counties; Hammond and Austin are coded `C1`. ### GNISFeatureID GNIS Feature ID defines that the Census data is referencing the Geographic Names Information System (GNIS) Feature ID. GNIS Feature IDs are similar to Census Codes. GNIS includes geographic names for all known places, features, and areas in the United States that are identified by a proper name. Census Codes defined for level 4 Administrative Areas and Zones are being phased out by the U.S. government and replaced by GNIS Feature IDs. However, GNIS Feature IDs are an addition to and not a replacement of Census Codes. New places only get a GNIS Feature ID assigned. For new places the government code publishes the GNIS feature ID. Census Codes and GNIS Feature IDs are published for Administrative Areas (Admin Level 1-4 in the U.S.) and all Zones with official government codes. ### CBSAMetropolitanStatisticalArea CBSA Metropolitan Statistical Area defines that the Census data is referencing the Core Based Statistical Area (CBSA). CBSA is a collective term for both metro and micro areas. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. Each metro or micro area consists of one or more counties and includes the counties containing the core urban area, as well as any adjacent counties that have a high degree of social and economic integration with the urban core (as measured by commuting to work). \*CBSA Metropolitan or Micropolitan areas can span multiple Counties. There is one CBSA that defines a partial county. St. Louis, MO-IL Metropolitan Statistical Area only includes the Sullivan City part of Crawford County, MO. For this specific case the complete Crawford County are published with the CBSA code (`41180`) for St. Louis, MO-IL. ### CBSAMicropolitanStatisticalArea CBSA Micropolitan Statistical Area. See definition above. ### NECTAMetropolitanStatisticalArea NECTA Metropolitan Statistical Area defines a set of geographic areas that are defined using cities and towns in the six New England states. The New England City and Town Areas (NECTAs) are defined using the same criteria as Metropolitan and Micropolitan Statistical Areas and are identified as either Metropolitan or Micropolitan. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. NECTAs are published for one or more cities or towns where applicable. ### NECTAMicropolitanStatisticalArea NECTA Micropolitan Statistical Area. See definition above. ### MetropolitanDivision Metropolitan Division defines that the Census data is referring to a county or group of closely tied contiguous counties that serve as a distinct employment region within a metropolitan statistical area that has a population core of at least 2.5 million. While a Metropolitan Division is a subdivision of a larger metropolitan statistical area, it often functions as a distinct social, economic, and cultural area within a larger region. ### NECTADivision NECTA Division defines NECTAs (see definition above) containing a single core with a population of at least 2.5 million that are subdivided to form smaller groupings of cities and towns referred to as NECTA Divisions. [Learn more about other address enhancement datasets](/field-descriptions/data-enhancement/) # GB Enhancement Data Fields Source: https://docs.loqate.com/field-descriptions/data-enhancement/gb-enhancement-data-fields **The following fields are sourced through the United Kingdom Postal Address File (PAF) and the OS Open UPRN data source, and provide further intelligence on each verified address record.** ## UDPRNKey The Royal Mail UDPRN, or Unique Delivery Point Reference Number, is an eight-digit numeric key that is unique to every delivery point record in the PAF. There are some cases where `AddressKeys` or `OrganisationKeys` will change or be re-used, so the UDPRN key is a more permanent reference to a given delivery point. ## UPRN The Unique Property Reference Number (UPRN) is the twelve-digit Ordnance Survey's unique record ID for a property and is a persistent ID for a property. ## ParentUPRN The Parent UPRN is a twelve-digit UPRN of the shell or owning building of a Multiple Residence (flat, unit or apartment). Note that this is inferred from the relationships of an Multi Residence with a PAF parent address record. ## OwningUDPRN The Owning UDPRN is an eight-digit UDPRN key of the shell or owning PAF building record of a Multiple Residence (flat, unit or apartment). For example, if "Ground Floor Flat, Princes House" is a Multiple Residence record, then "Princes House" would be its owning building. ## UMRRN The Unique Multiple Residence Reference Number (UMRRN) is an eight-digit numeric key that is unique to every Multiple Residence (MR). ## ResidentialCommercialFlag A flag indicating if the address is known to be residential or commercial. Values are `R` (residential), `C` (commercial), or blank (unknown). ## DPS The Delivery Point Suffix (DPS) is used with a postcode to generate a machine-readable barcode (RM4SCC), which then serves as a unique reference to an active property or delivery point. It is made up of one number (1-9) and one character (A-T), and is assigned by Royal Mail. It is possible that an address is not assigned a DPS value, in which case a default value of `9U` or `9Z` is used. `1A` is also reserved for postcodes that have `PostCodeType = L` (Large User). **Example:** 16 St. Alphonsus Road, London * Postcode: `SW4 7AS` * DPS: `1B` * Sample RM4SCC: (Loqate does not generate a barcode) ## PostcodeType This can be one of two values, below. This value can also be empty (not assigned). ### Large User Postcode (L) These are assigned to one single address either due to the large volume of mail received at that address, or because a PO Box has been set up. ### Small User Postcode (S) Describes a range of standard delivery points. On average, a Small User Postcode will serve between 15-20 properties, but may range from 1 to 100+ delivery points. ## AddressKey Every address in the Royal Mail Postal Address File (PAF) is assigned an 8-digit value that serves as a persistent reference to a building or delivery point, even when there are changes to a postcode. ## OrganisationKey Each Organization that is added to PAF is assigned an 8-digit number that serves as a unique delivery point when used alongside the `AddressKey` and `PostcodeType`. This is useful to identify small businesses that share an address (the address will appear multiple times in the PAF). For residential addresses, `OrganisationKey` is set to `0`. ## FormerPostalCounty Default value for `AdministrativeArea`, or County, in the United Kingdom. Defined and supplied by Royal Mail. These values were used prior to the postcode system introduced in the 1970s to differentiate `Locality` names that were the same, or similar. E.g. Avon This field is assigned as the `AdministrativeArea` default as it remains static and provides a consistent geographic boundary. ## AdministrativeCounty Alternative value for `AdministrativeArea`, or County, in the United Kingdom. Defined and supplied by Royal Mail. This is the Unitary Authority name (where one is present), and provided by the Office for National Statistics. This field can change more frequently due to administrative changes in the respective area. E.g. "Bristol, City Of" ## Traditional County Alternative value for `AdministrativeArea`, or County, in the United Kingdom. Defined and supplied by Royal Mail. These values date from the 1800s and were assigned by the Association of British Counties. E.g. "Gloucestershire" [Learn more about other address enhancement datasets](/field-descriptions/data-enhancement/) # Enhancement Datasets Source: https://docs.loqate.com/field-descriptions/data-enhancement/overview Since 2015Q2.0 Loqate has been adding data enhancement capabilities to its product suite. The enrichment process allows a user to append non-address information (metadata) to address fields in the final output of the Loqate engine. That information is retrieved from Loqate-produced enhancement data packs through the `Enhance` option. This process will take the output from a Verify, Search, or Geocode process and append enhanced data to the qualified fields. ## Available Enhancement Packs The list of currently available enhancement packs is the following: *More data enhancement packs will become available over time* > [card] [China Premium Data Set](https://www.loqate.com/en-us/datasets/china-premium-data-set/) > [card] [U.S. Census Data](/field-descriptions/data-enhancement/data-enhancement-us-census-data-fields/) > [card] [U.S. Census Plus Data Set](/field-descriptions/data-enhancement/us-census-data-enhancement/) > [card] [Administrative Area ISO-2 Identifiers](/field-descriptions/data-enhancement/data-enhancement-administrativearea-iso-2-code/) > [card] [GB Enhanced Data](/field-descriptions/data-enhancement/gb-enhancement-data-fields/) > [card] [Worldwide Time Zone Data Set](/field-descriptions/data-enhancement/timezone/) > [card] [Residential/Commercial Flag](/field-descriptions/data-enhancement/residential-commercial-flag) ## Licensing The data sets available at the present time are not included automatically with every license, but can be obtained by requesting them from your account manager. Once your account manager has updated your license with access to specific enhancement data packs, they will be available for download. Please note that the enhancement data packs will require the country data pack for the specific country for which you attempt to enhance data. For example, the U.S. Census data pack will not function without the standard U.S. Verify or Geocode packs in your license, and as such will not be distributed to customers who have not licensed the required data packs. ## Installation The enhancement data packs can be installed with the same methods as all other data packs. The best way is to execute the Install Manager and install the enhancement packs in the data folder that contains all other Loqate data packs. ## Execution An example of an Enhance process call and its output can be found here: * [Sample Java API Call](/field-descriptions/data-enhancement/data-enhancement-sample-api-call/) # Residential/Commercial Flag Source: https://docs.loqate.com/field-descriptions/data-enhancement/residential-commercial-flag We have this flag available for these countries: Australia, Belgium, Brazil, Canada, Netherlands, Spain, United Kingdom and the USA. We will update this page when we add this flag for more countries. The `ResComFlag` field can have the following values: * **Res:** Residential * **Com:** Commercial * **R/C:** Mixed use residential/commercial. Please note that this is not available in US data * **Unk:** Unknown > [!NOTE] > > Due to country certification requirements, the flag will not be valid for both Australia AMAS certified addresses and Canda SERP certified addresses (i.e., when you run Verify using “Certify”:true). For USA CASS certified addresses, you can safely use the CASS provided ResidentialDelivery flag. # Time Zone Enhancement Dataset Source: https://docs.loqate.com/field-descriptions/data-enhancement/timezone ## What are Time Zones? Time Zone refers to the local time of a region or a country. The local time within a time zone is defined by its offset (difference) from Coordinated Universal Time (UTC), the world's time standard, ranging from UTC-12:00 to UTC+14:00. Some countries or regions use Daylight Savings Time (DST) for part of the year during spring and summer. During DST, our clocks are forwarded an hour, so daylight ends at a later time of the day. ## Coverage and Data Loqate provides time zone information for worldwide countries. Most countries have a single time zone, there are 23 countries with at least two time zones, including Antarctica, Australia, Brazil, Canada, The Democratic Republic of the Congo, Ecuador, French Polynesia, Greenland, Indonesia, Kazakhstan, Kiribati, Mexico, Federated States of Micronesia, Mongolia, New Zealand, Papua New Guinea, Portugal, Russian Federation, Spain, Ukraine, United States Minor Outlying Islands, and United States. For countries with single time zone, Loqate engine will add the time zone fields using `CountryName` field. Whereas for countries with multiple time zones, Loqate will add the time zone fields using a combination of `CountryName` and Geographical fields – (`SuperAdministrativeArea` / `AdministrativeArea` / `SubAdministrativeArea` / `Locality` / or the combination of all of them). The new Time Zone enhanced data is available by using the `Enhance` option on the address verify requests. The following additional fields will be returned with the other address verification fields: ## Value Fields ### TimeZone\_UTC UTC defines the Coordinated Universal Time. **Example:** 2869 S County Road 210, Knox IN 46534-7969, USA * Returned UTC value: `-05:00` ### TimeZone\_DST DST defines the Daylight Saving Time. **Example:** 2869 S County Road 210, Knox IN 46534-7969, USA * Returned DST value: `-06:00` ### TimeZone\_Name This field is available with 2022 Q1.1 Minor release. For more information about accessing or using the Time Zone data please contact your account manager or support. # US Census Plus Data Fields Source: https://docs.loqate.com/field-descriptions/data-enhancement/us-census-data-enhancement US Census Plus Data may be appended to one or more of the following fields: * `AdministrativeArea` * `SubAdministrativeArea` * `Locality` * `Thoroughfare` * `Premise` This data comes from the US Census Tiger File and will provide multiple value fields which are outlined in the next section. For each value field, there is a corresponding status field named `ValueFieldName_Status` which indicates whether a value was returned for that value field or not. If a value is returned the status field will contain `fsAdded`. Please note it is important that when you use the new Census Plus data set you set the server option: `ReferenceDatasetCacheSize=15` This is due to the increased volume of data files in use as part of the Census Plus enhanced dataset. Please also note as a result of the increased size of this dataset we recommend an increase of 5GB of memory is allocated to your existing integration. ## Value Fields ### BlockCode `BlockCode` defines the census data that represent the smallest geographic unit used by the US Census Bureau. Blocks may be bounded by visible features such as roads/highways, rivers and other natural features, railroad tracks and non-visible features such as political boundaries of a city/town/county or property lines and school district. Blocks typically have a 4-digit value. In Loqate, this value field is appended to `Thoroughfare` and `Premise` field. ### BlockGroupCode `BlockGroupCode` defines the census data that represent the group of Blocks. `BlockGroupCode` typically have a 1-digit value, and it is also represented in the first digit value in `BlockCode` field value. In Loqate, this value field is appended to `Thoroughfare` and `Premise` field. ### CBSACode `CBSACode` defines that the Census data is referencing the Core-Based Statistical Area (CBSA), in typically 5-digit value. CBSA is a collective term for both metro and micro areas. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. Each metro or micro area consists of one or more counties and includes the counties containing the core urban area, as well as any adjacent counties that have a high degree of social and economic integration with the urban core (as measured by commuting to work). CBSAs defined according to the population standards above were applied since the Census 2000 data, that was announced by OMB (US Office of Management and Budget) in June 2003. These standards are used to replace the definitions of metropolitan areas (MSA) that were defined in 1990. ### CBSAName `CBSAName` refers to the official name given to the CBSAs which complements the `CBSACode` field value as defined above. For definition of CBSA, please refer to the `CBSACode` field definition above. ### CensusCode `CensusCode` defines that the Census data is referencing the Census Codes, previously known as the Federal Information Processing Standard (FIPS) code. Unlike its previous FIPS code value, Census Codes are currently used as the government code to represent Admin Places in the U.S. Census Codes are published for Administrative Areas (Admin Level 1-4 in the U.S.) and all Zones with official government codes. ### CensusClassCode `CensusClassCode` defines the census classification of a place. Census Class Code corresponding to the FIPS 55-3 standard. Census Class Codes are alphanumeric and can be referred at [https://www.census.gov/library/reference/code-lists/class-codes.html](https://www.census.gov/library/reference/code-lists/class-codes.html). Census Class Codes are published only for level 3 and 4 Administrative Areas and Zones. An example would be: `C1`: Identifies an active incorporated place that is not also recognized as an Alaska Native Village statistical area and does not also serve as a primary county division; that is, it is included in and is part of a primary county division. For example, the city of Hammond, Indiana is within and part of North township; the city of Austin, Texas is within and part of several census county divisions in several counties; Hammond and Austin are coded `C1`. ### CensusIndicator This field indicates the address level for which the census data was returned. In Census Plus, this field will show the value `Premise`, the most accurate address level in Census Plus data, when there is Premise level match found. Otherwise, the value field would not be visible. ### CountyCode The primary legal divisions of most states are termed counties. While not all states have them or call them counties, the census bureau will assign one for statistical purposes. These are three-character numeric codes that are unique within each state. ### GNISFeatureID `GNISFeatureID` defines the census data that is referencing the Geographic Names Information System (GNIS) Feature ID. GNIS Feature IDs are similar to Census Codes. GNIS includes geographic names for all known places, features, and areas in the United States that are identified by a proper name. Census Codes defined for level 4 Administrative Areas and Zones are being phased out by the U.S. government and replaced by GNIS Feature IDs. However, GNIS Feature IDs are an addition to and not a replacement of Census Codes. New places only get a GNIS Feature ID assigned. For new places the government code publishes the GNIS feature ID. Census Codes and GNIS Feature IDs are published for Administrative Areas (Admin Level 1-4 in the U.S.) and all Zones with official government codes. ### MetroDivisionCode `MetroDivisionCode` (Metropolitan Division Code) defines the census data that is referring to a county or group of closely tied contiguous counties that serve as a distinct employment region within a metropolitan statistical area that has a population core of at least 2.5 million. While a Metropolitan Division is a subdivision of a larger metropolitan statistical area, it often functions as a distinct social, economic, and cultural area within a larger region. Metropolitan Division Code is typically represented in 5-digit value. ### MetroDivisionName `MetroDivisionName` refers to the official name given to the Metropolitan Division which complements the `MetroDivisionCode` field value as defined above. For definition of Metropolitan Division, please refer to the `MetroDivisionCode` field definition above. ### NECTACode `NECTACode` refers to a set of geographic areas that are defined using cities and towns in the six New England states, in typically 5-digit value. The New England City and Town Areas (NECTAs) are defined using the same criteria as Metropolitan and Micropolitan Statistical Areas and are identified as either Metropolitan or Micropolitan. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. NECTAs are published for one or more cities or towns where applicable. ### NECTAName `NECTAName` refers to the official name given to the NECTAs which complements the `NECTACode` field value as defined above. For definition of NECTA, please refer to the `NECTACode` field definition above. ### NECTADivisionCode NECTA Division defines NECTAs (see definition under `NECTACode` field above) containing a single core with a population of at least 2.5 million that are subdivided to form smaller groupings of cities and towns referred to as NECTA Divisions. `NECTADivisionCode` is typically represented in a 5-digit value. ### NECTADivisionName `NECTADivisionName` refers to the official name given to the NECTA Divisions which complements the `NECTADivisionCode` field value as defined above. For definition of NECTA Division, please refer to the `NECTADivisionCode` field definition above. ### OldMSACode `OldMSACode` represents an obsolete value of MSA (metropolitan areas) that were defined by the OMB in 1990. With the introduction of CBSA definitions (see `CBSACode` field definition above), these MSA codes are replaced with the CBSA codes and names and not updated by the OMB since 1990. Therefore, the typical 4-digit value of `OldMSACode` will remain static in Census Plus product. ### OldMSAName `OldMSAName` refers to the official name given to the MSA (metropolitan areas) which complements the `OldMSACode` field value as defined above. For definition of MSA, please refer to the `OldMSACode` field definition above. ### StateCode `StateCode` refers to the census data that defines the official geographic (FIPS) code given to a US state. This field is a supplementary field given as part of Census Plus data. It can be used to complement the field value of `CensusCode`, in which when appended (in the format of `StateCode-CensusCode`) provides the old `CensusCode` value which represented the FIPS code. See `CensusCode` field value above for the current definition. ### TractCode `TractCode` represents the census data that defines geographic entities within counties, where each `TractCode` is typically a 6-digit code (including any leading zeros, and also two trailing zeros in the many cases in which the basic tract code has no suffix). A census `TractCode` may not be used more than once in a single county, but it may be used again in a different county in the same state or in a county of a different state. In Loqate, this value field is appended to `Thoroughfare` and `Premise` field. # Geocode Fields Source: https://docs.loqate.com/field-descriptions/geocode-fields [Click here](/support/geocode-accuracy-codes-demystified/) for more information on the geocode report fields Loqate provides. | Field | Description | | - | - | | **Latitude \[out]** | This field holds the WGS 84 latitude in decimal degrees format. | | **Longitude \[out]** | This field holds the WGS 84 longitude in decimal degrees format. | | **GeoAccuracy \[out]** | This field holds the [GeoAccuracy](/report-codes/geoaccuracy-code/) code. | | **GeoDistance \[out]** | This field holds the radius of accuracy in meters, giving an indication of the likely maximum distance between the given geocode and the physical location. Please note that this field is derived from and therefore dependent on the accuracy and coverage of the underlying reference data. | # HasSubPremise Source: https://docs.loqate.com/field-descriptions/hassubpremise [← Back to Address Fields](/field-descriptions/addfields) This page covers the logic and example scenarios for the `HasSubPremise` field, which is available in US PDH data. For the full set of address fields, see [Address Fields](/field-descriptions/addfields). ## Field values | Value | Meaning | | - | - | | `Yes` | The verified premise contains one or more sub premises (for example, apartments or suites). | | `No` | The verified record is itself a sub premise, or the verified premise contains no sub premises. | | blank | No sub premise information is available (typically when the address was only verified to thoroughfare or a lower level). | ## How `HasSubPremise` interacts with AVC The value of `HasSubPremise` should always be interpreted alongside the [AVC code](/field-descriptions/addfields). The table below summarises the common combinations. | AVC | Verification level | Typical `HasSubPremise` | Interpretation | | - | - | - | - | | `V4` | Verified to premise level | `Yes` | Premise verified and contains sub premises. | | `V4` | Verified to premise level | `No` | Premise verified and contains no sub premises. | | `V5` | Verified to sub premise level | `No` | Record is itself a sub premise, so it cannot contain further sub premises. | | `A5` | Ambiguous at sub premise level | `No` | Sub premise level record; no further sub premises to flag. | | `V3` | Verified to thoroughfare (street) level | blank | No sub premise information available. | ## Scenarios The following scenarios illustrate how the `HasSubPremise` flag behaves for different verification outcomes. ### Scenario 1: Verified premise level property that contains sub premises | Field | Value | | - | - | | `HasSubPremise` | `Yes` | | `AVC` | `V4` | | Verified address | `999 Baker Way San Mateo CA 94404 USA` | The property has been verified to premise level, so the AVC is `V4`. It also contains one or more sub premises, so `HasSubPremise` is set to `Yes`. ### Scenario 2: Verified sub premise level property | Field | Value | | - | - | | `HasSubPremise` | `No` | | `AVC` | `V5` | | Verified address | `999 Baker Way Ste 1 San Mateo CA 94404 USA` | The property has been verified as a sub premise, so the AVC is `V5`. A sub premise cannot itself contain further sub premises, so `HasSubPremise` is set to `No`. ### Scenario 3: Verified premise level property with incorrect sub premise data | Field | Value | | - | - | | `HasSubPremise` | `Yes` | | `AVC` | `V4` | | Verified address | `999 Baker Way Ste 21 San Mateo CA 94404 USA` | The property has been verified to premise level (AVC `V4`) because the supplied sub premise information was incorrect. The premise does contain sub premises, so `HasSubPremise` is set to `Yes`. ### Scenario 4: Verified premise level property with no sub premises | Field | Value | | - | - | | `HasSubPremise` | `No` | | `AVC` | `V4` | | Verified address | `121 Private Road 3697 Paradise TX 76073-4800 USA` | The property has been verified to premise level (AVC `V4`) and contains no sub premises, so `HasSubPremise` is set to `No`. ### Scenario 5: Ambiguous sub premise level property | Field | Value | | - | - | | `HasSubPremise` | `No` | | `AVC` | `A5` | | Verified address | `1 Chestnut St Ste 3Y Nashua NH 03060-9306 USA` | The AVC code of `A5` means there is more than one close reference data match at sub premise level. Because this is a sub premise level record, the sub premise does not contain further sub premises, so `HasSubPremise` is set to `No`. ### Scenario 6: No sub premise information | Field | Value | | - | - | | `HasSubPremise` | blank | | `AVC` | `V3` | | Verified address | `8055 veterans blvd redwoodcity ca usa` | The property was only verified to the thoroughfare (street) level, so no sub premise information is available and `HasSubPremise` is returned blank. # Field Descriptions Source: https://docs.loqate.com/field-descriptions/introduction ## Primary Data Fields > [card] [Address Fields](/field-descriptions/addfields/) > [card] [Unmatched Field](/field-descriptions/unmatched-field/) > [card] [Geocode Fields](/field-descriptions/geocode-fields/) > [card] [Data Enhancement](/field-descriptions/data-enhancement/) > [card] [Process Fields](/field-descriptions/objfeilds/) ## Server & Process Fields > [card] [processStatus](/field-descriptions/processstatus/) > [card] [serverStatus](/field-descriptions/serverStatus/) ## Certified Product Fields > [card] [CASS Fields](/support/cass2-output-field-descriptions/) > [card] [SERP Fields](/field-descriptions/serp-fields/) > [card] [AMAS Fields](/field-descriptions/amas-fields/) Documentation for [report codes can be found here](/report-codes/) # Process Fields Source: https://docs.loqate.com/field-descriptions/objfeilds Non-address fields that are either generated by the engine during processing or referenced from the country-specific configuration files are described below. These fields are returned alongside the Address and Report fields. Field descriptions for all processes can be accessed from [the main field descriptions menu](/field-descriptions/). | Field | Description | | - | - | | **MatchRuleLabel \[out]** | Loqate Engine uses a set of rules to match the input with the reference data. Each rule is identified by a match rule label. Please refer to the below links for more information regarding the Match Rules. - [Match Process](/available-processes/match-process/) - [Match Rule Syntax](/support/match-rules-syntax/) Possible values include: - `rlh` (Reflex Hash) - `rlfnpq` (Reflex filter, populate quick) - `rlfnp` (Normal Reflex filter and populate) - `rlhng` (Normal Reflex filter and populate with HashNG) - `1`, `1a`, `1ab`, …, `6` (Verify Match Rule name) - `1`, `2`, `3`, … (Reference Tool results) The `MatchRuleLabel` is mainly used for debugging and troubleshooting on case queries and issues. Customers are not expected to make use of this field within their integrations. | | **DuplicateInfo \[out]** | A single string indicating what is being removed from the original input (when `DuplicateHandlingFlag` is used). | | **HyphenClass \[out]** | A code of `A`, `B`, or `C` that identifies how a hyphen in a premise will be handled. | | **\_L \[out]** | A string providing an audit trail of parse, match, and formatting tools and options. Used only for debugging and troubleshooting. | # processStatus Source: https://docs.loqate.com/field-descriptions/processstatus | Code | Status | Description | | - | - | - | | `0` | `psOK` | The command completed normally. The accuracy score must be examined to determine result accuracy. | | `1` | `psException` | An exception occurred during processing, normally as a result of malformed input data. | | `2` | `psServerUninitialized` | The command could not be completed as the server has not yet been initialized. | | `3` | `psInvalidInputRecord` | The input record contains invalid data, often due to the supply of non-UTF8/Unicode data. | | `4` | `psError` | An error has been reported by loqate process, use `getLastError()` function in `lqtProcessResult` object to get error description. | # SERP Fields Source: https://docs.loqate.com/field-descriptions/serp-fields The table below displays the SERP verification codes currently available in the Loqate API. | Field | Definition | | - | - | | **SerpStatusEx** | `V` (Valid) `C` (Correctable) : Correctable fields will have been corrected to their right values in the output. `N` (Invalid) | | **Questionable** | `QR` (for "Questionable-Rural") `QU` (for "Questionable-Urban") Empty - It means that the address is not questionable. | | **Result** | `VALID` for valid addresses. Otherwise, internal error code. | | **GeneralDelivery** | This field is available when adding "SERP" to the Loqate engine. It identifies a General Delivery type address – Example value: `GD` | | **DeliveryInstallation** | This field is available when adding "SERP" to the Loqate engine. It contains the Station Information to direct mail to the proper postal installation for non-civic addresses. Example value: `STN A` | | **Route** | This field is available when adding "SERP" to the Loqate engine. It identifies a Route Address, such as Rural Route, Military Route. Example value: `RR 6` | | **AdditionalContent** | This field is available when adding "SERP" to the Loqate engine. Sometimes a site specification and compartment is assigned for delivery to a rural address that does not have a civic address. Example value: `SITE 6 COMP 10` | ## Notes For output field `RESULT`, it will either be `VALID`, or an address classification and series of three character codes indicating the status of individual address components. Each code will be a two-digit numeric that identify the address component plus one character status indicator. There can be many of these three character codes. For example a `RESULT` of `C17M` indicates: * `C` = Invalid Correctable Address * `17M` = The Suite Identifier is missing Another example, a `RESULT` of `N10I11I62M` indicates: * `N` = Invalid Non-Correctable Address * `10I` = Complete street information is Inconsistent/Incorrect * `11I` = Civic Number is Inconsistent/Incorrect * `62M` = Province is Missing Here are the classification, address components, and address components status: ### Address Classification | Code | Description | | - | - | | `VALID` | Valid address | | `C` | Invalid correctable address | | `N` | Invalid Non-Correctable Address | | `I` | Invalid Address | | `O` | Optional (correctable) | | `Q` | Questionable | ### Address Components | Code | Component | | - | - | | `00` | Complete Address | | `01` | Addressee and/or Additional Delivery Information | | `10` | Complete Street Information | | `11` | Civic number | | `12` | Civic number suffix | | `13` | Street name | | `14` | Street type | | `15` | Street direction | | `16` | Suite keyword | | `17` | Suite identifier | | `19` | Delivery Information | | `20` | Complete Route Service Information | | `22` | Route Service keyword | | `24` | Route Service identifier | | `30` | Complete PO Box/Bag Information | | `32` | PO Box/Bag keyword | | `34` | PO Box/Bag identifier | | `40` | Complete General Delivery Information | | `42` | General Delivery keyword | | `50` | Complete Delivery Installation Information | | `52` | Delivery Installation Area Name | | `54` | Delivery Installation Type | | `56` | Delivery Installation Qualifier | | `60` | Municipality | | `62` | Province | | `64` | Postal Code | | `81` | Typo | | `98` | Too Many Errors | | `99` | Correction does not fit | ### Component Status | Code | Description | | - | - | | `M` | Missing | | `I` | Inconsistent/Incorrect | | `T` | Typo | | (blank) | No status | # serverStatus Source: https://docs.loqate.com/field-descriptions/serverStatus | Code | Status | Description | | - | - | - | | `0` | `ssOK` | The library has been successfully initialized and ready to accept requests. | | `1` | `ssUninitialized` | The library has not yet been successfully initialized. | | `2` | `ssInvalidDataDirectory` | The supplied data directory does not contain a Global Knowledge Repository. | | `3` | `ssInvalidUnicodeFileVersion` | The installed `unicode.lfs` file is mismatched with the installed software. | | `4` | `ssInvalidCountryFileVersion` | The installed `country.lfs` file is mismatched with the installed software. | | `5` | `ssInvalidContextFileVersion` | The installed `context.lfs` file is mismatched with the installed software. | | `6` | `ssInvalidFormatFileVersion` | The installed `format.lfs` file is mismatched with the installed software. | | `7` | `ssInvalidLexiconFileVersion` | The installed lexicon file attempting to be opened is mismatched with the installed software. | | `8` | `ssInvalidReferenceFileVersion` | The installed lexicon file attempting to be opened is mismatched with the installed software. | | `9` | `ssException` | An exception was thrown. | | `10` | `ssError` | An error has been reported by loqate server, use `getLastError()` function in `lqtServer` object to get error description. | # Unmatched Field Source: https://docs.loqate.com/field-descriptions/unmatched-field The Unmatched field is used to place all the input data that cannot be parsed as part of an address. Generally Loqate will tend to assume that unidentified words are either Building or Organization names, but if it has a large degree of confidence that a particular item is not part of the address data it will place it into the `Unmatched` field, as in the example below. ![](https://mintcdn.com/loqate/6of5PNGnHDAqYvfh/images/unmatched-screenshot.png?fit=max\&auto=format\&n=6of5PNGnHDAqYvfh\&q=85\&s=033ebff3c408b07324c7518833927b0b) Other examples of unmatched values: * Details unknown * DO NOT APPLY * DO NOT ENTER * DO NOT SHIP TO THIS LOCATION * DO NOT USE * Empty * VARIOUS * VARIOUS LOCATIONS * All Locations * N A * NA * Not Applicable * Not Assigned * NOT AVAILABLE * Not Provided # Country Data Improvements Source: https://docs.loqate.com/getting-started/country-improvement-program Loqate have a unique process that brings together and combines multiple expert data sources to create **one best record** in the address and location hierarchy. We call this process the** Persistent Data Hierarchy, or PDH.** A country dataset is improved by using the PDH process to enhance reliability, improve the speed and quality of the location data, creates consistency, adds normalization, and resolves data errors. ### How it works 1. Loqate will source and evaluate the best sources for address and location data 2. Using our home-grown, expert system, the data is scanned and mapped into a standardized hierarchy 3. The completed dataset is then exported for use across all Loqate products ### Benefits of a single hierarchy The PDH process benefits customers in two ways: completeness and coverage. By blending multiple sources, the improvement process will complete missing fields, resolve component-level conflicts, and bring consistency and alignment across the regional hierarchy. For example, one source may state a value as a city, whereas another will identify it as a Village or smaller regional boundary. The PDH software will resolve this, and also enrich or fill any gaps that may be unique to each source. Coverage is is measured by the number of delivery-point records, which is maximized by having more sources. This is dependent on the quality of data already available in the market for each country. ### Coverage status We have now updated the Data Coverage [page](/data-coverage/introduction/) to include if a country has been through our PDH process. Measuring improvement We internally measure the improvements made by the PDH process when we complete it for a particular country. You may see a record returning a level 2 (locality level) prior to PDH and a level 4 (premise level) after PDH; these types of changes demonstrate a positive improvement due to better alignment and cleaner structures in the reference data. In cases where a record does the opposite, the enhanced dataset may be resolving a previously incorrect or false result. These changes are dependent on the amount of sample data available. ### Coverage & Completeness For countries using existing data sources, these are unlikely to show any big changes to the total number of deliverable records. Many improvements in datasets will be based around field/value alignments and corrections to the geography hierarchy. # Verify On-Premise Documentation Source: https://docs.loqate.com/getting-started/introduction **Welcome to the Loqate Technical Support Site for On-Premise Customers** Please choose a topic below or use the main menu to browse the site. > [card] [Getting Started](/getting-started/overview) > [card] [Release Info](/release-information/introduction) > [card] [Data Coverage](/data-coverage/introduction) > [card] [Request Support](/support/file-a-bug) > [card] [API Processes](/available-processes/introduction) > [card] [Field Descriptions](/field-descriptions/introduction) > [card] [Report Code Guides](/report-codes/introduction) > [card] [Demo](https://www.loqate.com/en-gb/demos/address-verification/) > [card] [CASS Demo](https://www.loqate.com/en-us/demos-us/address-verification/cass/) # Local API Install Options Source: https://docs.loqate.com/getting-started/local-api-install-options > [!NOTE] > > Loqate installers are available as multi-thread (`mt`) and single-thread (`st`) engines. ## Available Installers ### Windows x86 and x86\_64 ``` loqate_installer_mt_win_x86_vs2005.exe loqate_installer_mt_win_x64_vs2005.exe loqate_installer_mt_win_x86_vs2019.exe loqate_installer_mt_win_x64_vs2019.exe loqate_installer_mt_win_x64_vs2019_lfs64.exe ``` See [Dependencies](/getting-started/local-api-install-options#dependencies) section for details on installing dependencies from Microsoft. ### Linux x86 ``` loqate_installer_mt_linux_x86 loqate_installer_mt_linux_x86-cpp5 loqate_st_installer_x86 loqate_st_installer_x86-cpp5 ``` ### Linux x86\_64 ``` loqate_installer_mt_linux_x86_64 loqate_installer_mt_linux_x86_64-gcc7 loqate_st_installer_x86_64 loqate_st_installer_x86_64-gcc7l loqate_installer_mt_linux_x86_64-gcc7_lfs64 ``` ### AIX ``` loqate_installer_mt_aix61 loqate_installer_mt_aix71 loqate_installer_mt_aix72 loqate_st_installer_aix61 loqate_st_installer_aix71 loqate_st_installer_aix72 ``` ## Dependencies If using Windows without the correct library dependency installed, you may see the following error message: ![](https://mintcdn.com/loqate/wwkAPZOZpT3jkoyU/images/f73cc9a7-lqBatchError-300x118.png?fit=max\&auto=format\&n=wwkAPZOZpT3jkoyU\&q=85\&s=9dfaf26d46aecc04fc8add7d0bb781e6) Install the Visual C++ Redistributable package from Microsoft: [Download from Microsoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022) ## Customized Installs Each installer can be customized during installation using a settings file (default: `setup.ini`). ### Settings File Options All options are optional. | Option Name | Description | Installation Mode | | - | - | - | | `ProductName` | Custom name of product | All modes | | `ProductVersion` | Custom version name | All modes | | `ProductLogo` | Full path to custom product logo | GUI mode | | `ProductIcon` | Full path to custom product icon | Windows install | | `ShowLicense` | `yes` or `no` | GUI and commandline modes | | `LicenseFile` | Full path to custom license agreement text file | GUI and commandline modes | | `InstallDir` | Full path to the installation folder | All modes | | `Modules` | Modules to install | Silent mode | | `Samples` | Samples to install | Silent mode | | `SampleData` | `yes` or `no` | Silent mode | **Default InstallDir values:** * Windows: `C:\Loqate\` * Linux/Unix: `/opt/loqate` ### Settings File Tips * **Custom License:** Add a license text file, set `LicenseFile` to its location, and set `ShowLicense` to `yes` for graphical and command line installations * **Custom Logo:** Set `ProductLogo` to add a customized logo to graphical installations * **Custom Icon:** Set `ProductIcon` in Windows installations to add an icon to start menu shortcuts * **Modules (silent mode):** Options are `Java`, `.Net`, `Batch`, `Demo`, `InstallManager`, `Node`, `Central`, and `All`. C++ is always installed * **Samples (silent mode):** Options are `C++`, `Java`, `.Net`, `Batch`, and `All` * **SampleData (silent mode):** Determines whether sample US data is installed ### Settings File Examples **Linux GUI/commandline install:** ```ini theme={null} ProductName=Loqate ProductVersion=2012Q1 ProductLogo=/home/user/logo.png ShowLicense=Yes LicenseFile=/home/user/license.txt InstallDir=/opt/loqate ``` **Windows GUI install:** ```ini theme={null} ProductName=Loqate ProductVersion=2012Q1 ProductLogo=C:\Users\user\logo.png ProductIcon=C:\Users\user\icon.ico ShowLicense=Yes LicenseFile=C:\Users\user\license.txt InstallDir=C:\Loqate ``` **Linux silent install:** ```ini theme={null} InstallDir=/opt/loqate Modules=Java, Batch, InstallManager Samples=C++, Java, Batch SampleData=Yes ``` **Windows silent install:** ```ini theme={null} InstallDir=C:\Loqate Modules=Java, Batch, InstallManager Samples=C++, Java, Batch SampleData=Yes ``` ## Installation Modes The Windows and Linux installers can be run in graphical, console, or silent mode. The settings file is optional in these modes. The settings file is specified by the `--setup-file` option. If no settings file is specified, the installer will look for a file named `setup.ini` in the same folder as the installer. If no such file exists, the installer will run with no settings file. ### Silent Mode Defaults Running in silent mode with no settings file will use these default options: ``` InstallDir=C:\Program Files\Loqate (Windows) InstallDir=/opt/loqate (Linux/Unix) Modules=all Samples=all SampleData=yes ``` ### Windows x86 Default mode is graphical. ```bash theme={null} # Basic graphical installation loqate_installer_mt_win_x86_vs2005.exe # With settings file loqate_installer_mt_win_x86_vs2005.exe --setup-file # Silent mode loqate_installer_mt_win_x86_vs2005.exe --mode silent # Silent mode with settings file loqate_installer_mt_win_x86_vs2005.exe --mode silent --setup-file ``` ### Windows x86\_64 Default mode is graphical. ```bash theme={null} # Basic graphical installation loqate_installer_mt_win_x64_vs2005.exe # With settings file loqate_installer_mt_win_x64_vs2005.exe --setup-file # Silent mode loqate_installer_mt_win_x64_vs2005.exe --mode silent # Silent mode with settings file loqate_installer_mt_win_x64_vs2005.exe --mode silent --setup-file ``` ### Linux x86 Default mode is console, standard mode is graphical. ```bash theme={null} # Basic console installation loqate_installer_mt_linux_x86 # With settings file loqate_installer_mt_linux_x86 --setup-file # Graphical mode loqate_installer_mt_linux_x86 --mode standard # Graphical mode with settings file loqate_installer_mt_linux_x86 --mode standard --setup-file # Silent mode loqate_installer_mt_linux_x86 --mode silent # Silent mode with settings file loqate_installer_mt_linux_x86 --mode silent --setup-file ``` ### Linux x86\_64 Default mode is console, standard mode is graphical. ```bash theme={null} # Basic console installation loqate_installer_mt_linux_x86_64 # With settings file loqate_installer_mt_linux_x86_64 --setup-file # Graphical mode loqate_installer_mt_linux_x86_64 --mode standard # Graphical mode with settings file loqate_installer_mt_linux_x86_64 --mode standard --setup-file # Silent mode loqate_installer_mt_linux_x86_64 --mode silent # Silent mode with settings file loqate_installer_mt_linux_x86_64 --mode silent --setup-file ``` ### AIX Default mode is console, standard mode is graphical. ```bash theme={null} # Basic console installation loqate_installer_ # With settings file loqate_installer_ --setup-file # Graphical mode loqate_installer_ --mode standard # Graphical mode with settings file loqate_installer_ --mode standard --setup-file # Silent mode loqate_installer_ --mode silent # Silent mode with settings file loqate_installer_ --mode silent --setup-file ``` # Loqate API Architecture Source: https://docs.loqate.com/getting-started/loqate-api-architecture ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Loqate-API-Architecture-NB.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=7ebd9df8e83e8361fcf6d3a5636bf855) # Getting Started Source: https://docs.loqate.com/getting-started/overview Use the sections and links below to guide you through how to install and run the Loqate Verify & Geocode engine and data on your own server. > [!NOTE] > > Documentation for all web services and the Cloud API, including our type-ahead address [Capture service](/our-services/address-capture/overview/), can be [found on the main Loqate website](https://www.loqate.com/en-gb/address-capture/). Available videos on getting started can be found [here](/tutorials/loqate-video-tutorials/). ## Useful Information Before You Start > [card] [Supported Platforms](/getting-started/platforms/) > [card] [Minimum System Requirements](/getting-started/system-requirements/introduction/) > [card] [API Architecture](/getting-started/loqate-api-architecture/) > [card] [How We Geocode An Address](/support/geocode-accuracy-codes-demystified/) > [card] [Country Data Improvements](/getting-started/country-improvement-program/) ## Understanding Your Results > [card] [Verify Address Fields](/field-descriptions/addfields/) > [card] [Geocode Fields](/field-descriptions/geocode-fields/) > [card] [Server Options](/documentation/server-options/) > [card] [Output Report Codes](/report-codes/introduction/) ## Installing & Integrating Loqate > [card] [Installing the API](/tutorials/local-install-guide/) > [card] [Downloading & Updating Datasets](/installers/data-installation-and-update-process/) > [card] [MD5 Hash Files Guide](/support/md5-hash-values-guide/) > [card] [API Integration](/support/integration/) > [card] [API Install Options](/getting-started/local-api-install-options/) > [card] [Interactive Test Client](/support/lqtinter-guide/) > [card] [Address Processing Functions](/available-processes/introduction/) > [card] [Sample Code Library](/tutorials/sample-code/) > [card] [Using Batch (Command Line)](/support/batch-processor/) > [card] [Using Transliteration](/support/character-scripts/) ## Additional Products & Datasets > [card] [CASS Certified Processing (USA)](/support/usa-cass-v2/) > [card] [AMAS Certified Processing (Australia)](/support/address-matching-approval-system-amas/) > [card] [SERP Certified Processing (Canada)](/local-apis/serp-overview/) > [card] [Enhanced Dataset](/field-descriptions/data-enhancement/) > [card] [Worldwide Geographic Data Hierarchy](/support/geographic-data-hierachy/) # Supported Platforms Source: https://docs.loqate.com/getting-started/platforms For the latest supported platforms, please see the [most recent release notes](/release-information/). ## Core Platforms Supported > [card] [Windows 32-bit](/getting-started/system-requirements/win32bit/) > [card] [Windows 64-bit](/getting-started/system-requirements/win64bit/) > [card] [Linux 64-bit](/getting-started/system-requirements/linux64bit/) > [card] [AIX](/getting-started/system-requirements/aix/) ## Retiring support for older platforms To ensure that Loqate can continue to provide timely support for the latest and most used platforms, we will begin to retire older or unsupported platform versions. Notifications regarding the retirement of any platform or platform version will be published at least one major release in advance. # AIX Source: https://docs.loqate.com/getting-started/system-requirements/aix The Loqate library is available as a shared object on the following AIX platforms: ### loqate\_installer\_aix | Platform | Version | Build Compiler | Library Dependencies | | - | - | - | - | | **AIX** | 5.3 and above | IBM XL C/C++ Enterprise Edition V8.0 for AIX | libC.a(shr\_64.o) libC.a(shr2\_64.o) libC.a(ansi\_64.o) libc.a(shr\_64.o) libC.a(ansicore\_64.o) libc\_r.a(shr\_64.o) libC.a(shrcore\_64.o) libC.a(shr3\_64.o) | # System Requirements Source: https://docs.loqate.com/getting-started/system-requirements/introduction ## Minimum Specifications * 8GB RAM * 100GB RAIDed hard-disk space. (Note: post-installation size without installer or package files. During installation need around 30-50% more.) * 3GHz multi-core CPU * 64bit OS ## Recommended Specification * 16GB RAM or more * 100GB RAIDed/SSD space or more\* (Note: post-installation size without installer or package files. During installation need around 30-50% more.) * 3GHz multi-core CPU * 64bit OS # Linux 64-bit Source: https://docs.loqate.com/getting-started/system-requirements/linux64bit The Loqate library is available as a shared object on the following Linux platforms: | Platform | Version | Build Compiler | C/C++ Library | | - | - | - | - | | **SUSE (x64)** | 10 | gcc 4.1.2 | libstdc++.so.6, libc.so.6 | | **SUSE (x64)** | 11 | gcc 4.1.2 | libstdc++.so.6, libc.so.6 | | RHEL x64 | gcc version | glibc | libstdc++.so | | - | - | - | - | | **RHEL6** | 4.4.7 | 2.14 | 6.0.19 | | **RHEL7** | 4.8.5 | 2.17-326.el7\_9 | 6.0.19 | | **RHEL8** | 8.5.0 | 2.28-189.5.el8\_6 | 6.0.25 | | **RHEL9** | 11.2.1 | 2.34-28.el9\_0.2 | 6.0.29 | | Ubuntu (x64) | gcc version | glibc | libstdc++.so | | - | - | - | - | | **ubuntu14.04** | 4.8.4 | 2.19 | 6.0.19 | | **ubuntu16.04** | 5.4.0 | 2.23 | 6.0.21 | | **ubuntu18.04** | 7.5.0 | 2.27 | 6.0.25 | | **ubuntu20.04** | 9.4.0 | 2.31 | 6.0.28 | | **ubuntu22.04** | 11.2.0 | 2.35 | 6.0.30 | # Windows 32-bit Source: https://docs.loqate.com/getting-started/system-requirements/win32bit The Loqate library is available as a DLL on the following Windows platforms: | Platform | Version | Build Compiler | Service Pack | C/C++ Library | | - | - | - | - | - | | **Windows 10 (x86)** | All | Visual Studio 2005 | n/a | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x86)** | Standard Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x86)** | Web Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x86)** | Enterprise Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x86)** | Standard Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x86)** | Web Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x86)** | Enterprise Edition | Visual Studio 2005 | SP 1 | msvcp80.dll, msvcr80.dll | [Back to System Requirements](/getting-started/system-requirements/) # Windows 64-bit Source: https://docs.loqate.com/getting-started/system-requirements/win64bit The Loqate library is available as a DLL on the following Windows platforms: | Platform | Version | Build Compiler | Service Pack | C/C++ Library | | - | - | - | - | - | | **Windows 7 (x64)** | | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows 8.1 (x64)** | | Visual Studio 2019 | n/a | msvcp80.dll, msvcr80.dll | | **Windows 10 (x64)** | All Versions | Visual Studio 2019 | n/a | msvcp80.dll, msvcr80.dll | | **Windows 11 (x64)** | All Versions | Visual Studio 2019 | n/a | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x64)** | Standard Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x64)** | Web Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 (x64)** | Enterprise Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x64)** | Standard Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x64)** | Web Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2008 R2 (x64)** | Enterprise Edition | Visual Studio 2019 | SP 1 | msvcp80.dll, msvcr80.dll | | **Windows Server 2012 R2 (x64)** | Standard Edition | Visual Studio 2019 | SP2 | msvcp80.dll, msvcr80.dll | | **Windows Server 2012 R2 (x64)** | Web Edition | Visual Studio 2019 | SP2 | msvcp80.dll, msvcr80.dll | | **Windows Server 2012 R2 (x64)** | Enterprise Edition | Visual Studio 2019 | SP2 | msvcp80.dll, msvcr80.dll | | **Windows Server 2016 (x64)** | Standard | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2016 (x64)** | Datacenter | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2019 (x64)** | Standard | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2019 (x64)** | Datacenter | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2022 (x64)** | Standard | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2022 (x64)** | Datacenter | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | | **Windows Server 2022 (x64)** | Datacenter - Azure | Visual Studio 2019 | | msvcp80.dll, msvcr80.dll | # Verify Helm Configuration Source: https://docs.loqate.com/helm/configuration Configure country-specific deployments, certified datasets, and resource allocation ## Docker Image Versions Specify image tags for Verify components. **Helmfile (Unix/Linux):** ```bash theme={null} export LOQATE_INSTALLMANAGER_VERSION="image-tag" export LOQATE_QUERY_COORDINATOR_VERSION="image-tag" export LOQATE_SPATIAL_API_VERSION="image-tag" ``` **Helmfile (Windows):** ```powershell theme={null} $env:LOQATE_INSTALLMANAGER_VERSION="image-tag" $env:LOQATE_QUERY_COORDINATOR_VERSION="image-tag" $env:LOQATE_SPATIAL_API_VERSION="image-tag" ``` **Helm:** ```bash theme={null} helm install component loqate/component --set image.tag=image-tag ``` Contact your Loqate representative for available image tags. ## Country-Specific Deployments Deploy dedicated Spatial-API instances for high-traffic countries to optimize performance and enable independent scaling. ### Why Use Country-Specific Deployments * **Better performance:** Dedicated resources for frequently queried countries * **Flexible scaling:** Scale each country independently based on traffic * **Cost optimization:** Allocate resources where needed ### Configuration Set `verify.dataset` to the ISO 3166-2 country code. Keep a `row` (rest of world) deployment for other countries. **Example: United Kingdom deployment** ```bash theme={null} helm install -n loqate sa-gb loqate/spatial-api \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass \ --set app.memberlistService=memberlist.loqate.svc \ --set verify.dataset=gb ``` **Example with custom storage path:** ```bash theme={null} helm install -n loqate sa-gb loqate/spatial-api \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass \ --set storage.path=/custom/data/path \ --set app.memberlistService=memberlist.loqate.svc \ --set verify.dataset=gb ``` **Common Country Codes:** | Country | Code | | - | - | | United States | `us` | | United Kingdom | `gb` | | Canada | `ca` | | Australia | `au` | | Germany | `de` | | France | `fr` | | Rest of World (catch-all) | `row` | ## Certified Datasets Verify supports postal authority-certified validation: * **CASS** - United States (Coding Accuracy Support System) * **SERP** - Canada (Software Evaluation and Recognition Program) * **AMAS** - Australia (Address Matching Approval System) ### Requirements * License key with certified features enabled * Certified libraries (downloaded automatically to `lib64` folder) * Spatial-API configured for the certified country > [!WARNING] > > **CASS Restriction:** CASS data cannot be downloaded from locations outside the United States due to legal requirements. ### Example: AMAS (Australia) ```bash theme={null} helm install -n loqate spatial-api-au loqate/spatial-api \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass \ --set app.memberlistService=memberlist.loqate.svc \ --set verify.dataset=au ``` The certified engine activates automatically when licensed libraries are present. ## Premium Datasets Premium datasets provide enhanced data quality for: * **France** * **Ireland** * **United States** ### Deployment Options **Option 1: Dedicated deployments (recommended for high volume)** ```bash theme={null} # France helm install -n loqate sa-fr loqate/spatial-api \ --set verify.dataset=fr \ # ... other settings # Ireland helm install -n loqate sa-ie loqate/spatial-api \ --set verify.dataset=ie \ # ... other settings ``` **Option 2: Single rest-of-world deployment** Set `verify.dataset=row` to handle all premium countries with one deployment. Simpler but less flexible scaling. ### Premium US Resources The premium US dataset requires more resources: ```yaml theme={null} resources: requests: memory: "8Gi" cpu: "2" limits: memory: "16Gi" cpu: "4" ``` Apply via Helm: ```bash theme={null} --set resources.requests.memory=8Gi \ --set resources.requests.cpu=2 \ --set resources.limits.memory=16Gi \ --set resources.limits.cpu=4 ``` ## Resource Allocation Configure CPU and memory based on expected traffic. ### Recommended Sizing | Traffic Level | Memory Request | CPU Request | Memory Limit | CPU Limit | | - | - | - | - | - | | Low (under 100 req/min) | 2Gi | 0.5 | 4Gi | 1 | | Medium (under 1000 req/min) | 4Gi | 1 | 8Gi | 2 | | High (under 5000 req/min) | 8Gi | 2 | 16Gi | 4 | | Premium US | 8Gi | 2 | 16Gi | 4 | ### Example Configuration **Via values file:** ```yaml theme={null} resources: requests: memory: "4Gi" cpu: "1" limits: memory: "8Gi" cpu: "2" ``` **Via Helm:** ```bash theme={null} --set resources.requests.memory=4Gi \ --set resources.requests.cpu=1 \ --set resources.limits.memory=8Gi \ --set resources.limits.cpu=2 ``` Start conservative and adjust based on Prometheus metrics. ## AI Parser (Optional) Enable AI-enhanced parsing for improved accuracy with unstructured addresses. ### Requirements * Separate persistent storage (at least 4Gi) * Additional resources for TensorFlow Serving and AI Parser components ### Enable AI Parser **In helmfile, add to QueryCoordinator values:** ```yaml theme={null} app: allow_aiparser: true ``` **Configure AI storage:** ```bash theme={null} # Unix export LOQATE_AIPARSER_STORAGE_PATH="/opt/loqate/ai-models" # Windows $env:LOQATE_AIPARSER_STORAGE_PATH="C:\loqate\ai-models" ``` **Uncomment AI Parser sections in helmfile and apply:** ```bash theme={null} helmfile apply # Unix helmfile sync # Windows ``` See the AI Parser section in helmfile.yaml for detailed configuration. ## Next Steps * [Usage](/helm/usage) - Learn management and monitoring commands * [Troubleshooting](/helm/troubleshooting) - Resolve common issues * [Quick Start](/helm/quick-start) - Installation guide # Verify Helm Charts Overview Source: https://docs.loqate.com/helm/overview Deploy Verify on Kubernetes using Helm charts for scalable, cloud-native address verification ## What's Included Deploy Verify with production-tested Helm charts that include: * **Container images:** All Verify components packaged for Kubernetes * **Helm charts:** Pre-configured deployment manifests * **Reference data:** Global Knowledge Repository with 245+ countries * **Observability:** OpenTelemetry traces, Prometheus metrics, and stdout logging ## Architecture Components Verify uses a microservices architecture optimized for Kubernetes: * **InstallManager:** Downloads reference data to persistent storage * **Memberlist:** Coordinates communication between components * **QueryCoordinator:** Routes requests to appropriate Spatial-API instances * **Spatial-API:** Processes verification requests using country-specific data Deploy Spatial-API instances for high-traffic countries and a catch-all instance for the rest of the world, enabling independent scaling per region. ## Verify Capabilities * **Global Knowledge Repository (GKR):** Proprietary address database covering 245+ countries and territories * **Parsing engine:** Context-aware parsing rules that structure unstructured address data * **High performance:** Process millions of records per hour * **Transliteration:** Convert between character sets across 8 scripts (Cyrillic, Hellenic, Hebrew, Kanji, Simplified Chinese, Arabic, Thai, Hangul) ## Deployment Benefits * **Control:** Run in your own cloud with your security policies * **Scalability:** Auto-scale components based on demand * **Cost optimization:** Deploy only what you need * **Visibility:** Built-in monitoring and observability tools ## Routing Options * **Kubernetes Ingress (default):** Standard ingress controller integration * **Istio:** Advanced service mesh for sophisticated traffic management ## Scaling Options * **HPA (default):** Kubernetes Horizontal Pod Autoscaler based on CPU/memory * **KEDA:** Event-driven autoscaling with custom metrics ## Security For vulnerability disclosure or security findings, contact [support@loqate.com](mailto:support@loqate.com). ## Next Steps * [Quick Start](/helm/quick-start) - Deploy Verify in minutes * [Configuration](/helm/configuration) - Customize your deployment * [Usage](/helm/usage) - Manage and monitor your installation # Verify Helm Quick Start Source: https://docs.loqate.com/helm/quick-start Deploy Verify to Kubernetes in minutes using Helmfile ## Prerequisites Before installing, ensure you have: * **Kubernetes** v1.23 or higher * **Helm** v3.7.0 or higher * **Helmfile** v0.144.0 or higher (recommended) * **Docker Hub account** with access granted by Loqate * **Loqate license key** (API key) * **Persistent storage** - At least 250Gi ReadWriteMany (RWX) volume > [!NOTE] > > **Recommended tools:** Istio v1.11.4+, KEDA v2.4+, Prometheus v2.34.0+ for advanced features ## Step 1: Prepare Your Environment Create a working directory and set environment variables. **Unix/Linux:** ```bash theme={null} # Create directory mkdir -p /opt/loqate/lqtcharts cd /opt/loqate/lqtcharts # Set credentials (required) export LICENSE_KEY="your-api-key" export DOCKER_USERNAME="your-docker-username" export DOCKER_PASSWORD="your-docker-password" # Set custom data path (optional) export LOQATE_NFS_SHARE="/opt/loqate/data" # Use existing PVC (optional) export CLAIM_OVERRIDE="your-pvc-name" ``` **Windows (PowerShell):** ```powershell theme={null} # Create directory New-Item -Path "\loqate\lqtcharts" -ItemType "Directory" Set-Location "\loqate\lqtcharts" # Set credentials (required) $env:LICENSE_KEY="your-api-key" $env:DOCKER_USERNAME="your-docker-username" $env:DOCKER_PASSWORD="your-docker-password" # Set custom data path (optional) $env:LOQATE_NFS_SHARE="/run/desktop/mnt/host/c/loqate/data" # Use existing PVC (optional) $env:CLAIM_OVERRIDE="your-pvc-name" ``` > [accordion] Storage Configuration Options > > **Default behavior:** Creates a Persistent Volume (PV) and Persistent Volume Claim (PVC) using host filesystem at the path specified by `LOQATE_NFS_SHARE`. > > **Custom data path:** Set `LOQATE_NFS_SHARE` to your desired storage location. > > **Existing PVC:** Set `CLAIM_OVERRIDE` to use a pre-configured PVC for network storage. Skip `LOQATE_NFS_SHARE` if using this option. ## Step 2: Download Helmfile **Unix/Linux:** ```bash theme={null} wget https://charts.loqate.com/helmfile.yaml -O helmfile.yaml ``` **Windows (PowerShell):** ```powershell theme={null} Invoke-WebRequest https://charts.loqate.com/helmfile.yaml -OutFile helmfile.yaml ``` ## Step 3: Install Verify **Unix/Linux:** ```bash theme={null} helmfile apply ``` **Windows (PowerShell):** ```powershell theme={null} helmfile sync ``` The installation will: 1. Create the `loqate` namespace 2. Pull container images from Docker Hub 3. Deploy Memberlist, QueryCoordinator, and Spatial-API 4. Start InstallManager to download reference data > [!WARNING] > > Data download takes several hours and requires at least 250Gi storage for the full dataset. ## Step 4: Monitor Installation Progress Check pod status: ```bash theme={null} kubectl get pods -n loqate ``` Expected output during installation: ``` NAME READY STATUS RESTARTS AGE installmanager-xxxxx 0/1 Running 0 2m memberlist-xxxxx 1/1 Running 0 2m querycoordinator-xxxxx 0/1 Running 0 2m spatial-api-xxxxx 0/1 Running 0 2m ``` Monitor data download: ```bash theme={null} kubectl logs -f installmanager-xxxxx -n loqate ``` Installation is complete when you see `Edit complete` in the logs. ## Step 5: Test Your Installation Open a port forward: ```bash theme={null} kubectl port-forward -n loqate svc/querycoordinator 8900:8900 ``` **Test version endpoint (Unix/Linux):** ```bash theme={null} curl -X GET http://localhost:8900/api/version ``` Expected response: ```json theme={null} {"version":"2.xx.x.xxxxx-xxxxxxx"} ``` **Test verification (Unix/Linux):** ```bash theme={null} curl -X POST http://localhost:8900/verify \ -H "Content-Type: application/json" \ -d '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}' ``` Successful response includes validated address with AVC and AQI scores. > [accordion] Windows PowerShell Commands > > **Test version:** > > ```powershell theme={null} > Invoke-WebRequest -Method GET http://localhost:8900/api/version > ``` > > **Test verification:** > > ```powershell theme={null} > Invoke-WebRequest http://localhost:8900/verify -Method POST ` > -ContentType "application/json" ` > -Body '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}' > ``` ## Download Subset of Datasets To reduce storage and download time, install only specific countries: 1. Create `silent.txt` file: ``` gbgkey=your-api-key datachoice=selectcountries countries=USA,GBR,CAN ``` 2. Create ConfigMap: ```bash theme={null} kubectl create configmap installmanager-config \ --from-file=silent.txt=silent.txt \ -n loqate ``` 3. Update InstallManager values to reference the ConfigMap 4. Rerun helmfile ## Troubleshooting Installation **Pods not starting:** Check logs: ```bash theme={null} kubectl logs pod-name -n loqate ``` Common issues: invalid license key, Docker Hub authentication failed, insufficient storage. **Data download slow:** Normal for full dataset. Monitor with: ```bash theme={null} kubectl logs -f installmanager-xxxxx -n loqate ``` **Connection refused on port forward:** Ensure port forward is running and QueryCoordinator pod shows `1/1` ready status. See [Troubleshooting](/helm/troubleshooting) for more solutions. ## Next Steps * [Configuration](/helm/configuration) - Add country-specific deployments and certified datasets * [Usage](/helm/usage) - Learn management commands and monitoring * [Troubleshooting](/helm/troubleshooting) - Resolve common issues # Troubleshooting Verify Source: https://docs.loqate.com/helm/troubleshooting Common errors and solutions for Verify Helm deployment issues ## Memberlist Errors ### Symptoms Pod logs show: * `No private IP address found, and explicit IP not provided` * `(*Memberlist).UpdateStatus(0x0, 0x0, 0x0, 0x1)` ### Solution Set `memberlist.useAddrRef` to `true` for QueryCoordinator and Spatial-API. **Via values file:** ```yaml theme={null} memberlist: useAddrRef: true ``` **Via Helm:** ```bash theme={null} --set memberlist.useAddrRef=true ``` ## Data Installation Errors ### Symptoms * Pod logs show: `...is not a valid Global Knowledge Repository path` * InstallManager pod never completes * Spatial-API pods fail to start ### Solutions **1. Verify installation completed** Check InstallManager logs for: ``` Completed installing the data packs. Datapack installation was successfull. Edit complete ``` If missing, data installation didn't finish. **2. Check storage space** ```bash theme={null} kubectl logs installmanager-xxxxx -n loqate | grep "Space available" ``` If insufficient: * Increase PV size * Install subset of datasets (see [Quick Start](/helm/quick-start)) **3. Retry installation** Delete and reinstall InstallManager: ```bash theme={null} helm delete installmanager -n loqate helm install installmanager loqate/installmanager \ --set licenseKey=your-key \ # ... other settings ``` **4. Install minimal dataset** Create `silent.txt` with fewer countries, test, then expand. ## Request Processing Errors ### Symptoms API requests fail with: * `No spatialapi available` * `Failed to process` ### Solution: Restart Pods **Check pod status:** ```bash theme={null} kubectl get pods -n loqate ``` **If pods show 0/1 (not ready):** Delete the pod - Kubernetes will recreate it: ```bash theme={null} kubectl delete pod pod-name -n loqate ``` Wait 3 minutes and test again. **If all pods show 1/1 but errors persist:** Restart in this order: 1. Delete Spatial-API pod 2. Wait 3 minutes, test 3. If still failing, delete QueryCoordinator pod 4. Wait 3 minutes, test 5. If still failing, delete Spatial-API pod again ```bash theme={null} kubectl delete pod spatial-api-xxxxx -n loqate # Wait 3 minutes, test kubectl delete pod querycoordinator-xxxxx -n loqate # Wait 3 minutes, test ``` ### Solution: Reinstall Charts If pod restarts don't work: **1. List releases:** ```bash theme={null} helm list -n loqate ``` **2. Delete failing release:** ```bash theme={null} helm delete release-name -n loqate ``` **3. Reinstall** (see [Configuration](/helm/configuration) for commands) **4. Verify pods are running:** ```bash theme={null} kubectl get pods -n loqate ``` Wait 3 minutes after pods show 1/1, then test. ## Connection Issues ### Port Forward Not Working **Symptoms:** * `Connection refused` on localhost:8900 * Timeout errors **Solutions:** 1. Verify port forward is running (command doesn't terminate) 2. Check QueryCoordinator pod is ready: ```bash theme={null} kubectl get pods -n loqate # querycoordinator should show 1/1 ``` 3. Try different local port: ```bash theme={null} kubectl port-forward -n loqate svc/querycoordinator 9000:8900 # Then test localhost:9000 ``` 4. Check firewall not blocking localhost ## Image Pull Errors ### Symptoms Pods show `ImagePullBackOff` or `ErrImagePull` ### Solutions **1. Verify Docker Hub credentials:** ```bash theme={null} kubectl get secret -n loqate # Should show registry credentials ``` **2. Test Docker Hub access:** ```bash theme={null} docker login # Use your Docker Hub credentials ``` **3. Recreate image pull secret:** ```bash theme={null} kubectl delete secret regcred -n loqate kubectl create secret docker-registry regcred \ --docker-server=https://index.docker.io/v1/ \ --docker-username=your-username \ --docker-password=your-password \ -n loqate ``` **4. Verify Loqate repository access** Contact your Loqate representative to confirm your Docker Hub ID has been granted access. ## Performance Issues ### Slow Response Times **Check resource limits:** ```bash theme={null} kubectl describe pod pod-name -n loqate | grep -A 5 "Limits" ``` If CPU/memory limits are being hit: * Increase resource limits in values file * See [Configuration](/helm/configuration) for sizing guidelines **Check storage performance:** Slow storage impacts response times. Consider: * Faster storage class (SSD over HDD) * Local storage over network storage ### High Memory Usage Normal for large datasets. Ensure appropriate limits: * Standard datasets: 4-8Gi * Premium US: 8-16Gi ## Collecting Diagnostic Information If issues persist, collect diagnostic data before contacting support: ```bash theme={null} # Pod logs kubectl logs pod-name -n loqate > pod-logs.txt # Pod description kubectl describe pod pod-name -n loqate > pod-describe.txt # Events kubectl get events -n loqate --sort-by='.lastTimestamp' > events.txt # Resource usage kubectl top pods -n loqate > resource-usage.txt ``` ## Contact Support If issues persist after trying these solutions, contact [support@loqate.com](mailto:support@loqate.com) with: * Description of the issue * Steps already attempted * Diagnostic logs * Kubernetes version and environment details ## Next Steps * [Usage](/helm/usage) - Learn management commands * [Configuration](/helm/configuration) - Optimize your deployment * [Quick Start](/helm/quick-start) - Review installation steps # Managing Verify Source: https://docs.loqate.com/helm/usage Helm and Helmfile commands for managing, monitoring, and testing your Verify deployment ## Helmfile Management Helmfile simplifies managing multiple Helm releases. ### Install or Update ```bash theme={null} helmfile apply # Unix/Linux helmfile sync # Windows ``` ### Uninstall All Releases ```bash theme={null} helmfile destroy ``` ### List Releases ```bash theme={null} helmfile list ``` ### Update Specific Release ```bash theme={null} helmfile -l name=release-name apply ``` ## Helm Management Direct control over individual releases. ### Add Loqate Repository ```bash theme={null} helm repo add loqate https://charts.loqate.com helm repo update ``` ### Install Components **InstallManager:** ```bash theme={null} helm install installmanager loqate/installmanager \ -n loqate \ --set licenseKey=your-key \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass ``` **Memberlist:** ```bash theme={null} helm install memberlist loqate/memberlist \ -n loqate \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass ``` **QueryCoordinator:** ```bash theme={null} helm install querycoordinator loqate/querycoordinator \ -n loqate \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass \ --set app.memberlistService=memberlist.loqate.svc ``` **Spatial-API:** ```bash theme={null} helm install spatial-api loqate/spatial-api \ -n loqate \ --set imageCredentials.username=docker-user \ --set imageCredentials.password=docker-pass \ --set app.memberlistService=memberlist.loqate.svc \ --set verify.dataset=row ``` ### Upgrade Release ```bash theme={null} helm upgrade release-name loqate/chart-name \ -n loqate \ --set key=value ``` ### Uninstall Release ```bash theme={null} helm uninstall release-name -n loqate ``` ### List Releases ```bash theme={null} helm list -n loqate ``` ## Testing Verify ### Port Forward to QueryCoordinator ```bash theme={null} kubectl port-forward -n loqate svc/querycoordinator 8900:8900 ``` ### Version Check **Unix/Linux:** ```bash theme={null} curl http://localhost:8900/api/version ``` **Windows:** ```powershell theme={null} Invoke-WebRequest -Method GET http://localhost:8900/api/version ``` Expected response: ```json theme={null} {"version":"2.xx.x.xxxxx-xxxxxxx"} ``` ### Verify Request **Unix/Linux:** ```bash theme={null} curl -X POST http://localhost:8900/verify \ -H "Content-Type: application/json" \ -d '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}' ``` **Windows:** ```powershell theme={null} Invoke-WebRequest http://localhost:8900/verify -Method POST ` -ContentType "application/json" ` -Body '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}' ``` Successful response includes validated address with AVC and AQI scores. ## Monitoring ### Pod Status ```bash theme={null} kubectl get pods -n loqate ``` All pods should show `1/1` in the READY column (except InstallManager which shows `0/1` Completed). ### Pod Logs ```bash theme={null} kubectl logs pod-name -n loqate kubectl logs -f pod-name -n loqate # Follow logs ``` ### Resource Usage ```bash theme={null} kubectl top pods -n loqate ``` ### Recent Events ```bash theme={null} kubectl get events -n loqate --sort-by='.lastTimestamp' ``` ## Scaling ### Manual Scaling ```bash theme={null} kubectl scale deployment deployment-name --replicas=3 -n loqate ``` ### Horizontal Pod Autoscaler (HPA) Configure in your values file: ```yaml theme={null} autoscaling: enabled: true minReplicas: 2 maxReplicas: 10 targetCPUUtilizationPercentage: 80 ``` Apply via Helm: ```bash theme={null} --set autoscaling.enabled=true \ --set autoscaling.minReplicas=2 \ --set autoscaling.maxReplicas=10 ``` ### KEDA (Event-Driven Autoscaling) See [Configuration](/helm/configuration) for KEDA setup. ## Configuration Override ### Single Value ```bash theme={null} --set key=value ``` ### Multiple Values ```bash theme={null} --set key1=value1 --set key2=value2 ``` ### From Custom Values File ```bash theme={null} helm install release-name loqate/chart-name \ -n loqate \ -f custom-values.yaml ``` ## Complete Cleanup ### Remove All Resources **Using Helmfile:** ```bash theme={null} helmfile destroy kubectl delete namespace loqate ``` **Using Helm:** ```bash theme={null} helm uninstall installmanager -n loqate helm uninstall memberlist -n loqate helm uninstall querycoordinator -n loqate helm uninstall spatial-api -n loqate # Repeat for any other releases kubectl delete namespace loqate ``` ### Verify Cleanup ```bash theme={null} kubectl get all -n loqate ``` Should return: `No resources found` ## Common Values Key configuration options in `values.yaml`: ```yaml theme={null} image: repository: loqate/component-name tag: latest pullPolicy: IfNotPresent imageCredentials: username: "" password: "" resources: requests: memory: "4Gi" cpu: "1" limits: memory: "8Gi" cpu: "2" verify: dataset: "row" storage: path: "/data" size: "250Gi" ``` ## Next Steps * [Configuration](/helm/configuration) - Customize country deployments and resources * [Troubleshooting](/helm/troubleshooting) - Resolve common issues * [Quick Start](/helm/quick-start) - Installation guide # Data Installation And Update Process Source: https://docs.loqate.com/installers/data-installation-and-update-process The first step towards installation of data packs is to check the availability of Install Manager in the API installation folder. If the Install Manager is not available, the [Install Manager installer](/installers/installation-manager-install-process/) should be used to first install the Install Manager. Then the data packs can be downloaded and installed using the Install Manager. ## Recommended Installation Steps 1. Install the Install Manager, if not already installed in the Loqate API Installation Folder (You will need the Install Manager Installer from Loqate, to install the Install Manager) 2. Request a license key from Loqate Support at [support@loqate.com](mailto:support@loqate.com) or use local data packs if available 3. Execute the Install Manager and use it to install the data packs as needed > [!WARNING] > > **Important:** Please ensure Loqate is installed **outside** of Program Files. Even if you enable read/write permissions while inside Program Files, there may still be permissions issues. We recommend installing Loqate outside of Program Files. ## Install Manager Install Manager is a Java application that was introduced in 2013Q2.0 to handle the installation of the GKR. Install Manager can be run in graphical user interface (GUI) mode or in command line mode. Install Manager uses a web service running at `licensing.loqate.com` to provide the information on compatible data packs for a given Local API version. Install Manager requires either a license key or license pack that can be obtained by contacting [support@loqate.com](mailto:support@loqate.com). ### Change to Version of Java Used by Install Manager The Loqate Install Manager used to install or update Loqate LFS datafiles is provided with a bundled Java Runtime Environment (JRE) that it uses rather than relying on the version of Java on the target machine. From 2024Q4.1 release the bundled JRE will be changed, due to vulnerabilities in the version of JRE previously used by InstallManager. However, the more recent JRE bundled from 2024Q4.1 onwards has a dependency on a later version of `glibc`; it will need glibc **2.14** or later to be on the machine. Customers with machines using old operating systems may not have support for glibc 2.14, and the bundled Java JRE will therefore not be usable on their machine, causing an error, like below example: ``` ./java: /lib64/libc.so.6: version 'GLIBC_2.14' not found ``` Some older operating systems expected to be affected by this are: * SUSE Linux Enterprise Server (SLES) 11 SP3 * RedHat 6.9 If this should happen on your machine when trying to run `InstallManager.sh`, a potential workaround is to use the version of Java runtime already installed on the machine, rather than the bundled JRE. This can be achieved by commenting out or removing the two lines highlighted below in `InstallManager.sh` before running it. ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/0780c2e4-wPjEW1W7ct8AAAAABJRU5ErkJggg.png?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=47147e35412910664bb895a92f1da5d5) Alternatively you can delete the Install Manager `jre` folder/directory. If you do not have any JREs on your system, you are recommended to Install Java/JRE version 8 and above. Below is a list of links that contains downloadable Java/JDK, please choose the version that is compatible with your platform. **Reference download sites for Java (JDK/JRE):** * [Azul](https://www.azul.com/downloads/?package=jdk#zulu) * [Adoptium](https://adoptium.net/temurin/releases/) * [Openlogic](https://www.openlogic.com/openjdk-downloads) * [Corretto](https://github.com/corretto/corretto-8) ## Graphical User Interface Mode Install Manager can be started in GUI mode by providing the command line option: `mode=gui`. GUI mode is the default mode on Windows platforms. On Windows platforms, Install Manager can be launched by double clicking on `InstallManager.bat`. The first screen displays the version of the Local API currently installed, at the lower left corner. ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/1ac4bdaf-IMstep1-300x235.png?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=13ee51a4ae62a726d8da359b4967ba6d) If a proxy server is used, the checkbox "Use Proxy Server" needs to be checked and the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the checkbox "Use authentication for proxy server" should also be checked and the user name and password need to be provided. ![](https://mintcdn.com/loqate/_M6UKnN7xWZAxsg3/images/e1fbbf0a-IMstep2-300x236.png?fit=max\&auto=format\&n=_M6UKnN7xWZAxsg3\&q=85\&s=eabba6eed39b071ae8d6c8222d6adce4) The first step is to provide the installation folder. ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/891cc8f4-IMstep3-300x236.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=c65cb8d51b0efb28cf49b9deca0856c5) The next step is to either provide a license key or provide the full path to a license pack. The license pack is named `loqateLicense`. If a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. ![](https://mintcdn.com/loqate/bZ7DNdFBXsoQxP4T/images/46de4931-IMstep4-300x235.png?fit=max\&auto=format\&n=bZ7DNdFBXsoQxP4T\&q=85\&s=0b6bc6098da819b91d4c36d2ce195fa9) If the older format license pack `loqateLicense` is selected, it will be changed to the new format `license.lfs` ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/7ce31b58-IMLicensepack-300x233.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=1af453a40fe8654af04b8fd4e8b5857c) Once the license pack is saved to disk, Install Manager will display the contents of the license for reference. ![](https://mintcdn.com/loqate/SCbzdIaHMqk4IVMS/images/b7759098-IMstep5-300x234.png?fit=max\&auto=format\&n=SCbzdIaHMqk4IVMS\&q=85\&s=49812b9760215014e7ee57d5309e2334) There are 2 options available for downloading as shown below. One can either just download the data packs or install the data packs that are already downloaded to the local machine. ![](https://mintcdn.com/loqate/_M6UKnN7xWZAxsg3/images/e3791d25-datapacks-300x233.jpg?fit=max\&auto=format\&n=_M6UKnN7xWZAxsg3\&q=85\&s=e7ee0ca4fd94428bc3715bceff016428) After a valid option is selected, Install Manager will communicate with `licensing.loqate.com` and fetch details about the latest available licensed data packs that are compatible with the Local API version that is currently installed. The details of available data packs to install will be shown next. In the case a user selects an existing data folder for installation, it will show newer data packs available to download and install. The release date of the available data packs will also be displayed. The user can select the required data packs from this screen by checking the checkboxes next to each product. ![](https://mintcdn.com/loqate/_M6UKnN7xWZAxsg3/images/d1cd367c-IMSelectproducts-300x237.jpg?fit=max\&auto=format\&n=_M6UKnN7xWZAxsg3\&q=85\&s=75812bd0048cf23ddcbe1838358cdb87) If the user selects the download option, Install Manager will download the data packs. ![](https://mintcdn.com/loqate/bZ7DNdFBXsoQxP4T/images/4e4ea006-download-300x235.jpg?fit=max\&auto=format\&n=bZ7DNdFBXsoQxP4T\&q=85\&s=67f06ad1c5fb7d9a47dbee9f0a5f05a1) The download can be paused and resumed at any point. If the "Pause Download" button is pressed the UI will change as follows: ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/a8a303ba-IMresumedownload-300x234.jpg?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=a9d9d794ba271bafb35d9231533b8814) The next screen displays location where the downloaded data packs will be installed. ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/16ba1eb1-IMDiskspace-300x236.jpg?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=e1c136d8d4eff828d71b909129f1dbca) The next screen will proceed to installing the selected data packs. ![](https://mintcdn.com/loqate/_M6UKnN7xWZAxsg3/images/d8a069c6-IMUnzip-300x235.jpg?fit=max\&auto=format\&n=_M6UKnN7xWZAxsg3\&q=85\&s=7d30600f3dfd7b4db6585ee9722d0929) Finally, Install Manager will complete the installation as shown. ![](https://mintcdn.com/loqate/SCbzdIaHMqk4IVMS/images/c7c09a61-IMFinish-300x237.jpg?fit=max\&auto=format\&n=SCbzdIaHMqk4IVMS\&q=85\&s=7ed3ca70e2f904362ebf8021d71e1339) ## Command Line Interface Mode Install Manager can be started in command line mode by providing the command line option: `mode=commandline`. Command line mode is the default in Linux and UNIX platforms. On Linux/Unix platforms, Install Manager can be launched by running the script `InstallManager.sh`. The first screen displays the version of the Local API currently installed. ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/31aaebae-IM_CLI_image1.png?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=cc56a43a169c6862875cdeb4e8e17886) If a proxy server is used, the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the user name and password need to be provided. ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/743e2790-IM_CLI_image2.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=8822f0eac6d314a4fbbc356aa8310a58) ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/1d1f1f82-IM_CLI_image3.png?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=31a4f857614f80de32bb4b48aa3cab39) The first step is to provide the installation folder. If the user selects an empty folder the installation will proceed as a fresh installation of the data packs. If the user selects an existing data folder, the installer will proceed as an update installation. ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/797cfd67-IM_CLI_image4.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=6649d97e89e7c6f1bb9eb8bbe46c87e5) The next step is to either provide a license key or provide the full path to a license pack. The license pack is named `loqateLicense`. From 2015Q1 release the license pack format is changed from `loqateLicense` to `license.lfs`. If a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. There are 3 options available for downloading and installing as shown below. ![](https://mintcdn.com/loqate/bZ7DNdFBXsoQxP4T/images/69d4a40d-IM_CLI_image5.png?fit=max\&auto=format\&n=bZ7DNdFBXsoQxP4T\&q=85\&s=fab6f518db7b3d3184a8ff7ea2cad63a) One can either just download the data packs or install the data packs that are already downloaded to the local machine. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/a7fd0bf9-IM_CLI_image6.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=fb30f37feee1a90b57e2adb62d9c310a) When the list of available data packs is shown, enter `all` to select all data packs. Alternatively, if only certain products are desired for installation, enter the numbers next to those products, ending the selection by entering `done`. ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/75811245-IM_CLI_image7.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=4a09e841581902ec3abc839d8e7fd762) Depending on the choice made for download and installation, Install Manager may download data packs from `download.loqate.com` and install them. ![](https://mintcdn.com/loqate/NzQbT46fbZrWgEKs/images/2ba30866-IM_CLI_image9.png?fit=max\&auto=format\&n=NzQbT46fbZrWgEKs\&q=85\&s=4fcf5c46e25dd962417112c073c17b11) ![](https://mintcdn.com/loqate/bZ7DNdFBXsoQxP4T/images/5ddb3dad-IM_CLI_image10.png?fit=max\&auto=format\&n=bZ7DNdFBXsoQxP4T\&q=85\&s=c82a573a17c895a0f0ecaf2ebced2330) ## Installation Troubleshooting If you receive the error message "license expired" but your license key is still valid, we have listed the below recommendations. ### Insufficient Permissions Install Manager needs both read and write permissions to update the license pack. Make sure you have permission to create/overwrite `license.lfs`, otherwise the license pack will not update. **Linux:** Since the Linux install of `license.lfs` has default permissions of 644, only the owner of `license.lfs` has write permissions. If you are accessing `license.lfs` from a shared folder or someone else's folder, you will need to change the permissions to 664 or 666 first. **Windows:** If you are installing data anywhere inside Program Files, Program Files (x86), or Windows (for example `C:\Program Files\Loqate\data`), you will need to provide admin permissions, either by running InstallManager as administrator through Command Prompt, or installing outside of Program Files and copying the installed data into the desired location. ### Older Version of Install Manager If you are using an older version of the Install Manager from 2015, which had a bug, you will need to download the latest InstallManager from the Loqate FTP site. To retrieve the login info, please either ask your account manager or submit a ticket to [support@loqate.com](mailto:support@loqate.com). ### Proxy/Firewall Access Install Manager needs internet access and will connect to our licensing servers to validate the license key and to fetch the information about the latest compatible reference data for download. If there are any Proxy/Firewall settings in place that may block the access to our servers, please check that the following URLs are not blocked by your settings. If the following URLs are blocked, please update your firewall settings or use the proxy authentication specified during the Install Manager process (on the first screen). The following URLs are needed so that the Install Manager can connect to our server to verify the license key and get the reference datapacks: * `https://licensing.loqate.com` port 443 * `https://data.loqate.com` port 443 **Test the connections by using these curl commands:** Test licensing server: ```bash theme={null} $ curl https://licensing.loqate.com:443 ``` **Expected result:** An empty result. **Error result:** A result that contains "Could not resolve host" indicates you are not able to connect to the site and will not be able to download data. Please contact your IT department and ask them to allow access to that site. Test data server: ```bash theme={null} $ curl https://data.loqate.com:443 ``` **Expected result:** ```xml theme={null} AccessDenied Access Denied VY5YZNBETGF084CJ T5Xl6GNk9N4GsYcIpzgZChQabj/zoYcHrTmAKKpPjGysliqiLEX7BKVh0oRvCYnMdkYvZzAna0o= ``` Note that you will see this result because you were able to connect to the site and additional credentials (i.e., the license key) are needed. **Error result:** A result that contains "Could not resolve host" indicates you are not able to connect to the site and will not be able to download data. Please contact your IT department and ask them to allow access to that site. ### No Internet Connection If you do not have internet connection on your server or are unable to open up the firewall on the server, we recommend to follow the online + offline instructions available on our website. Basically, you have to download the datapacks on a machine that can connect to our licensing servers. Copy them over to your servers and install those datapacks. Online and Offline installation scenarios: [Example of Installation Scenarios](/installers/example/installation-scenarios/) ## Related Pages * [Local API](/local-apis/) * [Installers](/installers/) * [Local API install process](/installers/local-api-install-process/) * [Install Manager Installation Scenarios](/installers/example/installation-scenarios/) * [How to Obtain Version Information](/release-information/how-to-obtain-version-information/) # Install Manager Installation Scenarios Source: https://docs.loqate.com/installers/example/installation-scenarios > [card] [Online Installation](/installers/example/online-installation) > [card] [Offline Installation](/installers/example/offline-installation) # Offline Installation Source: https://docs.loqate.com/installers/example/offline-installation This section will describe offline installation scenario where the user is not able to connect to the internet and has a license pack file, and proceeds to download and install the data packs. In order to proceed with offline installation, the license pack and the data packs need be downloaded separately in a machine which has internet connectivity and then copied over to the install machine so that the Install Manager can access them at install time. ## Recommended Installation Steps 1. Download License pack on a machine with internet access using the License Key 2. Download datapacks (`*.lfz` files) on a machine with internet access 3. Copy the downloaded license pack and downloaded datapacks to the machine where they have to be installed (with no internet access) 4. Run the Install Manager on the install machine to install the datapacks The following sections demonstrate the steps in the data installation process. ## Graphical User Interface Mode ### Download Install Manager should be run on a machine which can access the internet. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image1-e1420596320437.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=1a407e6fb92275c81b885eb8eb64a2c0) If a proxy server is used, the checkbox "Use Proxy Server" needs to be checked and the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the checkbox "Use authentication for proxy server" should also be checked and the user name and password need to be provided. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image2%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=35919c8f90bdeddb7475cdf1cf7b5815) The first step is to provide the installation folder. The Loqate License Pack will be written to this folder. Until 2015Q1 release, the Loqate license pack was named `loqateLicense`. From 2015Q1 release the license pack format is changed from `loqateLicense` to `license.lfs`. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image2%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=35919c8f90bdeddb7475cdf1cf7b5815) In the next step provide a license key. When a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image4%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=959e8211c50d571a163ca6738cf171ca) Once the license pack is saved to disk, Install Manager will display the contents of the license for reference. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image5%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=42667fcd770132fa530e74729a256a75) There are 2 options available for downloading as shown below. Select the "Download datapacks" option to download the required datapacks. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image6%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=d29aab4bcdb8625ff4b42a462b207b0b) After a valid option is selected, Install Manager will communicate with `licensing.loqate.com` and fetch details about the latest available licensed data packs that are compatible with the Local API version that is currently installed. The details of available data packs to install will be shown next. In the case a user selects an existing data folder for installation, it will show newer data packs available to download and install. The release date of the available data packs will also be displayed. The user can select the required data packs from this screen by checking the checkboxes next to each product. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image7%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=bced48cfa73067ba48bbc0752e233b17) If the user selects the download option, Install Manager will download the data packs. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image8%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=ee26e39c59fcc408da7a7be7f7630b2a) The download can be paused and resumed at any point. If the "Pause Download" button is pressed the UI will change as follows: ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image9%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=8a8e70f38edc9d90943e83d80377905a) The next screen displays location where the downloaded data packs will be installed. Since the datapacks are to be installed on a different machine, the installation can be stopped at this stage by closing the window or by the 'Cancel' button. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image10%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=70cd609aa250ad11b125e2c70c56fb30) ### Installation Once the downloaded license pack and datapacks are copied to the Install machine, run the Install Manager on the install machine. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image1-e1420596320437%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=880963b2a9245f0856d2fefb7bbfd9d6) Select the installation folder, the license pack can be placed in this folder. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image3%20\(2\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=cf9a3149183f6d6ce9d610b00f501416) Choose the option "I have a license pack" and select the license pack file. From 2015Q1 release onwards, if the older format license pack `loqateLicense` is selected, it will be changed to the new format `license.lfs` ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image24.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=27fa347aac229fc7904fafd3b1642c87) Install Manager will display the contents of the license for reference. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image5%20\(1\).png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=42667fcd770132fa530e74729a256a75) In the next screen choose the option "use local data packs" and select the folder where the downloaded datapacks were copied to. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image25.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=ea60e431b7ed432c2178ccc3512c4573) The available datapacks will be displayed for selection. Once the required datapacks are selected for installation, continue by clicking 'Next' button. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image26.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=9a185df831bb5284fedb9794a758261f) The next screen displays location where the downloaded data packs will be installed. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image27.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=ab72997c26db4ea00fcc0c2ea1fc02a7) Next, the user is shown the data license agreement. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image28.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=3b194a496584ad21fd873ff7da28cbd8) Once the user accepts the license agreement, the next screen will proceed to installing the selected data packs. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image29.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=b345b53952f64623eb668dff79f5a48e) Finally, Install Manager will complete the installation as shown. The install folder will now have the `*.lfs` files along with `*_manifest.properties` for the datapacks which were selected for installation. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image13%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=65bb2e52a3c40ed76450c464b0cb034d) ## Command Line Interface Mode Install Manager can be started in command line mode by providing the command line option: `mode=commandline`. Command line mode is the default in Linux and UNIX platforms. On Linux/Unix platforms, Install Manager can be launched by running the script `InstallManager.sh`. ### Download The first screen displays the version of the Local API currently installed. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image14%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=8283e3899ead4b271aecaa009ac1d809) If a proxy server is used, the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the user name and password need to be provided. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image15%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=fe4dd34722149644c327859a918fcf89) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image16%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=2517c0f7b2ab744e35a115e4c9905d9d) The first step is to provide the installation folder. If the user selects an empty folder the installation will proceed as a fresh installation of the data packs. If the user selects an existing data folder, the installer will proceed as an update installation. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image17%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=00769e7c77dcd7ed428a8b897c4123b8) The next step is to provide a license key. When a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. Choose the option to download the datapacks. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image30%20\(1\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=7b154350f8d6d7d6e3c7fb27307fd849) When the list of available data packs is shown, enter `all` to select all data packs. Alternatively, if only certain products are desired for installation, enter the numbers next to those products, ending the selection by entering `done`. Install Manager downloads data packs from `download.loqate.com`. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image31.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=d62cebbb2d7813e35223a41ea8259e3a) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image32.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=1d4cce4d5d19e04bd90094af43416239) ### Installation Once the downloaded license pack and datapacks are copied to the Install machine, run the Install Manager on the install machine. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image14%20\(2\).png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=67640fd2a213c4f33e815f5d199a15e4) Select the installation folder, the license pack can be placed in this folder. Choose the option "I have a license pack" and select the license pack file. From 2015Q1 release onwards, if the older format license pack `loqateLicense` is selected, it will be changed to the new format `license.lfs`. Install Manager will display the contents of the license for reference. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image33.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=43c5f75b9c75249ef2d3cba6908b7796) Choose the option "install using locally available data packs" and select the folder where the downloaded datapacks were copied to. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image34.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=88f1f1a3dc131f323c388841fd7b26b5) The available datapacks will be displayed for selection. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image35.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=e4b4f79c828bdecafda0a9f865a5aaaa) Next, the user is shown the data license agreement. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image36.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=9bf63da0141fda90c4a42479b9e8d27d) Once the user accepts the license agreement, the Install Manager will proceed to installing the selected data packs. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Offline_image37.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=2cc9bfbafdfa01a2045dcdb243924950) # Online Installation Source: https://docs.loqate.com/installers/example/online-installation This section will describe online installation scenario where the user is able to connect to the internet and has a license key, and proceeds to download and install the data packs. ## Installation Steps 1. Run Install Manager using License key 2. Download the required datapacks (`*.lfz` files) 3. Install the data packs The following sections demonstrate the steps in the data installation process. ## Graphical User Interface Mode Install Manager can be started in GUI mode by providing the command line option: `mode=gui`. GUI mode is the default mode on Windows platforms. On Windows platforms, Install Manager can be launched by double clicking on `InstallManager.bat`. The first screen displays the version of the Local API currently installed, at the lower left corner. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image1.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=c49e3f62acc64b6245c97615fa162aba) If a proxy server is used, the checkbox "Use Proxy Server" needs to be checked and the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the checkbox "Use authentication for proxy server" should also be checked and the user name and password need to be provided. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image2.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=cb8cc55368887cd654e1e0b7d7143f7c) The first step is to provide the installation folder. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image3.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=6c9fb514667fdf522a7a09fc9f63e87d) The next step is to provide a license key. When a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image4.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=d72ccbe9221e3e16a35fce65086f75bf) Once the license pack is saved to disk, Install Manager will display the contents of the license for reference. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image5.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=387ac1851bfa145b526f15fa1efc96e0) There are 2 options available for downloading as shown below. One can either just download the data packs or install the data packs that are already downloaded to the local machine. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image6.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=021e6148b314aa0d8cb6cf5ee0542ac0) After a valid option is selected, Install Manager will communicate with `licensing.loqate.com` and fetch details about the latest available licensed data packs that are compatible with the Local API version that is currently installed. The details of available data packs to install will be shown next. In the case a user selects an existing data folder for installation, it will show newer data packs available to download and install. The release date of the available data packs will also be displayed. The user can select the required data packs from this screen by checking the checkboxes next to each product. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image7.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=acb4d0003a6b42ad77c56729807e8c35) If the user selects the download option, Install Manager will download the data packs. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image8.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=a7fe57acf6e3c10a6bafeaa65ad2b5ce) The download can be paused and resumed at any point. If the "Pause Download" button is pressed the UI will change as follows: ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/IM_Online_image9.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=4f060cc4ba299659d0d1b83e3e9f1528) The next screen displays location where the downloaded data packs will be installed. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image10.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=502ed56af286e60983a0b2864d79679e) Next, the user is shown the Loqate data license agreement. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image11.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=9ebdac7b4207c70ca1480ab41660eaa4) Once the user accepts the license agreement, the next screen will proceed to installing the selected data packs. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image12.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=856e626630c86eda117ae671e577cc69) Finally, Install Manager will complete the installation as shown. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image13.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=1b7b0fb4b4a0977a3d6bf9bf81b3b7fd) ## Command Line Interface Mode Install Manager can be started in command line mode by providing the command line option: `mode=commandline`. Command line mode is the default in Linux and UNIX platforms. On Linux/Unix platforms, Install Manager can be launched by running the script `InstallManager.sh`. The first screen displays the version of the Local API currently installed. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image14.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=3e7f8274324af178d4ef0bf1f96cf95d) If a proxy server is used, the Proxy server name and port need to be entered as shown below. If the proxy server needs authentication, the user name and password need to be provided. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image15.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=98da6919d67b9ed3de2862c416d72e25) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image16.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=7f16f86453eac61b6fe16647dbc491c8) The first step is to provide the installation folder. If the user selects an empty folder the installation will proceed as a fresh installation of the data packs. If the user selects an existing data folder, the installer will proceed as an update installation. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image17.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=9356b0681371208d548014159f048160) The next step is to provide a license key. When a license key is entered, Install Manager will communicate with `licensing.loqate.com`. If the license key is valid, the server will return the corresponding license pack to Install Manager and then Install Manager will write the license pack to the installation folder. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image18.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=35ea8f117e4c1647f829ccd425891fb9) One can either just download the data packs or install the data packs that are already downloaded to the local machine. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image19.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=08e504978e354a95daa3a85c8adc2548) When the list of available data packs is shown, enter `all` to select all data packs. Alternatively, if only certain products are desired for installation, enter the numbers next to those products, ending the selection by entering `done`. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image20.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=af12bc6546f5b61f6dfedf03ad8a3ec5) The screen below shows the Loqate License agreement. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image21.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=713b7aa53ef7f20d4b88a4a6d45e20e4) Depending on the choice made for download and installation, Install Manager may download data packs from `download.loqate.com`. ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image22.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=5992149f45a53b40a2645e86aa75ee34) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Online_image23.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=374e7e125ff58892b249ff5f6e8288f8) # Installation Manager Install Options Source: https://docs.loqate.com/installers/installation-manager Install Manager can be used to do a fresh install of data packs or update existing data packs. When you install the data packs using the Install Manager, you will need to enter a license key for the data files. Please email us at [support@loqate.com](mailto:support@loqate.com) for a license key. Install Manager is written using Java and requires a Java Runtime Environment 1.7 (JRE 1.7). In addition, if you have not installed the Loqate Java API Library as part of the Loqate Engine Installation, you also need to install those Java API libraries in order for the Install Manager to work. ## Windows Platform ```bash theme={null} set path=\bin;%path% cd java -jar InstallManager.jar mode=gui ``` ## Linux Platform ```bash theme={null} export LD_LIBRARY_PATH=/bin export PATH=$PATH;< path to JRE Folder > java -d64 -Djava.library.path=. -jar InstallManager.jar mode=commandline ``` ## Silent Mode Install Manager can be run in silent configuration using the available set of silent setting options. Using these options Install Manager can be set up to run such that there is no user interaction required. ### Silent Mode Settings File Options The full sets of options that are allowed to be defined are the following: * `LICENSE_KEY=` * `LICENSE_PACK_PATH=` * `INSTALL_FOLDER=` * `DOWNLOAD_FOLDER=` * `PRODUCTS=` * `MOVE_OLD_DATA_TO_SUBFOLDER=` * `DOWNLOAD_OPTION=` * `INSTALL_NEEDED=` * `PROXY_SERVER_NAME=` * `PROXY_PORT=` ### Tips for Using Silent Mode * Either `LICENSE_KEY` or `LICENSE_PACK_PATH` is needed. * `PRODUCTS` will equal the comma separated list of product names. Set `PRODUCTS` to `all` in order to install the full set of products allowed in the license. * If installation is done over an existing data folder, it is useful to move the old files to sub folder. This option can specified by setting `MOVE_OLD_DATA_TO_SUBFOLDER` to `yes`. * If data packs are to be downloaded, then the option `DOWNLOAD_OPTION` should be set to `yes`. If local data packs are to be used, the option `DOWNLOAD_OPTION` should be set to `no`. * If only data packs are to be downloaded and not installed, `INSTALL_NEEDED` should be set to `no`. If the downloaded or local data packs should be installed, `INSTALL_NEEDED` should be set to `yes`. * `PROXY_SERVER_NAME` and `PROXY_PORT` should both be set if proxy server settings are needed. ### Example 1: Download Data Packs This example specifies the license pack path and requires download of the data packs: ```properties theme={null} LICENSE_PACK_PATH=c:\loqate\loqateLicense INSTALL_FOLDER=C:\loqate\data DOWNLOAD_FOLDER=C:\tmp\DL PRODUCTS=all MOVE_OLD_DATA_TO_SUBFOLDER=yes DOWNLOAD_OPTION=yes INSTALL_NEEDED=yes ``` ### Example 2: Use Local Data Packs This example specifies license key and requires installation by using local data packs available at `c:\DL`: ```properties theme={null} LICENSE_KEY=1111111-523d-4ff2-8558-222222222 INSTALL_FOLDER=C:\loqate\data DOWNLOAD_FOLDER=C:\DL PRODUCTS=all MOVE_OLD_DATA_TO_SUBFOLDER=yes DOWNLOAD_OPTION=no INSTALL_NEEDED=yes ``` A **log file** is written to the folder containing the Install Manager with the date and time stamp corresponding to the execution of the silent mode. The log file will have output indicating success or failure of the execution. ### Preparing Silent Settings File Silent mode settings file can be any text file with a set of the options defined above. ### Running Install Manager in Silent Mode Install Manager can be run in silent mode by providing the command line options: ```bash theme={null} mode=silent silentInstallSettingsPath= ``` On Linux/Unix platforms, Install Manager can be launched by running the script `InstallManager.sh`. On Windows silent mode can be launched by executing the `InstallManager.bat` with the above command line option. ## Config Mode Install Manager can be run in custom configuration using the available set of config options. Using these config options Install Manager can be set up to run such that certain UI options are not presented to the user and certain fields are pre-populated. ### Config File Options The full sets of options that are allowed to be defined are the following: **`OPTION_BRAND_TITLE=`** Customize the company name displayed in Install Manager. **`OPTION_SKIP_DOWNLOAD=`** When set to `yes`, local data packs will be used for installation. **`OPTION_DOWNLOAD_FOLDER=`** Specify the download folder location. **`OPTION_INSTALL_FOLDER=`** Specify the installation folder location. **`OPTION_LOCAL_LICENSE_PATH=`** Specify the path to the license pack file. **`OPTION_LICENSE_AGREEMENT_PATH=`** You can specify the path to your custom license agreement file. **`OPTION_DOWNLOAD_BASE_URL=`** Specify the base download URL. **`OPTION_SKIP_LICENSE_REVIEW=`** When set to `yes`, the License Review screen will be skipped. #### GUI Screen ![](https://mintcdn.com/loqate/5ob_QWcOxwgHoz2p/images/IM_Config_image1.png?fit=max\&auto=format\&n=5ob_QWcOxwgHoz2p\&q=85\&s=bef51dba57978bc7b1ac00ce900f071e) #### Command Line ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Config_image2.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=b9e845696b37fe91ffd0ae358cdf6b24) **`OPTION_SELECT_FOLDER_DISABLE=`** When set to `yes`, the folder selection option will be disabled. #### GUI Screen (Disabled) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Config_image3.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=f45e8b890402d99616023a4a66bb5a16) #### Command Line (Disabled) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Config_image4.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=86b08d8d605384e42f6efd138032fa52) When set to `no`, folder selection option will be enabled. #### GUI Screen (Enabled) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Config_image5.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=b536cd608b42abe9f3b53e5518354dcb) #### Command Line (Enabled) ![](https://mintcdn.com/loqate/ovuMLzhaeZg77OvL/images/IM_Config_image6.png?fit=max\&auto=format\&n=ovuMLzhaeZg77OvL\&q=85\&s=e4886759f11153421fe8a104a8070dae) **`OPTION_MANDATORY_PRODUCTS=`** Datapacks that need to be installed mandatory can be mentioned in this list enabling the user installs all the required files. For example, `KBCOMMON` is a must in the Loqate data directory along with other country files. ### Config File Example ```properties theme={null} OPTION_SKIP_LICENSE_REVIEW=yes OPTION_SKIP_DOWNLOAD=yes OPTION_INSTALL_FOLDER=C:\\Loqate\\data OPTION_DOWNLOAD_FOLDER= C:\\Loqate\\data OPTION_LICENSE_AGREEMENT_PATH=C:\\Documents\ License_Agreement.txt OPTION_LOCAL_LICENSE_PATH=C:\\Loqate\\data\\loqateLicense OPTION_BRAND_TITLE=Loqate OPTION_MANDATORY_PRODUCTS=KBCOMMON ``` ### Preparing Config File Config mode settings file needs to be an encrypted file for use at Install Manager run time. The text file containing the config options (similar to above example) can be encrypted by running Install Manager with the `-encrypt` command line parameter. Command for encrypting config file: ```bash theme={null} PATH=.\jre6;.\jre6\bin;.;%PATH% start /MIN java -D64 -classpath ".;loqate.jar;InstallManager.jar;.\lib\*" com.loqate.licensemanager.integration.LicenseApplication –encrypt ``` The above will output an encrypted config file `.enc` in the same folder as the input config file. This encrypted file should be bundled with the Installers for executing Install Manager in config mode at the time of Installation. ### Running Install Manager in Config Mode Install Manager can be run in config mode by providing the command line options: ```bash theme={null} mode= configPath= ``` On Linux/Unix platforms, Install Manager can be launched by running the script `InstallManager.sh`. On Windows config mode can be launched by executing the `InstallManager.bat` with the above command line option. ## Important Notes > [!NOTE] > > **File and Folder Paths in Windows** > > While specifying the file or folder path in Windows, please use double backslash `\\` in the path. > [!NOTE] > > **Customizing Company Name** > > All default error messages refer to Loqate. If you wish to have your company name to be shown, please specify the Brand title option. > > For example: "There was an error during the installation. Please contact Loqate technical support". > > When `OPTION_BRAND_TITLE=XXX`, the message will be: "There was an error during the installation. Please contact XXX technical support". > [!NOTE] > > **License Agreement** > > By default Loqate license agreement will be shown if the required license agreement file and path are not provided in the config file. > [!NOTE] > > **Default Base URL** > > By default the base URL is [https://download.loqate.com](https://download.loqate.com) # Installation Manager Install Process Source: https://docs.loqate.com/installers/installation-manager-install-process The following sections demonstrate the steps of the installation process for Install Manager installation. The installer to be used depends on the platform and the flavor of the API already installed. On Windows and Linux, if the API installed is of 64-bit flavor, we need to use the 64-bit Install Manager Installer from the corresponding platform. See [installer options](/installers/installation-manager/) for more details. ## Installation Using GUI For Install Manager to work, the Loqate Java API is required. If not found in the installation directory, the following error will be shown. After the welcome screen the next screen requires selection of the installation folder. This folder needs to be the folder where the Loqate API is currently installed. The next screen is the review screen. The next screen will install the Install Manager and complete the installation. Installation of the Install Manager will install the `InstallManager.jar` file, a `lib` folder containing the dependent libraries and a local copy of the Java Runtime Environment (JRE) as well. The JRE is needed to run the Install Manager. This local copy of JRE will not affect any system settings on the target machine. ## Installation Using the Command Line Interface On Linux/Unix platforms, the preferred method of installation is using the command line interface. Installation of the Install Manager will install the `InstallManager.jar` file, a `lib` folder containing the dependent libraries and a local copy of the Java Runtime Environment (JRE) as well. The JRE is needed to run the Install Manager. This local copy of JRE will not affect any system settings on the target machine. # Installers Source: https://docs.loqate.com/installers/introduction Loqate software installation involves installation of the API and the GKR (Global Knowledge Repository) data packs. In the next sections we will walk through the steps of the installation process for the Local API and then the installation of the GKR using the Installation Manager. We will discuss the steps for installation using Graphical User Interface mode for Windows as well as the command line interface for Linux/Unix platforms. ## Recommended Installation Steps 1. [Install the Local API](/installers/local-api-install-process/) 2. Request a license key from Loqate Support at [support@loqate.com](mailto:support@loqate.com) 3. [Install the data packs](/installers/data-installation-and-update-process/) as needed, using Install Manager 4. [Example of installation scenarios](/installers/example/installation-scenarios/) 5. [Learn how to obtain version information](/release-information/how-to-obtain-version-information/) # Local API install process Source: https://docs.loqate.com/installers/local-api-install-process The following sections demonstrate the steps of the installation process for Local API installation. ## Installation Using GUI ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image110.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=51e3ccc3b57d9e83fd004cc9d9c05176) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image28.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=f7ab7d4ca4f11471e35c6394c7880147) After seeing the welcome screen and accepting the license agreement, the next screen shows the components to install. For Install Manager to work, the Loqate Java API is required. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image31.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=311facf5a20609cbe19e71e9f031f655) The next step is to select a folder to install the Local API. If Install Manager was selected as a component to install, then a local copy of Java Run time Environment will be installed in addition to `InstallManager.jar` and a script or a batch file (`InstallManager.bat` for Windows and `InstallManager.sh` for Linux/Unix platforms) for running Install Manager. The Java Runtime Environment will be installed locally so there will be no effect on the system settings in the target machine. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image41.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=4906abe2864d98ea4c432eb5b2b28e6f) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image51.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=4b8f7f6a11dd9aa62260e788194d1d50) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image61.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=056aeb74ec363f9753135995330ce961) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image71.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=2906edcfab0e5bf4e97dd8fb76c59825) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image81.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=7c503230d4343464e69564f38faa4e5b) ## Installation Using the Command Line Interface On Linux/Unix platforms, the preferred method of installation is using the command line interface. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image91.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=86a758731d436f3e280b6950ae350335) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image101.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=e88314c4f689eeba2a08fba4fb795ca7) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image111.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=3cb8c72978e9ab591d727a959b227f48) ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image121.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=353b2c8d08b9318ebfff906fc5b9b7fa) When selecting components, if Install Manager is selected, then the Java API is also installed. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image131.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=f89ae7fa0e6bdcb5cad6c53eae9d2994) If Install Manager is selected as a component to install, the installer will install a local copy of the Java Runtime Environment (JRE) as well. This is needed to run Install Manager. This local copy of JRE will not affect any system settings on the target machine. ![](https://mintcdn.com/loqate/7owb0a8870OAPvwG/images/Image141.png?fit=max\&auto=format\&n=7owb0a8870OAPvwG\&q=85\&s=229db93cfe11b7ac98d4ac07f5430935) # Adobe Commerce Integration Source: https://docs.loqate.com/integrations/adobe-commerce Add Address Capture, Address Verify, Email and Phone Validation to Adobe Commerce (Magento) checkout, registration, customer accounts and admin. ### Works with: Adobe Commerce (Magento 2.4) ### Supported Loqate Services:
    [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate Adobe Commerce integration is a single package from the [Adobe Commerce Marketplace](https://commercemarketplace.adobe.com/gbg-loqate-loqate-integration.html) that adds Loqate's address, email and phone services to your store. It helps you improve the customer experience, reduce failed deliveries and keep your customer data accurate. Each service can be enabled in the places that matter most in your Adobe Commerce environment: store checkout pages, registration pages, customer accounts, customer and order creation in the admin panel, and customer address imports. ## Supported Loqate Services > [tab] Address Capture > > ### Type-Ahead Address Lookup > > Real-time address lookup speeds up address entry and eliminates errors. The single-line type-ahead search uses location biasing to return the address closest to the customer within just a few keystrokes. > > **Key Features:** > > * Available on checkout, customer account, and admin customer and order creation pages > * Restrict searchable countries to the markets you serve > * IP2Country pre-selects the customer's country based on their IP address > * Enhanced fields to capitalise values or remove diacritics before they are populated > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Address Verify > > ### Address Verification > > Address Verify parses, cleanses and selects the most accurate address from Loqate's data sources. From version 2.0 of the integration, you control how strict verification is using Address Verification Code (AVC) thresholds. > > **Key Features:** > > * Best-practice AVC threshold applied by default, with the option to override it > * Available on checkout, customer account, and admin customer and order creation pages > * Verify addresses as customers are imported in the admin panel > > [Learn more about Address Verify](/our-services/address-verify/overview) > [tab] Email Validation > > ### Email Address Validation > > Validate email addresses at the point of capture so you can communicate with customers efficiently and keep your database up to date. > > **Key Features:** > > * Available on checkout, registration, customer account and admin pages > * Choose whether to block or warn on invalid email addresses > * Choose whether to accept `Valid_CatchAll` responses > * Configurable request timeout > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone Number Validation > > Validate mobile and landline numbers at the point of capture so the contact details you hold can be trusted. > > **Key Features:** > > * Available on checkout, customer account and admin pages > * Choose whether to block or warn on invalid phone numbers > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/adobe-commerce-setup-guide) > > Install, upgrade and configure the Loqate Adobe Commerce integration ## Integrate in 3 steps 1\) Get your API key 2) Install the extension 3) Configure services > [card] > > Get your API key, then install from the Adobe Commerce Marketplace > > Install the extension with Composer, add your API key in the admin panel, and choose where each service runs. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Install the Extension > > [Open](https://commercemarketplace.adobe.com/gbg-loqate-loqate-integration.html) > > 3. Configure Services > > [Open](/integrations/adobe-commerce-setup-guide#integration-configuration) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Which versions of Adobe Commerce are supported? > > The integration supports Magento 2.4 and is built with PHP 8. New versions of the integration are designed to be backwards compatible, so no extra development should be needed on your side after you upgrade. > [accordion] Which Composer package should I install? > > When installing directly with Composer, use `lqt/loqate-integration` (this supersedes `loqate-integration/adobe` from version 1.1.8 onwards). When installing from the Adobe Commerce Marketplace, use the package name provided by the Marketplace. See the [setup guide](/integrations/adobe-commerce-setup-guide#module-name) for details. > [accordion] Does my API key need any special setup? > > Your API key must be fully enabled for the features this integration uses. Keys on accounts created specifically for the integration are enabled automatically. Otherwise, check for the **Advanced** option on the key in your Loqate account and contact support if you can't see it. See the [prerequisites](/integrations/adobe-commerce-setup-guide#prerequisites). > [accordion] Can I use each service independently? > > Yes. Address Capture, Address Verify, Email Validation and Phone Validation each have their own settings, and you choose which pages each service is enabled on. > [accordion] Can different storefronts use different settings? > > Yes. The integration supports multiple store configurations, following the standard Store → Website → Default priority. Different stores can use different API keys and settings, such as restricting each store to different countries. > [accordion] Is it compatible with other third-party extensions? > > The integration was developed in isolation from other third-party Adobe Commerce integrations, so it may not be compatible with them. We recommend testing in a non-production environment first. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Adobe Commerce (Magento 2.4) [View on Adobe Commerce Marketplace](https://commercemarketplace.adobe.com/gbg-loqate-loqate-integration.html) # Adobe Commerce Setup Guide Source: https://docs.loqate.com/integrations/adobe-commerce-setup-guide Install, upgrade and configure Loqate Address Capture, Address Verify, Email and Phone Validation in Adobe Commerce (Magento). [Get the Adobe Commerce integration](https://commercemarketplace.adobe.com/gbg-loqate-loqate-integration.html) > [!NOTE] > > ![](https://mintcdn.com/loqate/WcNSN20tc62J7qEw/images/integrations/adobe-commerce/plugin-integration.svg?fit=max\&auto=format\&n=WcNSN20tc62J7qEw\&q=85\&s=702af92a7bcc6d68ae400ace5ceaa3f4) > > This guide will help you install, configure and utilise the Loqate Adobe > Commerce Integration from the Adobe Commerce Marketplace. > > Throughout the guide, we will be referencing Adobe Commerce as the formerly > named ‘Magento’. For an overview of the services included and where they can be used, see the [Adobe Commerce integration overview](/integrations/adobe-commerce). ## Who is this guide for? There are two primary sections within this guide, listed below: * **Installation:** this is aimed at your technical users with Adobe Commerce knowledge who will be installing the integration into your environment * **Using the Integration:** this is aimed at any user (no high level technical knowledge required) who wishes to use this integration or make configurations for your business to your Adobe Commerce store ### **Prerequisites** For the Loqate integration to work on your Adobe Commerce store there are two prerequisites: * An active Loqate account (available at [account.loqate.com](https://account.loqate.com/)) * A valid API key Please follow the instructions in our [Getting Started guide](/loqate-basics/get-started), paying particular attention to the following: * If you don’t already have an account, follow the instructions in the section titled **1. Create a Loqate account** * Then follow the instructions in the section titled **3. Create an API key** (we recommend you create a generic API key, and make sure you include ‘Adobe Commerce’ in the name you choose) * You can skip the remaining steps, although you may want to return to the section titled **5. Check your usage** once you’ve completed the Adobe Commerce integration **Please note** Your new API key will need to be fully enabled for use with a specific set of features in order to work with this integration. If you created an account specifically for this integration, your API key will automatically be fully enabled and you can move on to the next section of this guide: If not, please follow these instructions: * Once you have created a new API key, or if you want to use an existing key, in your Account Section go to the [Your Services page](https://account.loqate.com/account#/Dashboard/) * Select the key you want to use and look for the **Advanced** menu option ![API Key Headings](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/api-key-headings-june-25.PNG?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=7e9a5f6a7fa71f5a37a24bec4177fd8e) * If you **can** see the Advanced option, your key is fully enabled and you can proceed with your integration * If you **cannot** see the Advanced option, please contact our Support team ([on this page](https://www.loqate.com/en-us/contact/), or via [LoqateSupport@gbgplc.com](mailto:LoqateSupport@gbgplc.com)) or your Account Manager and ask them to enable your API key for use with Adobe Commerce. Once this is enabled, you can proceed with your integration ## Integration Management This section will include instructions on how to install, upgrade and uninstall the [Loqate Adobe Commerce Integration](https://commercemarketplace.adobe.com/gbg-loqate-loqate-integration.html). As stated in the introduction of this document, this part of the guide is primarily aimed at technical users with knowledge of Adobe Commerce who manage your environment. ### Supported Versions The Loqate integration for Adobe Commerce will support versions of Magento 2.4. It has been built with PHP8. New versions should be backwards compatible and require no extra development on your side after you upgrade. ### Module name Depending on how you’re installing the app you might install from different namespaces. When installing directly via Composer, without going via the Adobe Commerce store, you should use the package name "**lqt/loqate-integration**" (this supersedes "**loqate-integration/adobe"** from version 1.1.8 onwards). When installing from the Adobe Commerce app store you will need to have your Composer credentials in place for **[repo.magento.com](http://repo.magento.com),** and you should install from the package name provided by the app store (as of November 2024 this is "**gbg-loqate/loqate-integration**"). For the examples in this guide, we’ll use the non-store version "**lqt/loqate-integration**". ## Installing the module To begin, open a terminal and run the following command in your Adobe Commerce directory: **composer require lqt/loqate-integration** Next, set up the module by running the following commands: **php bin/magento module:enable Loqate\_ApiIntegration ** **php bin/magento setup:upgrade ** **php bin/magento setup:di:compile ** ## Upgrading the module Before you upgrade: * Back up your files and database. * Start with your test environment. * Keep a copy of any customisation you made to the module’s original code. * Check out the changelog. If you have customised the integrations code, you’ll need to port these customisations after upgrading and resolve any potential conflict. Run the following commands: **composer remove lqt/loqate-integration** **composer require lqt/loqate-integration** **php bin/magento setup:upgrade ** **php bin/magento setup:di:compile ** **php bin/magento setup:static-content:deploy ** **php bin/magento cache:clean ** ## Uninstalling the module Before you uninstall: * Back up your files and database. * Keep a copy of any customisation you made to the module’s original code in case you need to reinstall it later. Run the following commands: **composer remove lqt/loqate-integration** **php bin/magento setup:upgrade ** **php bin/magento setup:di:compile ** **php bin/magento setup:static-content:deploy ** **php bin/magento cache:clean ** ## Using the Integration ## Before you start There are configurations that Loqate offer within your account section on a key. The configurations you will see in this guide are solely related to the performance and capabilities of the integration for Adobe commerce. ## Integration Configuration Once the installation process has completed, you can then configure the module in the admin panel of the store. The configuration section for the integration can be found by navigating to **Stores -> Configuration -> Loqate -> Main Settings.** For this integration to work, you need to provide a valid API key to the **API Key** input field found in the configuration section of the module. This is a required field and can be found in the “Your services” section of your account on [https://www.loqate.com/](https://www.loqate.com/). Under the Loqate configuration you will find the below sections which we have within the integration. ## Main Settings **API Key** - Navigate to the **Your Services** section of your Loqate account and copy your API key. Next, navigate back to the Adobe Loqate configuration page and paste it in this field for your integration to work. ## Address Capture Our market leading address capture product allows you to search for and select global accurate premise level addresses from our comprehensive data sources. This service is available to be added in below sections of your Adobe commerce store: * **Enable on Customer Account:** by enabling this, a drop-down list will be displayed in the customer account page, based on the input text - **Enable on Checkout:** by enabling this, a drop-down list will be displayed in the checkout page, based on the input text * **Enable on Customer Account (Admin):** by enabling this, a drop-down list will be displayed in the customer account page in the Admin, based on the input text - **Enable on Create Order (Admin):** by enabling this, a drop-down list will be displayed in the create order page in the Admin, based on the input text The below features and customisations can be found within the config menu for Address Capture. ### **Restrict searchable countries** Merchants can restrict the address results to search only within specific countries. By default, no country is selected and the integration doesn’t apply any country restrictions. Multiple consecutive countries can be selected by clicking on the first country, scrolling towards the end country, holding down SHIFT and clicking on that end country. **Multiple countries can be selected by holding down CTRL and clicking on them**. All the countries can be selected by clicking once within the field and pressing CTRL+A. ![Guide 1](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-1.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=71a5d55718525af7a2367b8975438a54) ## Address Verify Our address verification product allows you to parse, cleanse and select the most accurate addresses from our comprehensive data sources. You are able to determine the level of quality according to your preferences, more information below: > [!NOTE] > > As of version 2.0 of the integration **AQI thresholds have been replaced by AVC thresholds**. > This brings the app in line with Loqate's recommended Verify usage, and gives users much greater control > over how verification decisions are made in checkout and elsewhere. **Address Quality Index (AQI) (legacy - for versions prior to 2.0)** **Address Quality Index**: this is used to indicate the quality of an address. Two factors decide the address quality post-processed verification and match level and Matchscore. Based on the Address Quality chosen, the address will be validated or not. All the settings from Address Verify will be based on the address quality set. Address Quality and index: * Excellent - A - Verifiable to at least premise level without changes * Good - B - Verifiable to at least thoroughfare level with minor changes * Average - C - Verifiable to at least locality level with moderate changes * Poor - D - Only verifiable to at least locality level with more than moderate changes * Bad - E (or empty) - If an address is unable to be parsed, the AQI can be empty **AVC Threshold** is the quality threshold that will trigger a validation message to the user in the event the address they have provided does not exceed the threshold set. By default we use a best practice threshold for AVC. This requires a **verification status** of `Partially Verified` or better, a **verification match level** of `4 (premise)` or better, and a **matchscore** above `95`. If you want to alter the standard threshold, you can enable `Override default AVC threshold?` and then change the thresholds. More information can be found in the [AVC documentation](/report-codes/address-verification-code/). This service is available to be added in below sections of your Adobe commerce store: 1. **Enable on Customer Account:** the quality of the address will be verified in the Customer Account based on the address quality index set 2. **Enable on Checkout:** the quality of the address will be verified in the Checkout page based on the address quality index set 3. **Enable on Customer Account (Admin):** the quality of the address will be verified in the Customer Account (Admin) based on the address quality index set 4. **Enable on Create Order (Admin):** the quality of the address will be verified in the Create Order page based on the address quality index set 5. **Enable on Customer Import (Admin):** the quality of the address will be verified at the import, based on the address quality index set ## Email Validation Validate the accuracy of the emails captured in your Adobe Commerce environment with our simple but effective email validation product. In the config menu for this service you will first see the option below: * **Prevent Submit on Invalid Email Address: **this is used to prevent the user from adding invalid email in the email fields. If set to NO then a warning will be displayed at the save address in which the customer is told that the email address is unable to be validated. This may be useful if you do not depend too much on the accuracy of the email address and wish to proceed with the entered information. If the end user selects ‘Save’ a second time, the entered email address will be accepted and the user can proceed. If set to YES then your end user will be unable to proceed until a validated email address has been entered. This service is available to be added in below sections of your Adobe commerce store: * **Enable on Customer Account** - if this is set to YES then the validation will be displayed on the customer account page - **Enable on Checkout** - if this is set to YES then the validation will be displayed on the checkout page * **Enable on Register** - if this is set to YES then the validation will be displayed on the registration page - **Enable on Customer Account (Admin)**- if this is set to YES then the validation will be displayed on the customer account page in the Admin * **Enable on Create Order (Admin)** - if this is set to YES then the validation will be displayed on the create order page in the Admin For email validation the Loqate Integration returns Valid, Invalid and Valid\_CatchAll responses. In the config you will see an option entitled ‘Accept Valid\_CatchAll response code’. This means that a domain has been validated but the account could not be validated (particularly for employment email addresses). You have the option to allow all responses, by selecting Yes in this option, or NO only allows fully validated emails to be accepted. ![Email Validation](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-email-validation.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=8a7f37260c64943b4093c455f1e78563) * **Validation timeout: **the request timeout can also be customised, the default value and maximum is 15000 ms.(15 seconds). If you wish to reduce this, you can enter the value in milliseconds here ## Phone Validation Validate the accuracy of the phone numbers captured in your Adobe Commerce environment with our simple but effective phone validation product. In the config menu for this service you will first see the option below: * **Prevent Submit on Invalid Phone Number: **this is used in order to prevent the user from adding invalid phone numbers in the phone fields If set to NO then a warning will be displayed at the save address in which the customer is told that the phone number is unable to be validated. This may be useful if you do not depend too much on the accuracy of the phone number and wish to proceed with the entered information. If the end user selects ‘Save’ a second time, the entered phone number will be accepted and the user can proceed. If set to YES then your end user will be unable to proceed until a validated phone number has been entered. This service is available to be added in below sections of your Adobe commerce store: * **Enable on Customer Account:** if this is set to YES then the validation will be displayed on the customer account page - **Enable on Checkout:** if this is set to YES then the validation will be displayed on the checkout page * **Enable on Customer Account (Admin):** if this is set to YES then the validation will be displayed on the customer account page in the Admin - **Enable on Create Order (Admin):** if this is set to YES then the validation will be displayed on the create order page in the Admin ## Additional config ### IP2Country This optimisation can pre-determine the country of the end user’s IP to populate the country selection field within parts of the integration. The user’s IP (if redeemable) is gathered by Loqate and the API returns the country ISO2 code, that is then mapped within Magento’s country form. The form will be set by default to that country and addresses will be searched from that country unless the customer changes it. Upon accessing a page with an address form creation (new customer address, new address at checkout), an Ip2Country request is done if configured for the integration:\\ ![Ip2Country](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-ip2country.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=d632b774347a9e5823d3d89d9289e9d6) ### Enhanced fields Loqate API results can be customised via the enhanced fields functionality. Before the address is auto-completed by the end user, values can be enhanced by specifying the fields within this section of the integration config. Trailing characters can be added in admin config page, for example ! for capitalisation and \$ to remove diacritics. The fields are mapped as following: | Frontend Form Field | Backend Text Input | | - | - | | Street Address1 | Line1 | | Street Address2 | Line2 | | State/Province | ProvinceName | | City | City | Note: State/Province will be changed only in the case of a text field, as Adobe Commerce displays a dropdown for certain countries. ![Enabled Fields](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-enabled-fields.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=59ad4a5151bdea2a9cc71d1980a4c2ec) In the screenshot above, all values will be enhanced – replaced from the enhanced fields call, capitalised and without diacritics. ![Enabled Fields 1](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-enabled-fields-1.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=976c5355815c415bd3cec4e85401e858) This is an example where diacritics were removed from the city name, as it would have been the same as the value in the State/Province field. Additional data can be returned within other fields(ex: Latitude, Longitude), but that data is not mapped to form fields and the values will not be replaced. These values can be found in the API response call. ### Multiple storefront support The Loqate integration supports multiple store(s) configuration. If you had an operation that needed to interact differently for the UK, and another for a Spanish storefront, then this capability has been introduced to allow management of this. The priority for configuration values is defaulted to the standard Magento site:**Store->Website->Default** ![Multiple Store](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-multiple-store.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=e69e2e97e11b3db6ccf6bcad277ce1d8) In this store, the API key is inherited from the parent website, which inherits it from the Default config: ![Multiple Store 1](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-multiple-store-1.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=46c325673d6ae3aac3b5386bb5c8e126) Different stores can use different API keys for the Loqate service, and even different settings (e.g.: restrict one store to specific countries and another to other countries). ![Multiple Store 2](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/integrations/adobe-commerce/adobe-commerce-magento-guide-multiple-store-2.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=23016b384d78cc30681204a64c4b4b2d) ## Troubleshooting The development of this integration has been concluded in isolation from other third-party Adobe Commerce integrations, and therefore may not be compatible with these. # Loqate Integrations for Commerce and CRM Platforms Source: https://docs.loqate.com/integrations/all-integrations Pre-built Loqate integrations for Shopify Plus, Adobe Commerce, BigCommerce, Salesforce, Microsoft Dynamics 365, commercetools, and more. > [card] > > ![Shopify Plus](https://uat.loqate.com/media/dgfnoekv/shopify-plus.svg) > > ### Shopify Plus > > Native integration for Shopify Plus stores > > [Open](/integrations/shopify-plus) > [card] > > ![Adobe Commerce](https://uat.loqate.com/media/gjrk4ijt/adobe-commerce.svg) > > ### Adobe Commerce > > Magento and Adobe Commerce integration > > [Open](/integrations/adobe-commerce) > [card] > > ![BigCommerce](https://uat.loqate.com/media/n4papthm/bigcommerce.png) > > ### BigCommerce > > BigCommerce platform integration > > [Open](/integrations/bigcommerce) > [card] > > ![Microsoft Dynamics 365](https://uat.loqate.com/media/wuhpl5sr/dynamic365.svg) > > ### Microsoft Dynamics 365 > > Dynamics 365 CRM integration > > [Open](/integrations/microsoft-dynamics-365) > [card] > > ![Salesforce](https://uat.loqate.com/media/rzehm0gb/salesforce.svg) > > ### Salesforce Commerce Cloud > > Salesforce Commerce Cloud integration > > [Open](/integrations/salesforce-commerce-cloud) > [card] > > ![commercetools](https://uat.loqate.com/media/ow3bk2m2/commercetools.svg) > > ### commercetools > > commercetools headless commerce platform > > [Open](/integrations/commercetools) > [card] > > ![Salesforce](https://uat.loqate.com/media/rzehm0gb/salesforce.svg) > > ### Salesforce CRM > > Salesforce CRM integration > > [Open](/integrations/salesforce-crm) > [card] > > ![Shopware](https://uat.loqate.com/media/43wgb1x0/shopware.svg) > > ### Shopware > > Shopware e-commerce platform > > [Open](/integrations/shopware) > [card] > > ![Reapit](https://mintcdn.com/loqate/lWfUs4aqJ-lwssBc/images/integrations/reapit/reapit.png?fit=max\&auto=format\&n=lWfUs4aqJ-lwssBc\&q=85\&s=ab2a28d2e3fd32a65cc0b6929dcd0b6a) > > ### Reapit > > Reapit property software integration > > [Open](/integrations/reapit) > [card] > > ![Oracle Cloud](https://mintcdn.com/loqate/_cmDD1AL7C3KSiW2/images/integrations/oracle-cloud/oracle-cloud-logo.png?fit=max\&auto=format\&n=_cmDD1AL7C3KSiW2\&q=85\&s=08dc9b965756527d74f9cdca57780a0c) > > ### Oracle Cloud > > OCI deployment and Oracle Integration adapters > > [Open](/integrations/oracle-integration-cloud-overview) # BigCommerce Integration Source: https://docs.loqate.com/integrations/bigcommerce Add Loqate type-ahead address lookup to your BigCommerce store with a generated code snippet and Script Manager. No custom development needed. ### Works with: BigCommerce storefronts ### Supported Loqate Services:
      [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration Add Loqate's type-ahead address lookup to your BigCommerce store without custom development. You generate a code snippet in your Loqate account, with field mappings that match the standard BigCommerce field layout, and add it to your store using BigCommerce's Script Manager. ## Supported Loqate Services > [tab] Address Capture > > ### Type-Ahead Address Lookup > > Customers start typing their address and select from a list of suggestions, reducing input time and errors. > > **Key Features:** > > * Code snippet generated for you in your Loqate account > * Field mappings generated to match the standard BigCommerce field layout > * Added to your store through Script Manager, with no theme changes required > > [Learn more about Address Capture](/our-services/address-capture/overview) > [card] [Setup guide](/integrations/bigcommerce-setup-guide) > > Generate your code snippet and add it to BigCommerce Script Manager ## Integrate in 3 steps 1\) Create your Loqate account 2) Generate your code snippet 3) Add it to Script Manager > [card] > > Create your account, then add Loqate to Script Manager > > Generate a BigCommerce code snippet in your Loqate account and paste it into Script Manager. > > 1. Create Your Account > > [Open](https://account.loqate.com/Register/) > > 2. Generate Your Snippet > > [Open](/integrations/bigcommerce-setup-guide#generate-your-code-snippet) > > 3. Add to Script Manager > > [Open](/integrations/bigcommerce-setup-guide#add-the-snippet-to-script-manager) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Do I need to write any code? > > No. Your Loqate account generates the code snippet for you. You paste it into the **Script Contents** area of a new script in BigCommerce's Script Manager. > [accordion] How are address fields mapped? > > When you set up the service, the **Generate my mappings** option creates mappings that match the standard BigCommerce field layout. > [accordion] Do I need a Loqate account? > > Yes. If you don't already have one, you can [sign up](https://account.loqate.com/Register/) before you start. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB ### Platform BigCommerce # BigCommerce Setup Guide Source: https://docs.loqate.com/integrations/bigcommerce-setup-guide Generate a Loqate code snippet with BigCommerce field mappings and add it to your store with Script Manager. Before you start, make sure you have a Loqate account. If you don’t already have one, you will need to [sign up](https://account.loqate.com/Register/). For an overview of what the integration does, see the [BigCommerce integration overview](/integrations/bigcommerce). ## Setup In order to set up Loqate for BigCommerce, please follow these steps. ### Generate your code snippet * In your Loqate account select **+ Add a service**: ![AddService](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/getting-started/add-service-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=e8d0591353eb3d08e9ea566650dbe847) * Then select **Start setup**. ![StartSetup](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/start-setup-june-25.PNG?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=46e5533ea7cf4d80eb8d09a731ba4da4) * You will be presented with two options: Website or App. Select **App**, tick **BigCommerce** from the suggested options below, and hit **Next**. ![SelectApp](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/select-app-june-25.PNG?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=ceb475ba449376123e5928eeeb8494f7) * Here you will be presented with a code snippet. Copy this, as you'll need to use it later. * Click the "Generate my mappings" button at the bottom of the page. This will generate mappings that match the standard BigCommerce field layout. ### Add the snippet to Script Manager * Next, log in to BigCommerce and go to **Script Manager**. You can access this by clicking Sidebar > Storefront > Script Manager. ![BigCommerceScriptManager](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/script-manager.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=7f3f166772b1ca3ca5496c68b9d31c0c) * Once in this section you want to add Script Library, then fill out the checkboxes as follows: ![Checkboxes1](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/checkboxes-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=a99f9554618403f429439d3797c2c10d) ![Checkboxes2](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/checkboxes-2.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=6003a2628be2888540030b6a2ea0b01a) * In the **Script Contents** area, paste the code snippet you generated earlier. * Once this has been done the Loqate functionality will work as follows: ![LoqateAddressLookup](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/big-commerce/loqate-address-lookup.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=becccc60f8e76ce841ec176c98dd43c8) ## Troubleshooting If you require any help, please do not hesitate to get in touch with our [support teams](https://www.loqate.com/en-gb/contact/customer-support/). # commercetools Integration Source: https://docs.loqate.com/integrations/commercetools Reference implementation for integrating Address Capture, Address Verify, Email and Phone Validation with commercetools Frontend checkout, My Account and registration. ### Works with: commercetools Frontend (B2C template) ### Supported Loqate Services:
        [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate commercetools plugin ([`loqate-commercetools`](https://github.com/loqate/loqate-commercetools)) integrates [the commercetools platform](https://commercetools.com/) with the Loqate API to provide Address Capture, Address Verify, Email Validation and Phone Validation in the **Checkout**, **My Account** and **Registration** flows. The modifications are applied in two areas: * **Backend-for-frontend (BFF):** commercetools extensions that make the Loqate API calls and handle the responses * **Frontend:** React components that display the Loqate features to your customers > [!WARNING] > > The plugin is a **reference implementation** built on the [commercetools Frontend B2C template](https://docs.commercetools.com/frontend-development/b2c-store-launchpad-overview) (latest as of 3 June 2024). It is not intended to be cloned and used as-is in production. Copy the relevant parts into your own implementation instead. See [Disclaimers](#disclaimers) for details. ## Supported Loqate Services Each service can be toggled on or off through project settings. The configuration options below are set in [Studio settings](/integrations/commercetools-studio-settings). > [tab] Address Capture > > ### Type-Ahead Address Lookup > > Address Capture suggests possible addresses based on user input. > > **How it works:** > > * Calls to the [Find](/api-reference/address-capture/find) endpoint are made continuously until an address of type `Address` is found > * If the type is `Container`, the system continues making calls to the Find endpoint > * Once an address of type `Address` is found, the [Retrieve](/api-reference/address-capture/retrieve) endpoint is called to capture the full address details > > **IP to Country:** determines the user's country based on their IP address, and auto-populates the country field with the result. > > **Configuration options:** > > * `LOQATE_IP_TO_COUNTRY_ENABLED` - toggle for IP to Country functionality > * `LOQATE_ADDRESS_LOOKUP_CHECKOUT` - toggle for address lookup during checkout > * `LOQATE_ADDRESS_LOOKUP_MY_ACCOUNT` - toggle for address lookup on the My Account page > * `CHECKOUT_ADDRESS_REQUEST_LIMIT` - debounce time for address capture requests > * `RESTRICTED_COUNTRIES` - list of restricted country ISO2 codes to exclude from address capture suggestions > > **Integration areas:** Checkout, My Account > > See the [Address Capture API documentation](/api-reference/address-capture/apis) or [learn more about Address Capture](/our-services/address-capture/overview). > [tab] Address Verify > > ### Address Verification > > Address Verify evaluates the validity of the address on form submission, using fields like country, city, postal code and street address. Based on the response, the address is scored as `Good`, `Questionable` or `Invalid` using the [Address Verification Code](/report-codes/address-verification-code/): > > * **Good:** no issues detected > * **Questionable:** the user is prompted to accept a corrected address suggested by Address Verify. The user can either edit the address manually or proceed with the initial input > * **Invalid:** a suggestion is provided to update the address. The user can either update it or proceed with the original input > > **Configuration options:** > > * `LOQATE_ADDRESS_VERIFICATION_CHECKOUT` - toggle for address verification during checkout > * `LOQATE_ADDRESS_VERIFICATION_MY_ACCOUNT` - toggle for address verification on the My Account page > * `LOQATE_AVC` - minimum matchscore threshold for an address to be considered `Good` > > **Integration areas:** Checkout, My Account > > See the [Address Verify API documentation](/api-reference/address-verify/international-batch-cleanse) or [learn more about Address Verify](/our-services/address-verify/overview). > [tab] Email Validation > > ### Email Address Validation > > Email Validation verifies the user's email address during input, ensuring the format is correct and that the address is valid. > > **Configuration options:** > > * `LOQATE_EMAIL_VALIDATION_CHECKOUT` - toggle for email validation during checkout > * `LOQATE_EMAIL_VALIDATION_MY_ACCOUNT` - toggle for email validation on the My Account page > * `LOQATE_EMAIL_VALIDATION_REGISTRATION` - toggle for email validation during registration > * `LOQATE_EMAIL_VALIDATION_TIMEOUT_MILLISECONDS` - timeout duration for email validation requests > * `LOQATE_INCLUDE_VALID_CATCHALL_EMAILS` - determines whether `Valid_CatchAll` responses are considered valid (see the `ResponseCode` response field in the API documentation) > > **Integration areas:** Checkout, My Account, Registration > > See the [Email Validation API documentation](/api-reference/email-validation/apis) to learn more about the service. > [tab] Phone Validation > > ### Phone Number Validation > > Phone Validation checks the correctness of the phone number the user enters, ensuring it is properly formatted and valid. > > **Configuration options:** > > * `LOQATE_PHONE_VALIDATION_CHECKOUT` - toggle for phone validation during checkout > * `LOQATE_PHONE_VALIDATION_MY_ACCOUNT` - toggle for phone validation on the My Account page > * `LOQATE_PHONE_VALIDATION_REGISTRATION` - toggle for phone validation during registration > * `LOQATE_INCLUDE_MAYBE_PHONE_NUMBERS` - determines whether the `Maybe` validation state is treated as valid (see the `IsValid` response field in the API documentation) > > **Integration areas:** Checkout, My Account, Registration > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/commercetools-setup-guide) > > Install the plugin and apply the backend-for-frontend and frontend changes > [card] [Studio settings](/integrations/commercetools-studio-settings) > > Configure the plugin in commercetools Frontend Studio ## Integrate in 3 steps 1\) Get your API key 2) Clone the repository 3) Configure and integrate > [card] > > Get your API key, then start from the reference implementation > > Clone the repository, configure the project in Studio, and carry the changes over to your own project. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Clone the Repository > > [Open](https://github.com/loqate/loqate-commercetools) > > 3. Configure and Integrate > > [Open](/integrations/commercetools-setup-guide) ## Additional Resources [loqate-commercetools on GitHub](https://github.com/loqate/loqate-commercetools) [commercetools Frontend development docs](https://docs.commercetools.com/frontend-development/cli) ## Disclaimers The loqate-commercetools repository demonstrates the integration of Loqate Address Capture, Address Verify, Email Validation and Phone Validation features with commercetools. It is to be used as a reference implementation for your own integration - it is not intended to be used as is in a production environment. Please refer to the [Setup Guide](/integrations/commercetools-setup-guide) for instructions on the changes required to carry over the Loqate commercetools integration into your own project. It uses the [commercetools Frontend B2C template](https://docs.commercetools.com/frontend-development/b2c-store-launchpad-overview) as a base, specifically the latest as of 3 June 2024. This plugin: * Does not aim to keep up with the latest changes in the commercetools frontend template, but rather to provide a reference implementation * Should not be cloned and used as is in a production environment. It is recommended to use it as a reference and adapt it to your own needs by copying the relevant parts of the code and applying them to the merchant’s implementation * Does not aim to fix any bugs or issues in the commercetools frontend template. If you encounter any issues related with the B2C Frontend Template, please refer to the commercetools documentation * Is not responsible for any bugs or issues coming from the commercetools B2C Frontend Template, nor any customizations made to it and does not aim to fix them. You should refer to the commercetools documentation for support for any issues related to the specific version of the commercetools B2C Frontend Template that you are using * Does not take an opinion of the flow you should support in your store - it applies changes to the out of the box checkout, my account and registration flows ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Can I use the plugin as-is in production? > > No. The plugin is a reference implementation. Get the latest version of the commercetools B2C Frontend template and apply the backend-for-frontend and frontend changes described in the [setup guide](/integrations/commercetools-setup-guide) on top of your existing implementation. > [accordion] What do I need before I start? > > Node.js 18.16.0 or higher, Yarn 1.22.19 or higher, a commercetools project, commercetools Frontend Studio, and a [Loqate API key](/loqate-basics/create-an-api-key). > [accordion] Which parts of my store does it change? > > The plugin modifies the out-of-the-box Checkout, My Account and Registration flows. It doesn't take an opinion on which flows you should support in your store. > [accordion] Can I turn individual features on and off? > > Yes. Each feature can be toggled per area through the project settings. See [Studio settings](/integrations/commercetools-studio-settings) for the full list. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform commercetools Composable Commerce [View on GitHub](https://github.com/loqate/loqate-commercetools) # commercetools Setup Guide Source: https://docs.loqate.com/integrations/commercetools-setup-guide Install Loqate validation in commercetools B2C Frontend. Backend-for-frontend controller setup and React component integration instructions. ## Prerequisites * Node.js 18.16.0 or higher * Yarn 1.22.19 or higher * A commercetools project * commercetools Frontend Studio * [A Loqate API key](/loqate-basics/create-an-api-key) ## Disclaimers * The loqate-commercetools repository is meant to be used as a reference to integrate Loqate services into a commercetools B2C Frontend project * In order to do so, you will need to get the latest version of the commercetools B2C Frontend template and apply the changes described in the [Backend-for-Frontend Changes](#backend-for-frontend-changes) and [Frontend Changes](#frontend-changes) sections on top of your existing implementation * On the frontend, the visual appearance of this Loqate integration is meant to be relatively simple and independent so that it can be carried over to your own project with minimal effort * On the backend-for-frontend, the Loqate integration is implemented so that it can be carried over to your own project with minimal effort ## Installation * Clone [the repository](https://github.com/loqate/loqate-commercetools) * Run the standard commercetools Frontend setup process as described in the [commercetools Frontend development docs](https://docs.commercetools.com/frontend-development/cli) ## Project configuration - Studio settings Please refer to the [Studio Settings](/integrations/commercetools-studio-settings) documentation for instructions on how to configure the project. ## Backend-for-frontend changes ### LoqateController The `LoqateController` is a key component that interacts with the Loqate API to handle address capture, address verification, and validation for email and phone numbers. It serves as the gateway for these services, ensuring they are integrated within the commercetools environment. **Key features:** * **Loqate API Client:** the controller initializes the `LoqateApi` client, configured with project settings like API key, address quality threshold, and validation timeouts * **Address Management:** it provides methods for capturing, verifying, and validating addresses based on user input * **Email & Phone Validation:** the controller includes email and phone validation methods that ensure the correctness of these fields as per the rules defined in the Loqate API * **IP-based Country Detection:** it also enables the retrieval of the user’s country based on their IP address for better geolocation-based address suggestions ### Controller functions overview **1. `createLoqateApi(actionContext: ActionContext): LoqateApi`** * **Description:** this function creates a `LoqateApi` client instance using the project configuration. The API key, address verification threshold, and other settings are passed to the client. This ensures that each API call is correctly authenticated and configured according to the commercetools project * **Use case:** called internally by the controller before making requests to the Loqate API **2.** `getAddresses(request: Request, actionContext: ActionContext): Promise` * **Description:** this function handles address lookup requests. It takes user-provided details (like text, city, country) and returns address suggestions from the Loqate API. The result is a list of possible address matches based on the input * **Use case:** used during My Account adding of new address or checkout forms to provide real-time address suggestions as the user types * **Parameters:** * `request`: contains query parameters such as `id`, `address`, `countryIsoCode`, and `city` * `actionContext`: provides access to the current commercetools project configuration * **Response:** returns a list of matching addresses in JSON format **3.** `verifyAddress(request: Request, actionContext: ActionContext): Promise` * **Description:** verifies the accuracy of a provided address by checking against Loqate’s address verification system. It validates fields such as country, postal code, and city * **Use case:** called when the user submits a form that requires verified address data, such as during checkout * **Parameters:** * `request`: contains the address details (`country`, `postalCode`, `city`, and `address`) to be verified * `actionContext`: accesses the commercetools project configuration * **Response:** returns whether the address is valid, questionable, or invalid **4.** `getCountryByIp(request: Request, actionContext: ActionContext): Promise` * **Description:** retrieves the country of the user based on their IP address, leveraging Loqate’s IP-to-country service. If the request does not directly provide the client IP, it attempts to extract it from the `x-forwarded-for headers` * **Use case:** used to pre-fill the country field in checkout or registration forms for a better user experience * **Parameters:** * `request`: contains the client IP address or retrieves it from headers * `actionContext`: provides the commercetools project configuration * **Response:** returns the country detected from the user’s IP address **5.** `validateEmail(request: Request, actionContext: ActionContext): Promise` * **Description:** validates an email address using Loqate’s Email Validation service, ensuring that the email is correctly formatted and that it meets the required validation criteria * **Use case:** used to validate email addresses during registration, checkout, or other form submissions where email accuracy is essential * **Parameters:** * `request`: contains the email address to be validated * `actionContext`: accesses project configuration for Email Validation settings * **Response:** returns the validation status of the email (e.g., valid, invalid, or catch-all) **6.** `validatePhone(request: Request, actionContext: ActionContext): Promise` * **Description:** validates a phone number provided by the user using Loqate’s Phone Validation service, ensuring the phone number format is correct and valid for the given country * **Use case:** typically used during checkout or registration to ensure that users provide valid contact numbers * **Parameters:** * `request`: contains the phone number and the country code for validation * `actionContext`: provides project-specific settings for phone validation * **Response:** returns the validation status of the phone number **7.** `getSettings(request: Request, actionContext: ActionContext): Promise` * **Description:** retrieves and returns the project settings related to the Loqate integration. These settings determine the behaviour of Address Capture, Address Verify, Email Validation and Phone Validation features * **Use case:** this function is used to get the current Loqate-related settings for specific use cases, such as checkout or account management * **Response:** returns a JSON object containing the current configuration for Loqate in the project **8.** `getRestrictedListedCountries(request: Request, actionContext: ActionContext): Promise` * **Description:** fetches a list of countries that are restricted from using Loqate services in the current project. This can be used to prevent address capture or validation in specific regions * **Use case:** used in form validations to check if a user’s country is restricted before allowing further actions * **Response:** returns a JSON object containing restricted countries ### LoqateApi class overview **Key Methods in** `LoqateApi` * `getAddresses()`: fetches address suggestions based on user input * `verifyAddress()`: verifies the accuracy of a provided address * `getCountryByIp()`: retrieves the user’s country based on their IP address * `validateEmail()`: validates the format and deliverability of an email address * `validatePhone()`: validates the format and correctness of a phone number ### Utility functions `isValidAddress(matchScore, addressVerificationLevel, goodAddressMinimumMatchscore)` * Description: checks if an address is valid based on its matchscore and verification level * Use Case: used to determine if an address should be accepted as valid, questionable, or invalid `extractDescription(description)` * **Description:** extracts the postal code and city from an address description string * **Use Case:** used internally to parse and normalise address data `extractCountryIsoCode(id)` * **Description:** extracts the country ISO code from an address ID string * **Use Case:** helps to normalise address data ## Frontend changes ### Loqate Context The `LoqateContext` provides a centralized state management system for Loqate-related features such as address capture, address verification, email validation, and phone validation. It encapsulates multiple Loqate API integrations and makes them accessible to components throughout the application via React’s context API. **Key Responsibilities:** * **Address Lookup:** Listens to user input and fetches address suggestions from the Loqate API, debouncing the requests to reduce unnecessary API calls. The context updates the suggested addresses list and allows the user to select an address. * **Address Verification:** Verifies the address provided by the user using the Loqate API. It triggers validation when an address is manually entered or submitted. The context validates the address based on the Loqate response, ensuring its accuracy. * **Email and Phone Validation:** Integrates email and phone number validation, with the ability to validate inputs using the corresponding Loqate APIs. Results are stored in the context for use across components like checkout or user account management. * **IP-to-Country Mapping:** Automatically fills in the country based on the user’s IP address, improving user experience and preventing invalid country selections. Here’s a detailed description of the exposed functions in the `LoqateContext`: **Exposed functions** **1.** `setLoqateAddress(value: LoqateAddress)` * **Description:** updates the current address stored in the context based on the user’s input or address selection. It triggers address suggestions when the input changes and resets the address verification state if the address changes * **Use case:** called whenever the user updates their address input, whether through manual input or selecting an address from the suggestions dropdown * **Parameters:** * `value`: the updated address object containing fields like `text`, `city`, `countryIsoCode`, etc. **2.** `verifyAddress(loqateAddress: LoqateAddress): Promise` * **Description:** verifies the provided address using the Loqate API to ensure it’s valid. It returns a `LoqateIsValidAddress` object, indicating whether the address is valid or not * **Use case:** used to validate addresses during adding of new address in My Account or checkout processes where accurate address entry is critical * **Parameters:** * `loqateAddress`: the address object that needs to be verified * **Returns:** a promise resolving to an object with `isValid: true` or `false` depending on whether the address is valid **3.** `validateEmail(): Promise` * **Description:** validates the email address associated with the current Loqate address. If Email Validation is enabled in the Loqate settings, it sends the email to Loqate’s validation API and updates the context with the result * **Use case:** triggered to validate an email when users input their email address in a form, commonly during registration or checkout * **Returns:** a promise resolving to a boolean indicating whether the email is valid (`true`/false`), or `undefined\`\`\` if validation is not enabled **4.** `validatePhone(): Promise` * **Description:** validates the phone number provided in the `LoqateAddress` object using the Loqate API. If Phone Validation is enabled, it checks the number’s format and correctness based on the country * **Use case:** used to validate phone numbers during form submission (e.g., in checkout forms) to ensure that the provided number is valid * **Returns:** a promise resolving to a boolean indicating whether the phone number is valid (`true`/`false`), or `undefined` if validation is not enabled **5.** `setBypassAddressVerification(bypass: boolean)` * **Description:** sets a flag to bypass Address Verify. This is useful in scenarios where the user wants to skip the verification process or manually override an invalid address * **Use case:** typically used when users manually input invalid or questionable addresses and opt to bypass automatic verification for any reason by * **Parameters:** * `bypass`: a boolean value that, when set to `true`, bypasses Address Verify **6.** `setLoqateSettings(loqateSettings: LoqateSettings)` * **Description:** updates the Loqate settings used for address lookup and validation, including enabling or disabling email, phone, and address validation features * **Use case:** used to configure or reconfigure Loqate settings dynamically (e.g., different pages might require different settings) * **Parameters:** * `loqateSettings`: the settings object that dictates how Loqate functionality is used (e.g., enabling/disabling email or phone validation) The context handles API calls using RxJS operators like `debounceTime`, `distinctUntilChanged`, and `switchMap` to manage user input efficiently and ensure smooth address verification and lookup processes. ## Address Capture The `AddressCapture` component is responsible for capturing and suggesting addresses based on user input. It integrates seamlessly with the Loqate Context and allows for dynamic address suggestions and selection. **Key features:** * **Input field:** the component displays an input field where users can begin typing their address. As they type, the component fetches address suggestions from Loqate based on the user’s input * **Address suggestions dropdown:** while the input field is focused, the component shows a dropdown of suggested addresses. These suggestions come from the Loqate API, and users can click on any suggestion to populate the address fields automatically * **Manual and auto address handling:** the component supports both manual entry and auto-selection of addresses. If a user selects an address from the dropdown, the address is treated as an auto-populated value, while manual entries bypass the suggestion feature * **Debouncing and API efficiency:** to minimize API calls, user input is debounced, ensuring that requests are only sent after a specified delay in typing * **Handling nested addresses (address containers):** in cases where the address suggestion is a container (e.g., a boulevard that contains many addresses), the component displays an icon, allowing the user to recognize such cases and continue refining their search ## Restricted Countries This code defines a React custom hook called `useRestrictedCountries` that retrieves and manages the list of countries that are not restricted, filtering out any countries that are restricted based on an external API call to the `loqate/getRestrictedCountries` action via the `commercetools` SDK. ### Key elements **1.** **State management:** * `countries`: this state holds the list of available countries, which is initialized with a static list of all countries (`allCountries`) * `fetchingInProgress`: a boolean state to track if the fetching process is currently ongoing * `successfullyFetched`: a boolean state indicating whether the fetching was successfully completed **2.** **API integration:** * The `fetchRestrictedCountries` function asynchronously calls the `loqate/getRestrictedCountries` API action using the `commercetools SDK`. It expects a response containing restricted country codes **3.** **Logic for filtering restricted countries:** * The API response provides a list of restricted countries * The list of restricted countries is mapped and filtered to remove any invalid entries (i.e., missing or empty country codes) * The hook filters out the restricted countries from the full list (`allCountries`) **4.** **Side effects (useEffect):** * On component mount, the hook triggers the API call to fetch restricted countries * During this process, `fetchingInProgress` is set to `true` and `successfullyFetched` is updated based on whether the call succeeds or fails * In case of an error, the hook logs the error and falls back to the default list of all countries **5.** **Observable and RxJS integration:** * The code uses RxJS operators (`map`, `tap`, `catchError`) to handle the API call, map the response, and manage error handling * The `subscribe` function applies the country filtering logic and updates the `countries` state accordingly ## Navigation > [card] [commercetools Overview](/integrations/commercetools) > > Learn what the integration does and review the Loqate products available. > [card] [commercetools Studio Settings](/integrations/commercetools-studio-settings) > > Configure the Loqate plugin in the commercetools Studio. # commercetools Studio Settings Source: https://docs.loqate.com/integrations/commercetools-studio-settings Configure Loqate Address Capture, Address Verify, Email and Phone Validation in commercetools Studio. Set API keys and validation thresholds. Refer to the [commercetools Frontend Studio documentation](https://docs.commercetools.com/frontend-studio/accessing-the-studio) for instructions on how to access the studio. ![StudioSettings](https://mintcdn.com/loqate/Qk0UlsZU23OElwd1/images/commercetools-studio-settings.png?fit=max\&auto=format\&n=Qk0UlsZU23OElwd1\&q=85\&s=3c82da8bf26629f9584df75d2e70fef2) ## Settings The following settings are configurable in the `Project settings`, found in the `projectConfiguration.json` file: | Name | Env Variable | Description | | :- | :- | :- | | `Project Key` | LOQATE\_API\_KEY | The API key used to authorize requests against Loqate | | `IP to Country` | LOQATE\_IP\_TO\_COUNTRY\_ENABLED | Toggles IP to country functionality on or off | | `Restricted Countries` | RESTRICTED\_COUNTRIES | A list of restricted country ISO2 codes | | `Checkout Address Request Limit` | CHECKOUT\_ADDRESS\_REQUEST\_LIMIT | Debounce time for address capture requests | | `Checkout Address Lookup` | LOQATE\_ADDRESS\_LOOKUP\_CHECKOUT | Toggle for address lookup during checkout | | `My Account Address Lookup` | LOQATE\_ADDRESS\_LOOKUP\_MY\_ACCOUNT | Toggle for address lookup on the My Account page | | `Checkout - Address Verify` | LOQATE\_ADDRESS\_VERIFICATION\_CHECKOUT | Toggle for address verification during checkout | | `My Account - Address Verify` | LOQATE\_ADDRESS\_VERIFICATION\_MY\_ACCOUNT | Toggle for address verification on the My Account page | | `Checkout Email Validation` | LOQATE\_EMAIL\_VALIDATION\_CHECKOUT | Toggle for email validation during checkout | | `My Account Email Validation` | LOQATE\_EMAIL\_VALIDATION\_MY\_ACCOUNT | Toggle for email validation on the My Account page | | `Checkout Phone Validation` | LOQATE\_PHONE\_VALIDATION\_CHECKOUT | Toggle for phone validation during checkout | | `My Account Phone Validation` | LOQATE\_PHONE\_VALIDATION\_MY\_ACCOUNT | Toggle for phone validation on the My Account page | | `Registration Phone Validation` | LOQATE\_PHONE\_VALIDATION\_REGISTRATION | Toggle for phone validation during registration | | `Maybe' Phone Number Validation State is Valid` | LOQATE\_INCLUDE\_MAYBE\_PHONE\_NUMBERS | Determines whether the `Maybe` phone number validation state is treated as valid | | `Valid_CatchAll' Email Validation State is Valid` | LOQATE\_INCLUDE\_VALID\_CATCHALL\_EMAILS | Determines whether `Valid_CatchAll` email validation responses are considered valid | | `Email Validation Timeout (milliseconds)` | LOQATE\_EMAIL\_VALIDATION\_TIMEOUT\_MILLISECONDS | Timeout duration for email validation requests | | `AVC - Good Address Matchscore` | LOQATE\_AVC | The minimum matchscore threshold for an address to be considered `Good` | ## Navigation > [card] [commercetools Overview](/integrations/commercetools) > > Learn what the integration does and review the Loqate products available. > [card] [commercetools Setup Guide](/integrations/commercetools-setup-guide) > > Follow these steps to get started. # Microsoft Dynamics 365 Integration Source: https://docs.loqate.com/integrations/microsoft-dynamics-365 Add Loqate Address Search, Email and Phone Verification controls to Microsoft Dynamics 365 forms. Import the solution and configure each field. ### Works with: Microsoft Dynamics 365 ### Supported Loqate Services:
          [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate Dynamics 365 integration is a solution you import into your Dynamics 365 environment. It adds Loqate controls that you attach to the fields on your forms, so users can search for addresses and verify email addresses and phone numbers as they enter customer details. Each control is configured per field in the form editor, so you choose exactly which forms and fields use Loqate. ## Supported Loqate Services > [tab] Address Capture > > ### Address Search > > The **Loqate - Address Search** control adds type-ahead address lookup to a field on your form and populates the rest of your address fields when an address is selected. > > **Key Features:** > > * Map each returned address item to the form field of your choice > * Configure Capture Find request parameters directly on the control > * Works alongside forms that use the compound address field > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Email Validation > > ### Email Verification > > The **Loqate - Email Verification** control lets users validate an email address directly from the form. > > **Key Features:** > > * Optionally prevent the form being saved until a valid email address is entered > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone Verification > > The **Loqate - Phone Verification** control lets users select a country and validate a phone number directly from the form. > > **Key Features:** > > * Optionally prevent the form being saved until a valid number is entered > * Choose how a "Maybe" response from Phone Validation is treated > * Set the initial country from the user's IP address, or a default country > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/microsoft-dynamics-365-setup-guide) > > Import the Loqate solution and configure the controls on your forms ## Integrate in 3 steps 1\) Get your API key 2) Download the solution 3) Import and configure your forms > [card] > > Get your API key, then import the Loqate solution > > Import the solution into Dynamics 365 and add the Loqate controls to your form fields. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Download the Solution > > [Open](https://assets.loqate.com/dynamics-integration/latest/loqate_dynamics_latest.zip) > > 3. Import and Configure > > [Open](/integrations/microsoft-dynamics-365-setup-guide#importing-the-solution) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] What do I need to install the integration? > > You need the Loqate solution zip file, a Loqate API key, and administrative access to your Dynamics 365 environment. > [accordion] Can I stop users saving invalid email addresses or phone numbers? > > Yes. The Email Verification and Phone Verification controls each have an option that prevents the form being saved until a valid value has been entered and verified. > [accordion] My form uses the compound address field. Can I still use Address Search? > > Yes. You can either replace the compound field with individual address fields, or add a separate field to your form to handle the address lookup. The [setup guide](/integrations/microsoft-dynamics-365-setup-guide#address) walks through the second option. > [accordion] How do I update to a new version of the solution? > > Import the new solution zip file the same way as a new installation. Dynamics 365 shows a warning when you're updating an existing installation to a new version. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Microsoft Dynamics 365 [Download the latest solution](https://assets.loqate.com/dynamics-integration/latest/loqate_dynamics_latest.zip) # Microsoft Dynamics 365 Setup Guide Source: https://docs.loqate.com/integrations/microsoft-dynamics-365-setup-guide Import the Loqate solution into Dynamics 365 and add Address Search, Email and Phone Verification controls to your forms. > [card] [Download the Microsoft Dynamics 365 plugin](https://assets.loqate.com/dynamics-integration/latest/loqate_dynamics_latest.zip) This guide will take you through the steps required to install and configure the Loqate Dynamics 365 integration in your Dynamics 365 instance. For an overview of what the integration does, see the [Microsoft Dynamics 365 integration overview](/integrations/microsoft-dynamics-365). ## Prerequisites In order to install and configure the Loqate Dynamics 365 integration you will need the following: * The Loqate solution zip file * A Loqate API key (for more information see our [Creating API Keys page](/loqate-basics/create-an-api-key)) * Administrative access to your Dynamics 365 environment ## Installation Installing the Loqate Dynamics 365 integration involves the following steps: 1. [Import the solution](#importing-the-solution) 2. [Configure your forms to use Loqate controls](#configuring-your-forms) (for each form you can add controls for Email Verification, Phone Verification and Address Search) We will talk you through how to complete each step, using a standard contact form as an example (you can then apply the same process to each of your forms as required). ## Importing the solution * From your Dynamics 365 environment select Settings > **Advanced Settings**. This will open your Business Settings in a new tab * From the Customisation section of the menu, select **Solutions** * Select **Import Solution** ![D365 Install 1](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/d365-install-1s.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=9ce7ab68a9bd7d72f3938ecbc8bfb1c7) * A menu will appear allowing you to browse for the Loqate solution zip file - select this and click **Next** * The version of the solution you're importing will display, and you will see a warning if you're updating an existing installation to a new version, or installing a version you’ve already installed previously ![D365 Install 2](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/d365-install-2s.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=edd5d1e9a3ccd2a8d89f07ad0cd299f0) * Select **Import** * A bar will appear at the top of the page reading 'Currently importing solution “loqate\_dynamics”.' ![D365 Install 3](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/d365-install-3s.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=1c0420bdb29624c47955ab224b71f5c5) * If you need to navigate away while this is importing, you can - the process will run in the background * Once the import is complete, the progress bar will turn green and read 'Solution “loqate\_dynamics” imported successfully' ![D365 Install 4](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/d365-Install-4s.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=36c480bc8de832d7f4ba8c2ebf0d3b82) At this point you can move on to the next step, and start configuring your forms. ## Configuring your forms With the solution imported into your environment, the next step is to configure your forms to use Loqate controls. There is a control for each of the services available in the solution (you can click the links below to go to the relevant section of this document): * [Email Verification](#email) * [Phone Verification](#phone) * [Address Search](#address) The configuration method is similar for each control, although the specific configuration options are different depending on which control you're using. For this example we’re going to add the controls to the standard Customer Contact form, which looks like this: ![Dynamics Contact List](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-contact-list.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=0cac3877f9e47b9b964f7d763618df0f) Your forms may well be different and contain different fields or configurations, but you can apply the same principles. We’re going to add Loqate controls to the Email, the Mobile Phone and Address 1 fields. All control configurations happen on the form editor. ### Email Here are the steps to take to add Loqate controls to the Email field. * From your Dynamics 365 environment select Settings > **Advanced Settings**. This will open your Business Settings in a new tab * From the Customisation section of the menu, select Customizations > **Customise the system** * Select the form you want to update (for this example we're editing “AI for sales”) to open the form editor ![Dynamics Form List](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-form-list.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=e5804f084839311e1837c2c086f6b81c) The form editor is where you will be configuring the Loqate controls for your fields. If you’re following the guides for Phone and Email and the steps say “Go to the form editor for your form”, this is where you want to be. * Select the Email field in your form to open its Properties menu on the right-hand side of the screen * Expand the Components section, and select the **+ Component** button ![Dynamics Add Component](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-add-component.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=7ba387f189391f394a6022501b094833) * If you’ve installed or used Loqate before, the Email control may already be in the quick selection menu. If this is the first time you’re installing Loqate, however, you’ll likely need to look the component up * To do this, select **Get more components** ![Dynamics Component List](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-component-list.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=5312f7568fe0811744e0fef6e48f4a96) * Use the search bar to search for “Loqate”. The control is called **Loqate - Email Verification** * Once you have selected the control you will be prompted for some configuration information ![Dynamics Email Configuring](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-email-configuring.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=4dd816b1e8af5e1d46afd25bafe94b8f) * The options available for Email Verification are: * **API Key:** your API key for accessing Loqate services (this is a **required field**) * **Prevent saving invalid emails:** with this set to True, when an email is verified and found to be invalid a user will not be able to save the form until they have entered and validated a correct email address * With those settings entered, select Done to set the component * You should now see the component update in the preview ![Dynamics Email Field Updated](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-email-field-updated.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=baed34fded0ff7c252987b8eecd48280) * Select **Save and Publish** to update your form and publish the control. Depending on your form setup, this can take a little time. Once the form is published, the Email field will be using the Loqate control. By clicking the button you will now be able to validate an entered email address. ### Phone Installing the phone control is a similar process to the Email control, just with a couple of extra options. * Go to the Form editor for your form * Select the **Phone** field to open its Properties menu * Expand the Components section, and select the **+ Component** button * Find the **Loqate - Phone Verification** control and select it * Here are the options for this control: * **API Key:** your API key for accessing Loqate services (this is a required field) * **Prevent saving invalid numbers:** with this set to True, when a number is verified and found to be invalid a user will not be able to save the form until they have entered and validated a correct number * **Pass if Maybe:** it's possible for the Phone Validation service to respond with a status of “Maybe”. This option will allow you to select how you want the control to behave in this scenario: setting this to **True** will mean the control returns a positive result for a maybe, while **False** will result in a negative response * **Use client IP to set initial country:** sets whether the plugin should use the client's IP address to automatically detect and set the initial country for phone validation. If enabled, the country will be set based on the client's IP address; if disabled, the initial country specified below will be used. * **Initial Country (ISO2):** the initial country to use for the phone number validation (e.g., 'US', 'GB'). This will be used if the client IP is not available, or if the option above is set to False * When you have set your options, select **Done** * You should see the control update in the preview window ![Dynamics Phone Control Updated](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-phone-control-updated.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=655d6adfa3334b0bdb2404f867dd672b) * Select **Save and Publish** to update your form and publish the control. Depending on your form setup, this can take a little time Once the form is published, the Phone field will be using the Loqate control. By selecting a country and clicking the button you will be able to validate an entered phone number. ### Address Installing the address control is a similar process to the Email and Phone controls, but might require an extra step or two. NOTE: in the Form editor for your form, you might notice that the address fields are included as a set, and you're not able to select them individually: ![Dynamics Address Fields](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-address-fields.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=27511522fb6c95574d6659abbef8d732) This is because the Compound field is often used to add addresses to forms. There are a couple of options for how you manage this: * You could remove this part of the form and add the other parts individually * Or you could add another separate field to handle the address lookup For this example we’ll do the second option. Here are the steps to take to do this: * Drag the **Address 1: Street 1** field from the column list on the left, and drop it above the existing address fields * Select the new field to open its Properties menu, and set its Label to "Address Finder" (or another description of your choice) * Expand the Components section, and select the **+ Component** button * Find and select the **Loqate - Address Search** control * Here are the available options for this control: * **API Key:** your API key for accessing Loqate services (this is a **required** field) * **Input fields:** the set of options from 'Origin' down to 'Field20Format' all relate to Loqate input fields, and how you want to use them. You can find more information on what these options do in the **Request parameters** section of our [Capture Find API page](/api-reference/address-capture/find) * **Address:** the set of options from 'Address Line 1' onwards allow you to set where each different address item is inputted into your form when an address is returned. For each option in this section that you want to return, make sure you select the relevant field from your form that you want the address item to map to (note that if you don't want to return a particular field, you don't need to map to it) ![Dynamics Field Mappings](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-field-mappings.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=5c1d3875a99b435bcc51b1b68355e4bb) * When you have set your options, select **Done** * Select **Save and Publish** to update your form and publish the control. Depending on your form setup, this can take a little time. Once the form is published you will be able to perform address lookups using the new control. Here's an example of how that might look: ![Dynamics Using Address Finder](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/dynamics-365/dynamics-using-address-finder.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=bce5fe5bff66f9d5d1071239f46971cf) # Oracle Cloud Marketplace Integration Source: https://docs.loqate.com/integrations/oracle-cloud-marketplace Deploy Loqate Verify services in your own Oracle Cloud tenancy via the Oracle Cloud Marketplace. Process address validation at scale with full control of data residency. ### Works with: Oracle Cloud Infrastructure (OCI) ### Supported Loqate Services:
            [Integrate in 3 steps](#integrate-in-3-steps) ## About this listing Deploy Loqate Verify directly into your own Oracle Cloud Infrastructure (OCI) tenancy from the [Oracle Cloud Marketplace](https://marketplace.oracle.com/listings/gbg-loqate-address-validation/ocid1.mktpublisting.oc1.iad.amaaaaaajav7u2aar5tcojg5tcmgqn2igjpfkrr3r2yrxm7s2v2mtb2dvnka). The listing provisions everything needed to run the Loqate Verify API in OCI, giving you enterprise-grade address validation with full control over data residency, networking, and scale. Run the same Verify engine that powers Loqate's global address validation, but inside an Oracle region of your choice. Ideal for customers who need data to remain in-region, integrate with private OCI workloads, or operate Loqate behind their own VCN. ## Supported Loqate Service ### Address Verify Address Verify standardizes, corrects, and enriches address records against authoritative postal data for 245+ countries and territories. Running Verify on OCI means high-volume batch and real-time validation workloads stay inside your Oracle Cloud environment. **Key features:** * Batch and single-record verification * Standardization, correction, and enrichment in one call * Coverage for 245+ countries and territories * Detailed verification status and field-level reporting * Runs inside your OCI tenancy and region of choice [Learn more about Address Verify](/our-services/address-verify/overview) > [card] [Address Verify API reference](/api-reference/address-verify/international-batch-cleanse-oci) > > Endpoint, request, and response details for the Verify API. > [card] [Oracle Cloud Marketplace listing](https://marketplace.oracle.com/listings/gbg-loqate-address-validation/ocid1.mktpublisting.oc1.iad.amaaaaaajav7u2aar5tcojg5tcmgqn2igjpfkrr3r2yrxm7s2v2mtb2dvnka) > > View the GBG Loqate Address Validation listing on Oracle Cloud Marketplace. ## Integrate in 3 steps 1\) Get your API key 2) Subscribe on Oracle Cloud Marketplace 3) Deploy in your tenancy > [card] > > Get your API key, then deploy from the Oracle Cloud Marketplace > > Provision Loqate Verify into your OCI tenancy and start validating addresses in your own cloud environment. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Subscribe on Marketplace > > [Open](https://marketplace.oracle.com/listings/gbg-loqate-address-validation/ocid1.mktpublisting.oc1.iad.amaaaaaajav7u2aar5tcojg5tcmgqn2igjpfkrr3r2yrxm7s2v2mtb2dvnka) > > 3. Deploy in Your Tenancy > > [Open](https://marketplace.oracle.com/listings/gbg-loqate-address-validation/ocid1.mktpublisting.oc1.iad.amaaaaaajav7u2aar5tcojg5tcmgqn2igjpfkrr3r2yrxm7s2v2mtb2dvnka) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] What does the Oracle Cloud Marketplace listing deploy? > > The listing provisions the Loqate Verify service into your own Oracle Cloud Infrastructure tenancy. Once deployed, you can call the Verify API from any workload that has network access to the deployment, including services running inside your VCN. > [accordion] Why run Loqate on OCI instead of using the public Loqate cloud? > > Running Loqate inside your OCI tenancy gives you control over data residency, network isolation, and scaling. It's a good fit if you have OCI-hosted applications, regional compliance requirements, or workloads that must stay inside your private network. > [accordion] Do I still need a Loqate API key? > > Yes. You'll need a Loqate API key to authenticate against the deployed Verify service. You can create one from the [Loqate account portal](https://account.loqate.com/). > [accordion] Which Oracle Cloud regions are supported? > > The listing can be deployed into the OCI regions supported by Oracle Cloud Marketplace for this image. Check the listing page for the current region availability. > [accordion] How is billing handled? > > Loqate usage is billed under your Loqate plan. Underlying OCI compute, storage, and networking are billed through your Oracle Cloud account. See the [Loqate pricing page](https://www.loqate.com/pricing) for plan details. > [accordion] Where can I get support? > > For questions about the Loqate service, email \[[LoqateSupport@gbgplc.com](mailto:LoqateSupport@gbgplc.com)]\(mailto:[LoqateSupport@gbgplc.com](mailto:LoqateSupport@gbgplc.com)). For issues with the OCI deployment or marketplace listing, contact Oracle Cloud support. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Listing details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Publisher GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Oracle Cloud Infrastructure [View on Oracle Cloud Marketplace](https://marketplace.oracle.com/listings/gbg-loqate-address-validation/ocid1.mktpublisting.oc1.iad.amaaaaaajav7u2aar5tcojg5tcmgqn2igjpfkrr3r2yrxm7s2v2mtb2dvnka) # Oracle Integration Cloud Integration Guide Source: https://docs.loqate.com/integrations/oracle-integration-cloud-overview Install the GBG Loqate Reach and GBG Loqate Verify adapters from the Oracle Integration Store and configure a connection to verify addresses inside Oracle Integration flows. GBG Loqate publishes two adapters in the Oracle Integration Store. Both bring Loqate address verification into Oracle Integration as a native connector, so you can verify addresses inside an integration flow without writing custom REST calls, handling authentication, or parsing Loqate response codes yourself. This guide covers choosing an adapter, installing it, and configuring a connection. For mapping the action into a flow and working with the response, see the [Usage Guide](/integrations/oracle-integration-cloud-usage). ## Which adapter should you use? | | GBG Loqate Reach | GBG Loqate Verify | | - | - | - | | **What it returns** | Corrected address, standardised components, AVC, a confidence score, and an accept, review, or reject recommendation | Corrected address, standardised components, AVC, and the Address Quality Index | | **Decisioning** | Yes, driven by a verification policy you choose on the connection | No, you apply your own rules to the returned codes | | **Typical use** | Customer onboarding, KYC, checkout, anywhere the flow needs a decision to branch on | Data cleansing, migrations, enrichment, anywhere you already have your own quality rules | | **API key travels as** | An `Authorization: Bearer` header | A field inside the request body | | **Endpoint** | `https://reach-oci.location.gbg.com` | `https://oci.location.gbg.com/Cleansing/International/Batch/v1.2/json6.ws` | Both adapters expose the same action, **Verify address**, and accept the same input. The difference is what comes back. If you want Loqate to make a policy-aware judgement on the address, use Reach. If you want the verification result and nothing more, use Verify. You can install both adapters on the same instance. They are independent connectors with separate connections. ## Installing the adapter The adapters require **Oracle Integration 3** and do not appear on a Generation 2 instance. You need permission to install from the Integration Store and to create connections, normally the **ServiceDeveloper** role or higher. Each adapter calls a single allowlisted host, shown in the table above, so confirm your instance has outbound access to it. **1. Open the Integration Store** Sign in to Oracle Integration and open the **Integration Store**. **2. Find the adapter** Search for `Loqate`, then select **GBG Loqate Reach** or **GBG Loqate Verify**. Both are published by GB Group plc. **3. Install** Click **Get** and accept the Oracle Cloud Marketplace terms of use when prompted. **4. Confirm** When installation finishes, the adapter appears in your **Adapters** list and becomes selectable when you create a connection. > [!NOTE] > > If the adapter does not appear straight away, the Integration Store catalogue cache can take up to eight hours to refresh. An administrator can force a refresh rather than wait. > [!NOTE] > > If your instance already has a privately registered adapter using the same identifier (`1616497:loqate-reach` or `1616497:loqate-verify`), installation fails with **ICS-18541: An error occurred while installing RAB adapter**. Remove the private registration first, then install from the Store. The two cannot coexist, because they claim the same adapter identifier. ## Creating a connection: GBG Loqate Reach 1. In Oracle Integration, go to **Design** > **Connections** and click **Create**. 2. Choose the **GBG Loqate Reach** adapter. 3. Give the connection a name, set the role to **Invoke**, and click **Create**. 4. Complete the connection properties. | Field | Required | Default | Notes | | - | - | - | - | | Loqate MCP endpoint | Yes | `https://reach-oci.location.gbg.com` | Leave the default unless GBG has provided a regional or private endpoint for your account | | Verification policy | Yes | `standard` | Governs the accept, review, and reject thresholds. See [Verification policies](#verification-policies) below | 5. Under **Security**, choose **Loqate API key** and paste your key into the **Loqate API key** field. The adapter applies it as an `Authorization: Bearer` header on every call. 6. Click **Save**, then **Test**, then **Save** again once the test succeeds. ### Verification policies The policy sets how demanding Loqate is before it will recommend accepting an address. | Policy | Intended for | | - | - | | `strict` | KYC and regulated onboarding, where a wrong address carries compliance risk | | `shipping` | Delivery and fulfilment, where the address must be physically deliverable | | `standard` | General purpose use. This is the default | | `permissive` | Early funnel lead capture, where you would rather keep a usable record than reject it | Changing the policy changes only the recommendation, not the verification itself. The AVC and the corrected address are unaffected. These are the same policies used across GBG Reach; see [Policies](/ai-agents/reference/policies) for more detail. ## Creating a connection: GBG Loqate Verify 1. Go to **Design** > **Connections** and click **Create**. 2. Choose the **GBG Loqate Verify** adapter. 3. Give the connection a name, set the role to **Invoke**, and click **Create**. 4. Complete the connection properties. | Field | Required | Default | Notes | | - | - | - | - | | Loqate Verify endpoint | Yes | `https://oci.location.gbg.com/Cleansing/International/Batch/v1.2/json6.ws` | Leave the default unless GBG has provided a regional or private endpoint for your account | | Loqate API key | Yes | None | Stored as a password field and never displayed after saving | 5. Click **Save**, then **Test**, then **Save** again once the test succeeds. > [!NOTE] > > This connection shows **No HTTP authentication** under Security, and that is by design. The Loqate Verify json6 service takes the API key inside the request body rather than in an HTTP header, so the key is supplied through the **Loqate API key** connection property instead. See the [Verify API reference](/api-reference/address-verify/international-batch-cleanse-oci) for the underlying endpoint. The API reference writes the version as `v1.20` rather than the adapter's `v1.2`. Both paths reach the same service, so you can keep the adapter's default. ## Testing the connection Clicking **Test** performs a live call, so a success means your key, endpoint, and network path all work together. | Adapter | What the test does | Success means | | - | - | - | | GBG Loqate Reach | Requests the list of available verification policies | The endpoint returned a valid response and your key was accepted | | GBG Loqate Verify | Verifies a known United States address | The endpoint returned HTTP 200 with at least one result | If the test fails, work through these in order. | Message | Likely cause | What to do | | - | - | - | | Connection test failed, the endpoint did not return a valid Loqate MCP response | Wrong endpoint URL, or outbound traffic blocked | Confirm the endpoint matches the default, and that your instance can reach that host | | Connection test failed, the Loqate Verify endpoint did not return a valid response | Wrong endpoint URL or rejected API key | Check the endpoint path is complete, including `/Cleansing/International/Batch/v1.2/json6.ws` | | Unauthorized (401) | API key missing, mistyped, or not entitled to the service | Confirm the key value is correct and re-enter it | ## Usage attribution Both adapters add a `Source` parameter to every outbound call, identifying Oracle Integration as the calling application in your Loqate usage reporting. Connection tests are tagged separately from live verification calls, so testing a connection does not distort your usage figures. You do not need to configure anything for this, and the value cannot be edited from the connection. ## Next steps > [card] [Usage Guide](/integrations/oracle-integration-cloud-usage) > > Add the Verify address action to a flow, map the request, and work with the response. > [card] [Oracle Cloud Marketplace](/integrations/oracle-cloud-marketplace) > > Deploy Loqate Verify into your own Oracle Cloud Infrastructure tenancy. # Oracle Integration Cloud Usage Guide Source: https://docs.loqate.com/integrations/oracle-integration-cloud-usage Use the GBG Loqate Reach and GBG Loqate Verify adapters inside an Oracle Integration flow: add the Verify address action, map the request, and branch or handle errors on the response. This guide covers using the GBG Loqate Reach and GBG Loqate Verify adapters inside an Oracle Integration flow: adding the action, mapping data into it, and working with what comes back. If you have not installed an adapter and created a connection yet, start with the [Integration Guide](/integrations/oracle-integration-cloud-overview). ## Adding the Verify address action Both adapters expose a single action, **Verify address**, and both are invoke only. You call them from inside a flow. Neither adapter can start an integration. **1. Open an integration** Open or create an integration. Any style works, including app driven, scheduled, and event driven. **2. Add the connection** Drag your Loqate connection onto the flow at the point where you want the address verified. **3. Name the endpoint** Give the endpoint a name and click **Continue**. **4. Select the action** Select the **Verify address** action and click **Continue**, then **Finish**. **5. Map the request** Open the mapper for the new invoke and map your source fields onto the [request](#request). ## Request Both adapters accept the same two fields. | Field | Type | Required | Notes | | - | - | - | - | | `address` | String | Yes | The address to verify. A single line containing the whole address is acceptable, and is usually the easiest thing to map | | `country` | String | Yes | ISO 3166-1 alpha-2 country code, for example `GB`, `US`, `MY`. Map it on every call, see the warning below | > [!WARNING] > > Always map `country`. Neither adapter works it out from the address. Leave it unmapped and GBG Loqate Reach raises a **Verification service error (502)** fault, while GBG Loqate Verify returns a normal response with an empty verified address, no AVC and no match quality. The Verify case raises no fault, so it is easy to mistake for success. You do not need to split the address into components before calling. Loqate parses the input itself, so mapping a concatenated address line, or a single free text field captured from a form, works well. ```json theme={null} { "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043", "country": "US" } ``` ## Response: GBG Loqate Reach | Field | Type | Description | | - | - | - | | `verified_address` | String | The cleaned, standardised address as a single line | | `confidence` | Number | Confidence score from 0.0 to 1.0 | | `recommendation` | String | The policy-aware decision to branch on: `accept`, `review`, or `reject` | | `match_level` | String | How precisely the address matched. One of `premise`, `delivery_point`, `thoroughfare`, `locality`, `admin_area`, `country`, `none` | | `avc` | String | The full Loqate [Address Verification Code](#reading-the-avc) | | `fields` | Object | Standardised [address components](#address-components) | ```json theme={null} { "verified_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351", "confidence": 0.97, "recommendation": "accept", "match_level": "premise", "avc": "V44-I44-P7-100", "fields": { "address1": "1600 Amphitheatre Pkwy", "locality": "Mountain View", "administrative_area": "CA", "postal_code": "94043-1351", "premise": "1600", "thoroughfare": "Amphitheatre Pkwy", "country": "US", "country_name": "United States" } } ``` ## Response: GBG Loqate Verify | Field | Type | Description | | - | - | - | | `verified_address` | String | The cleaned, standardised address as a single line | | `avc` | String | The full Loqate [Address Verification Code](#reading-the-avc) | | `match_quality` | String | The Loqate [Address Quality Index](/report-codes/address-quality-index) | | `fields` | Object | Standardised [address components](#address-components) | Verify does not return `confidence`, `recommendation`, or `match_level`. If your flow needs a decision rather than raw codes, use the Reach adapter instead, or derive your own rules from the AVC. ## Address components Both adapters return the same `fields` object. Loqate fills in components that were missing from the input when the reference data supplies them, so expect fields you did not send. In the example above, the request had no `country_name` or ZIP+4, but the response has both. A component is returned empty only when it does not apply to that country or the reference data cannot supply it. | Field | Description | | - | - | | `address1` | First address line | | `address2` | Second address line | | `premise` | House or building number | | `thoroughfare` | Street name | | `locality` | City or town | | `sub_administrative_area` | County or sub region | | `administrative_area` | State or province | | `postal_code` | Postal or ZIP code | | `country` | ISO 3166-1 alpha-2 country code | | `country_name` | Full country name | Neither adapter returns geographic coordinates. If you need latitude and longitude, use the Loqate geocoding services directly. See [Address Verify](/our-services/address-verify/overview). ## Reading the AVC Every verification returns an Address Verification Code, which is far more informative than a simple pass or fail. The leading letter is the verification status. | Status | Meaning | | - | - | | `V` | Verified. A complete match against a single reference record | | `P` | Partially verified. A partial match against a single reference record | | `A` | Ambiguous. More than one close reference match was found | | `R` | Reverted. Could not be verified to the minimum acceptable level | | `U` | Unverified. Unable to verify | In `V44-I44-P7-100`: * `V` is the verification status (Verified). * `44` are the post-processed and pre-processed match levels, from `0` for none up to `5` for delivery point. `4` is premise. * `I44` is the parsing status, followed by the lexicon and context identification match levels. * `P7` is the postcode status. `P7` means the primary postal code was verified and the secondary postal code was added or changed. Here, Loqate verified `94043` and added the ZIP+4 suffix `1351`. * `100` is the matchscore, from 0 to 100, indicating how much the input had to change. `100` means no changes were needed. The full breakdown is in the [Address Verification Code reference](/report-codes/address-verification-code). ## Branching on the recommendation The most common pattern with the Reach adapter is a switch immediately after the invoke, routing on `recommendation`. | Recommendation | Suggested handling | | - | - | | `accept` | Write the verified address back to your system and continue | | `review` | Route to a manual review queue, or present the corrected address to the user for confirmation | | `reject` | Stop and ask for re-entry, or record the failure and continue depending on how critical the address is | Because the thresholds behind these values come from the policy set on the connection, you can make a flow stricter or more forgiving without touching the integration itself. If you need two different levels of strictness in the same instance, create two connections with different policies and use whichever the flow requires. > [!TIP] > > Write `verified_address` and the `fields` components back to the source record, rather than keeping the original input. That is what gives you the standardisation benefit. An address that verifies but is never written back leaves the poor quality data in place. ## Error handling Both adapters convert Loqate service conditions into faults that Oracle Integration can catch, so you can handle them in a scope with a fault handler rather than inspecting response codes yourself. ### GBG Loqate Reach | Fault | Raised when | | - | - | | Unauthorized (401) | The Loqate API key is missing or was rejected | | Invalid request (400) | The request to the verification service was malformed | | Verification service error (502) | The upstream Loqate service returned an unexpected error | ### GBG Loqate Verify | Fault | Raised when | | - | - | | Unauthorized (401) | The Loqate API key is missing or was rejected | | No match (404) | The address could not be verified against reference data | | Verification service error (502) | The Loqate Verify service returned an unexpected error | > [!WARNING] > > The two adapters treat an unverifiable address differently. Verify raises a **No match (404)** fault, so an address that cannot be verified is an exception your flow must catch. Reach returns a normal response carrying a `reject` recommendation, so the same address flows through as data rather than as a fault. Design your error handling accordingly: with Reach you branch, with Verify you catch. ## Throughput Each Verify address call verifies one address. To process many addresses in a single integration run, loop over your collection and call the action per record, keeping the usual Oracle Integration considerations in mind for large loops. For bulk cleansing of large datasets, calling the [Loqate batch API](/api-reference/address-verify/quickstart) directly is more efficient than looping inside an integration, since it verifies many addresses per request. ## Troubleshooting | Symptom | Likely cause | Resolution | | - | - | - | | Adapter missing from the Adapters list after installing | Catalogue cache not refreshed | Wait, or have an administrator force a catalogue refresh | | ICS-18541 during installation | A privately registered adapter already uses the same identifier | Remove the private registration, then install from the Store | | Connection test fails immediately | Endpoint unreachable from the instance, or endpoint URL edited | Restore the default endpoint and confirm outbound access to the host | | Unauthorized (401) at runtime, though the test passed | Key revoked, expired, or out of entitlement since the test | Confirm the key is still valid and has remaining entitlement | | Every address returns `reject` or a `U` status AVC | Wrong country code, so the address is matched against another country's reference data | Check the value being mapped into `country` | | Verification service error (502) on every GBG Loqate Reach call | `country` is not mapped | Map `country`. Reach rejects a request without it | | GBG Loqate Verify returns a blank address and no AVC, with no fault | `country` is not mapped | Map `country`. Without it the Verify service returns an empty match | | Components come back empty but the address verified | The country's reference data does not populate that component | Compare against the [AVC](/report-codes/address-verification-code) match level rather than assuming a fault | | No match (404) faults on addresses you expect to verify | New build, unusual format, or genuinely unverifiable input | Confirm with the same address through the Loqate API directly to isolate the adapter from the data | ## Support For questions about the adapters or the Loqate service, email [LoqateSupport@gbgplc.com](mailto:LoqateSupport@gbgplc.com). Both adapters are published by GB Group plc. # Reapit Integration Source: https://docs.loqate.com/integrations/reapit Add Loqate Email and Phone Validation to Reapit alongside Address Capture. Download the apps from Reapit AppMarket and add your API keys. ### Works with: Reapit (AgencyCloud) ### Supported Loqate Services:
              [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration Address Capture is available by default to all Loqate customers using Reapit. Email Validation and Phone Validation are available as optional add-on apps from the Reapit AppMarket. In the same way that Address Capture helps you collect accurate address data, Email and Phone Validation make sure the customer email and phone data you capture is accurate and up to date. You don't need any in-depth technical knowledge to install the apps, just familiarity with Reapit. ## Supported Loqate Services > [tab] Address Capture > > ### Address Capture > > Address Capture is available by default to all Loqate customers using Reapit, so there's nothing extra to install. > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Email Validation > > ### Email Validation > > The Email Validation app appears as an option in email widgets across Reapit, including applicant pages. > > **Why use it:** > > * Ensure your customer data is valid for marketing purposes and sending documentation > * Maintain valid data for customer engagement and communications > * Maximise the impact of checks such as Know Your Customer (KYC) and Anti-Money Laundering (AML) > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone Validation > > The Phone Validation app appears as an option in phone widgets across Reapit, including applicant pages. > > **Why use it:** > > * Ensure your customer data is valid for marketing purposes and sending documentation > * Maintain valid data for customer engagement and communications > * Maximise the impact of checks such as Know Your Customer (KYC) and Anti-Money Laundering (AML) > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/reapit-setup-guide) > > Create API keys, download the apps from Reapit AppMarket and configure them ## Integrate in 3 steps 1\) Create your API keys 2) Download the apps 3) Add your API keys to the apps > [card] > > Create your API keys, then download the apps from Reapit AppMarket > > Add a key to each app's configuration and Email and Phone Validation are ready to use. > > 1. Create Your API Keys > > [Open](https://account.loqate.com/) > > 2. Download the Apps > > [Open](/integrations/reapit-setup-guide#download-apps-from-reapit-appmarket) > > 3. Add Your API Keys > > [Open](/integrations/reapit-setup-guide#add-api-keys-to-app-configuration) ## Additional Resources [Video Tutorial](/integrations/reapit-setup-guide#setup-video) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Do I need to install anything for Address Capture? > > No. Address Capture is available by default to all Loqate customers using Reapit. Only Email Validation and Phone Validation need to be installed from the Reapit AppMarket. > [accordion] Do I need new API keys? > > We recommend creating a separate API key for each of Email Validation and Phone Validation, named so it's clear which key belongs to which service. See [Creating API Keys](/loqate-basics/create-an-api-key) for the steps. > [accordion] Can I use just one of Email Validation or Phone Validation? > > Yes. You can install and use either app on its own. > [accordion] Where do the apps appear in Reapit? > > Once downloaded, the apps appear as options within all phone and email widgets across Reapit, including applicant pages. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB ### Platform Reapit AppMarket # Reapit Setup Guide Source: https://docs.loqate.com/integrations/reapit-setup-guide Install Loqate Email and Phone Validation in Reapit. Create API keys, download the apps from Reapit AppMarket and add your keys. Address Capture is available by default to all Loqate customers using Reapit, however Email Validation and Phone Validation are also available as optional add-ons. In this guide we will take you through the simple steps to install and set up Email and Phone Validation in Reapit. You don't need any in-depth technical knowledge to install this app, just familiarity with Reapit. For an overview of the services and why to use them, see the [Reapit integration overview](/integrations/reapit). ## Setup Video [YouTube video player](https://www.youtube.com/embed/XDuMvowCmSA) ## Installation The installation steps are as follows, and we recommend working through the guide in this order: * [Create new API keys](#create-new-api-keys) * [Download apps](#download-apps-from-reapit-appmarket) * [Add API keys to the apps](#add-api-keys-to-app-configuration) ### Create new API keys As an existing user you will already have a Loqate API key for use with Address Capture. We recommend creating a new API key for each of Email and Phone Validation, to keep everything clear (assuming you want to use both services – you can use just one of them if you would prefer). Our [Creating API Keys page](/loqate-basics/create-an-api-key) takes you through the steps of creating new API keys – follow the instructions for creating generic keys, repeating the process for each service. Make sure you name each key to note which one is for Email Validation, and which is for Phone Validation. If you need to refer back to your API keys, you can find them on the [Your Services page](https://account.loqate.com/account/#/Dashboard/) of your Loqate account. ### Download apps from Reapit AppMarket Head over to the Reapit AppMarket and search for ‘Loqate’. Both the Email Validation and Phone Validation apps should appear as below: ![Reapit AppMarket](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/reapit/appmarket.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=466ed2dfa5f95fc3b36dcee36d257a68) Click into each app and download them. Once downloaded, they will appear as options within all phone and/or email widgets across Reapit, including applicant pages. ### Add API keys to app configuration The final step is to add a new API key to each app. You can open an app within Reapit using the phone or email widgets. Using Phone Validation as an example, click on the phone icon and then select the **App – Phone validation by Loqate** option. ![Reapit AppMarket](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/reapit/widget.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=c0e84df9cdb8b71ed395acd82c77e7b7) This will open the app in a pop-up window - click **Configuration** on the left-hand side tab, then enter the new API key from your Loqate account. Save and close the app, then repeat this step for the second app. We recommend logging out of Reapit and logging back in, to refresh the platform. With that done, Email Validation and Phone Validation will be available to use. # Salesforce Commerce Cloud Integration Source: https://docs.loqate.com/integrations/salesforce-commerce-cloud Add Address Capture, Email and Phone Validation to Salesforce Commerce Cloud with the Loqate cartridge. Reduce input time and improve data accuracy. ### Works with: Salesforce Commerce Cloud (B2C Commerce) ### Supported Loqate Services:
                [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate Salesforce Commerce Cloud cartridge lets you quickly add Loqate services to your Salesforce Commerce Cloud instance, providing type-ahead lookup for address fields and validation for both email addresses and phone numbers. With some or all of these services enabled, you can reduce the time spent inputting customer details and improve the accuracy of your database. ## Supported Loqate Services > [tab] Address Capture > > ### Type-Ahead Address Lookup > > Address Capture provides a type-ahead solution for address input, so customers can find and select their address in a few keystrokes. > > **Key Features:** > > * Added to any page that includes the Loqate module > * Mapped to your existing address fields with the in-page setup > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Email Validation > > ### Email Address Validation > > Email Validation ensures the accuracy of the email addresses your customers enter. > > **Key Features:** > > * Added to any page that includes the Loqate module > * Mapped to your existing email fields with the in-page setup > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone Number Validation > > Phone Validation ensures the accuracy of the phone numbers your customers enter. > > **Key Features:** > > * Added to any page that includes the Loqate module > * Mapped to your existing phone fields with the in-page setup > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/salesforce-commerce-cloud-setup-guide) > > Install the Loqate cartridge, import metadata and map your fields ## Integrate in 3 steps 1\) Get your API key 2) Download the cartridge 3) Install and configure > [card] > > Get your API key, then install the Loqate cartridge > > Upload the cartridge, import the metadata, and map Loqate services to your fields. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Download the Cartridge > > [Open](https://assets.loqate.com/sfccb2c-integration/latest/loqate_salesforce_commerce_cloud_b2c_latest.zip) > > 3. Install and Configure > > [Open](/integrations/salesforce-commerce-cloud-setup-guide#process) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Do I have to use all three services? > > No. You can use one, two or all three of Address Capture, Email Validation and Phone Validation, depending on your business needs. > [accordion] Where do I configure the cartridge? > > In Business Manager, under **Merchant Tools > Site Preferences > Custom Preferences > Loqate**. This is where you provide your Loqate account details and add any custom scripts you want to run. > [accordion] Which pages should include the Loqate module? > > Add the module to each page where you want Loqate functionality. We recommend adding it to the Header section of each page. > [accordion] How do I map Loqate services to my fields? > > Follow the [Tag Setup Guide](/our-services/tag-setup-guide). The module code you add to your site replaces the setup code that guide asks you to add, so you can go straight to launching the in-page setup. > [accordion] Should I create a new API key for Salesforce Commerce Cloud? > > We recommend it. The key used in the cartridge is your primary way of reporting on usage, so a dedicated key keeps your Commerce Cloud usage separate from other websites or applications. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Salesforce Commerce Cloud [Download the latest cartridge](https://assets.loqate.com/sfccb2c-integration/latest/loqate_salesforce_commerce_cloud_b2c_latest.zip) # Salesforce Commerce Cloud Setup Guide Source: https://docs.loqate.com/integrations/salesforce-commerce-cloud-setup-guide Install the Loqate cartridge in Salesforce Commerce Cloud, import metadata, configure settings and map Address Capture, Email and Phone Validation to your fields. The Loqate Salesforce Commerce Cloud cartridge allows you to quickly and easily add Loqate address verification services to your instance of Salesforce Commerce Cloud, providing type-ahead lookup functionality for address fields, and validation for both email addresses and phone numbers. With some or all of these services enabled, you can reduce the amount of time spent inputting customer details, and improve the accuracy of your database. For an overview of what the integration does, see the [Salesforce Commerce Cloud integration overview](/integrations/salesforce-commerce-cloud). ## Available services The Loqate cartridge gives you access to these Loqate services in your Salesforce Commerce Cloud instance: * **Address Capture**, which provides a type-ahead solution for address input * **Email Validation**, which ensures the accuracy of customer email addresses * **Phone Validation**, which ensures the accuracy of customer phone numbers You can use one or more of these services, depending on your business needs. ## Prerequisites Before installing the Loqate cartridge you will need: * A live Salesforce Commerce Cloud account * A live Loqate account * A Loqate API key\* \* Note that your API key is designed to be an open access key to your account - there are security controls within your Loqate account to ensure this is not abused. The key used in the app will be your primary mechanism of reporting for usage, so we recommend creating a new key rather than reusing one you may already have on a website or other application. ## Process The installation process is made up of the following steps: * Download and install the cartridge * Add the cartridge to your cartridge path * Import required metadata * Configure your settings * Add the module to your site * Map your fields ### Download and install the cartridge First, download the [latest version of the Loqate cartridge](https://assets.loqate.com/sfccb2c-integration/latest/loqate_salesforce_commerce_cloud_b2c_latest.zip). Once that's downloaded: * Inside the cartridge zip file you will find two directories - `cartridges` and `system-objects` * Upload the `cartridges` directory and its contents (everything within the `plugin_loqate` folder) to the `Cartridges` directory of your SFCC instance ![Upload to Cartridge directory](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-commerce-cloud/upload.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=621455c417f34820988d5c78a4ef39da) ### Add the cartridge to your cartridge path The next step is to update your site's cartridge path to include the new Loqate cartridge. * You can do this in the Business Manager under **Administration > Sites > Manage Sites > \[Your Site] > Settings > Cartridge Path** ![Add to cartridge path](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-commerce-cloud/add.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=bd61b6e084caf0c980a7d784b085e270) * Add `plugin_loqate` to your cartridge path (Note: the cartridge path is colon separated) ### Import required metadata Next, import the metadata file `LoqateMetadata.xml`, which is provided in the `system-objects` directory of the downloaded zip file. * You can do this in the Business Manager under **Administration > Site Development > Import & Export** * Upload the xml file via the **Import & Export Files** section ![Import required metadata](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-commerce-cloud/import.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=6c1fc5c2a0a6e59245bea0860d807e59) * Then import it via the **Meta data** section ### Configure your settings With everything imported and installed, the next step is to start configuring the cartridge. * Navigate to **Merchant Tools > Site Preferences > Custom Preferences > Loqate** * Here you will be able to provide your Loqate account, and add any custom scripts you want to execute ### Add the module to your site Now add the following code to each page on which you want to include Loqate functionality: ```JSON theme={null} ``` This will include the module and add the scripts (including any custom scripts defined in your settings) to the page. > [!NOTE] > > We recommend you add this to the Header section of each page. ### Map your fields You can now start to set up your Loqate services and map them to your existing fields. You can choose whether to use one, two, or all three of the available services (Address Capture, Email Validation, Phone Validation). To do this, follow the process as detailed in our [Tag Setup Guide](/our-services/tag-setup-guide) - note that the code you've already added into your site in the previous step supersedes the setup code that you'll be instructed to add in that guide. When you get to the step about copying and pasting a code snippet into your site, you can go straight to launching the in-page setup. # Salesforce CRM Integration Source: https://docs.loqate.com/integrations/salesforce-crm Add Address Capture, Email and Phone Validation to Salesforce CRM. Install from AppExchange and use Lightning components and Flows. ### Works with: Salesforce CRM (Lightning Experience) ### Supported Loqate Services:
                  [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate app, available from the [Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000HOiI0UAL), adds type-ahead address lookup and email and phone validation to your Salesforce CRM instance. With some or all of these services enabled, you can reduce the time spent inputting customer details and improve the accuracy of your database. Use Loqate on **record** pages with Lightning components, or during **actions** with Flows. ## Supported Loqate Services > [tab] Address Capture > > ### Address finder > > Address Capture, referred to in Salesforce as **Address finder**, provides type-ahead address search and populates your Salesforce address fields with the selected address. > > **Key Features:** > > * Add to record pages with the Lightning App Builder > * Add to screens in Flows (recommended for actions) > * Address mappings control which Loqate element populates each Salesforce field > * Custom patterns combine several address elements into a single field > * Legacy Visualforce component for overriding standard actions > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Email Validation > > ### Email validator > > Email Validation, referred to in Salesforce as **Email validator**, checks the accuracy of customer email addresses on your record pages. > > **Key Features:** > > * Add to record pages with the Lightning App Builder > * Ready to use as soon as your API key is added, with no mappings required > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone number validator > > Phone Validation, referred to in Salesforce as **Phone number validator**, checks the accuracy of customer phone numbers on your record pages. > > **Key Features:** > > * Add to record pages with the Lightning App Builder > * Ready to use as soon as your API key is added, with no mappings required > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/salesforce-crm-setup-guide) > > Install the Loqate app, assign permission sets and configure address mappings ## Integrate in 3 steps 1\) Get your API key 2) Install from AppExchange 3) Configure the app > [card] > > Get your API key, then install the Loqate app from AppExchange > > Assign permission sets, add your API key, and drop the Loqate components onto your pages and Flows. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Install from AppExchange > > [Open](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000HOiI0UAL) > > 3. Configure the App > > [Open](/integrations/salesforce-crm-setup-guide#process) ## Additional Resources [Video Tutorial](/integrations/salesforce-crm-setup-guide#setup-video) [Permission Sets](/integrations/salesforce-crm-setup-guide#permission-sets) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Where can I use Loqate in Salesforce? > > All three services can be used on record pages through Lightning components. Address Capture can also be used during actions through Flows (recommended) or legacy Visualforce components. > [accordion] Can I use Email and Phone Validation without Address Capture? > > Yes. The Email validator and Phone number validator are enabled as soon as you add your API key, so you can skip the address mapping step if you don't need the Address finder. > [accordion] Which permission sets do my users need? > > Assign **Loqate Administrator** to whoever configures the package. End users need a **Loqate User** set, plus **Loqate User (Apex Access)** if they're on an Apex-capable licence. See [Permission Sets](/integrations/salesforce-crm-setup-guide#permission-sets) for the full guidance. > [accordion] Does it work on public Experience Cloud sites? > > Yes, but Salesforce's guest user security model requires you to explicitly share the Loqate Settings record with your site's guest user. See [Public Experience Cloud sites](/integrations/salesforce-crm-setup-guide#public-experience-cloud-sites) for the steps. > [accordion] Why do accented characters display as �? > > Your page or data uses an encoding other than UTF-8. The Loqate app is not the cause. See [Accented Characters Display Incorrectly](/integrations/salesforce-crm-setup-guide#accented-characters-display-incorrectly) to check the encoding and fix it. > [accordion] Should I create a new API key for Salesforce? > > We recommend it. The key used in the app is your primary way of reporting on usage, so a dedicated key keeps your Salesforce usage separate from your website or other applications. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Salesforce CRM [View on Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000HOiI0UAL) # Salesforce CRM Setup Guide Source: https://docs.loqate.com/integrations/salesforce-crm-setup-guide Install the Loqate app from AppExchange, assign permission sets, and configure Address Capture, Email and Phone Validation in Salesforce CRM. > [card] [Download the Loqate app from the Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000HOiI0UAL) The Loqate app, available from the [Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000HOiI0UAL), allows you to quickly and easily add Loqate address verification services to your instance of Salesforce CRM, providing type-ahead lookup functionality for address fields, and validation for both email addresses and phone numbers. With some or all of these services enabled, you can reduce the amount of time spent inputting customer details, and improve the accuracy of your database. For an overview of what the integration does, see the [Salesforce CRM integration overview](/integrations/salesforce-crm). ## Setup Video [YouTube video player](https://www.youtube.com/embed/L7a6awSyJGo) ## Available services The Loqate app gives you access to these Loqate services in your Salesforce CRM instance: * [**Address Capture**](https://www.loqate.com/en-gb/address-capture), which provides a type-ahead solution for address input - referred to in Salesforce as **Address finder** * [**Email Validation**](https://www.loqate.com/en-gb/email-validation-software), which ensures the accuracy of customer email addresses - referred to in Salesforce as **Email validator** * [**Phone Validation**](https://www.loqate.com/en-gb/phone-validation), which ensures the accuracy of customer phone numbers - referred to in Salesforce as **Phone number validator** ## Use cases There are two ways of using Loqate services in your Salesforce instance: * On **record** pages, using Lightning components - all Loqate services * During **actions**, using Flows (recommended) or Visualforce components (legacy, and not recommended) - Address Capture only The [Process](#process) section below will take you through how to set up both methods, beginning with overall installation before moving onto setting up mappings for use on record pages, then setting up Flows. For details of Visualforce setup, see the separate [Legacy Visualforce elements](#legacy-visualforce-elements) section at the end of this article. ## Prerequisites Before installing the Loqate app you will need: * A live Salesforce CRM account * A live Loqate account * A Loqate API key\* \* **Note:** your API key is designed to be an open access key to your account - there are security controls within your Loqate account to ensure this is not abused. The key used in the app will be your primary mechanism of reporting for usage, so we recommend creating a new key rather than reusing one you may already have on a website or other application. ## Process There are a few quick steps to get the Loqate app up and running: * [Install the app](#installing-the-loqate-app) * [Assign permissions](#setting-permissions) * [Add your Loqate API key](#app-setup) * [Set up address mappings](#address-mappings) * [Add Loqate widgets to your object pages](#loqate-widgets) * [Optional: Address finder settings](#optional-address-finder-settings) * [Add address Capture to Flows](#add-address-capture-to-flows) If you only want to use the Email validator and Phone validator controls, you can skip the address mapping step. If you want to also use the Address finder control though, please follow all of the steps below. ### Installing the Loqate app We recommend installing the Loqate app directly from the Salesforce AppExchange - adding the app from here will ensure you're always installing the latest version. #### Setting permissions The Loqate app ships with one administrator permission set, three end-user permission sets, and an Apex-access set you stack on top of a user set. Assign **Loqate Administrator** to whoever configures the package, and a **Loqate User** set (plus **Loqate User (Apex Access)** for users on Apex-capable licences) to anyone who needs to capture addresses on a page, form, or flow. See [Permission Sets](#permission-sets) for a full description of each set, the licence-type rules, and guidance on which combination to pick for your org. Set the permissions as required for each of your users under Setup → Permission Sets, then move on to the next step. ![Permissions](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/permissions-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=7872b27b0a7746e3b4c28179d7d42411) #### App setup With the app installed and permission sets assigned, the next step is to add your Loqate API key to the app, which you can do in the **API Settings** section of the Loqate Settings page. ![App setup](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/app-setup.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=6679f7486096a61303b84db8b8fc4ad5) **Note:** accessing the Settings page requires the Loqate Administrator permission set. Select the Loqate app from the App Launcher, then copy and paste your API key into the **API Settings** section and click Save. With that done, the Email validator and Phone validator controls are both enabled and can be added to pages - if you only want to use those two controls, you can skip ahead to the Loqate widgets section. To add the Address finder control as well, follow the steps below for creating address mappings. #### Address mappings For each address type that you want to populate using the Address finder control, you need to create an address mapping. This may involve creating multiple mappings for a single object - for example, for the Contact object you might create one mapping for the 'Mailing' address and another for the 'Other' address. You can create address mappings in the Settings page of the Loqate app. * In the Mappings section, click **New Mapping** * Name your mapping (we recommend using a distinct and memorable name, to distinguish it from other address types - for example, "Contact Mailing") * From the 'Select an object' drop-down, choose the object that you want to create a mapping for ![Address mapping](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/address-mapping-2.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=e63aaddde2ead95089bffa78af2d90f0) * Click the **+ Add Field** button, then from the 'Select a field' drop-down choose a field that you want to populate with address data * From the 'Select a element' drop-down, choose a Loqate element to map to your chosen field ![Address mapping](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/address-mapping-4.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=3ebc824ef5b54c1e0a72c31cb2b44d05) * Click the **Add Field Mapping** button to save and add your new mapping to the list ![Mappings list](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/mappings-list.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=49a4a2daab3224d6e57b66b85a63b9ad) You can create as many mappings as you need by just repeating these steps. #### Custom mappings If required, you can also use custom address mappings. * When selecting an element to map to a field, choose the **custom format** option from the drop-down list * In the 'Custom pattern' field that appears, enter your custom field mapping * For example, entering ", " will concatenate line1 and line2, separated by a comma and a space (assuming line2 is available - if not, only line1 will be included) ![Custom mapping](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/custom-mapping.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=b8ffb0fa9902da6670dad75c05d06af5) * See the Formatting section of our [Advanced Setup Guide](/our-services/address-capture/sdk) for more information about custom field values ### Loqate widgets In order to start using Loqate functionality, you need to add each control (i.e. Address finder, Email validator and Phone validator, where appropriate) to your object pages. * From the Details tab on the Contacts page, select **Settings** and then **Edit Page** ![Widgets](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/widgets-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=55b0d5b408bafe91ef917d301c33f053) * In the Lightning App Builder, look for the Loqate controls in the Custom section of the Components menu. You should see `loqateAddressCapture`, `loqateEmailVerification` and `loqatePhoneVerification`: ![Widgets](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/widgets-2.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=9a28c4ca3f95a3b4d9cd4b7ed3803c51) * You can drag each of these onto your page, placing them where you want them. Here's an example showing all three components added to the right-hand side of the page: ![Widgets](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/widgets-3.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=9dab8932520e96f64b9d04a7ba8fa2db) * Once you've placed all of the components, Save and Activate the page to be able to start using them * Repeat this process for all pages that you want to add the Loqate features to ### Optional: Address finder settings The Address finder control includes some additional settings which you can amend if required. To see these settings, select an Address finder control where it's been added to one of your pages. ![Settings](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/settings-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=be3fd743a7f161eee24aed0749835f48) You'll need to amend the settings for each instance of the control. #### Field mappings By default, the Address finder control will display a select box listing all of the mappings you've created for the object on which the control has been placed. You can then select the relevant mapping you want to use. Optionally though, you can lock the Address finder control to a particular mapping by entering a specific mapping name in the **Field Mappings** box. The control will no longer display the 'Select a mapping' box, and will instead always use the mapping you've chosen. #### Address title prefix If you have multiple Address finder controls on a single page (for example if you've locked one or more of them to particular mappings), it's useful to give each one a specific name to clearly differentiate them. You can use this setting to add additional text to the start of each control's title. Whatever text you enter in the **Address Title Prefix** box will be added at the start of its title - so for example if you have both 'mailing' and 'other' address fields on a page, add "Mailing" into this box for one of the controls so that it will display as "Mailing Address finder". ### Add Address Capture to Flows Follow these steps to add Address Capture to a Flow: * Open the Flow editor for the Flow you want to add Address Capture to. For this example we’ll use **Create a case** ![Flows](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/flows-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=2deb2eded41f548c6c7bfbc229c16b14) * From here, choose a screen to add the Loqate control to, and open the screen editor. In this example we'll use the **Confirm Customer Info** screen ![Flows](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/flows-2.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=35433a7462edd8a32e59cd297947974f) * The Loqate Address Capture component will be listed under **Custom**, so scroll down to that and drag the component onto your view ![Flows](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/flows-3.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=55ea2074ce2ba06f6f45833d7350ae98) * Make sure you add a name into the **API Name** field * You shouldn't need to fill in any of the other fields, as they're in place to allow for the Flows data model * Click **Done**, then run or debug the Flow to view the control and output ![Flows](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/flows-4.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=a194de5a17be2ad2007b917f90b17c11) * From here you can see that the **Search for an address** field is present * Having searched for and found an address, click **Next** to move to the next screen - in this case the **Confirm Customer Details** screen ![Flows](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/flows-5.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=3bf64522340b06c827f24315e5c8a943) * Here you can see the returned address data, which you can then use in the rest of the Flow #### Handling Custom Field Types in Flows When using the Loqate Flow action to return custom fields, the output values are returned as **Text**. This is fine for most scenarios, but can cause issues when mapping onto Salesforce standard fields that expect other data types (for example, `MailingLatitude` and `MailingLongitude`, which are **Number** fields). If you attempt to map a Text resource directly to a Number field in a **Create or Update Records** element, Flow will block the mapping. **Solution: Use a Number Formula Resource** You can convert the returned Text into a Number inside your Flow before mapping. **Steps:** 1. In Flow Builder, open the **Manager** panel and click **New Resource**. 2. Select **Resource Type**: `Formula`. 3. Give it an **API Name** (e.g. `latNumber`). 4. Set **Data Type**: `Number`. 5. Set **Decimal Places**: `6` (or another precision suitable for coordinates). 6. Enter the following formula, referencing the Text output from the Loqate action (e.g. `selectedAddressField1`): ```bash theme={null} IF( ISBLANK({!ADDRESS_FINDER.selectedAddressField1}), NULL, IF( ISNUMBER({!ADDRESS_FINDER.selectedAddressField1}), VALUE({!ADDRESS_FINDER.selectedAddressField1}), NULL ) ) ``` * `VALUE()` casts the text into a number. * Blank or invalid inputs return NULL so the Flow won't fault. 7. Save the resource. 8. In your **Create/Update Records** element, set the record field (e.g. `MailingLatitude`) to this formula resource. Repeat the same steps for Longitude if required. **Example** * **Loqate selectedAddressField1** → `"52.123456"` (Text) * **Formula (latNumber)** → `52.123456` (Number) * **Mapped to Contact.MailingLatitude** → works successfully. ## Permission Sets The Loqate for Salesforce managed package ships with **five permission sets**. After installing the package you assign these to your users to grant access to the address-capture components and the configuration screens. There is **one administrator permission set** for configuring the package, **three user permission sets** that grant the read-only object/field access end users need, and **one Apex-access permission set** that you stack on top of one of the user sets for any user who is on a licence type that supports Apex class access on permission sets. The reason for the split: Salesforce auto-restricts which user licences a permission set can be assigned to as soon as the set declares Apex class access. Keeping the user sets free of class access lets them remain truly licence-agnostic, and the Apex Access set carries the licence restriction so it only narrows assignment for users who need it. You can find all of these in **Setup → Permission Sets** after the package is installed. *** ### Loqate Administrator **Purpose:** the configuration role. Assign this to anyone who needs to enter the Loqate API key, define how Loqate address fields map onto your Salesforce objects, or otherwise maintain the integration. **What it grants:** * Full read, create, edit, and delete access to all of the Loqate configuration objects (settings and field mappings). * Edit access to the API key field and to the mapping fields that define which Loqate address element populates which Salesforce field. * Apex class access to all of the controllers backing the configuration UI. * Visibility of the **Loqate Address Verification** app in the App Launcher. * Visibility of the **Loqate Settings** tab. **Who should get it:** Salesforce administrators or whoever owns the Loqate integration in your org. End users should **not** be assigned this set — it would let them rotate the API key or change field mappings, which would break address capture for everyone else. **Stacking:** none required. The administrator set is self-sufficient and only assignable to internal Salesforce-licensed users in any case. *** ### Loqate User (All User Types) **Purpose:** the standard end-user permission set. Assign this to anyone who needs to use Loqate address capture on a Salesforce form, page, or flow. It is licence-agnostic, so it can be assigned to internal Salesforce users, Experience Cloud (Community / Partner) users, Platform users, and any other user licence type. **What it grants:** * Read-only access to the Loqate configuration objects so the address-capture component can resolve which fields to populate. * “View All” on the configuration records, meaning users will always see the mappings regardless of record-ownership or sharing rules. * The Loqate Address Verification app and the Loqate Settings tab are **hidden** — end users do not see the configuration UI. **What it does *not* grant:** access to the Apex controllers the address-capture components call at runtime. For users on licences that support Apex class access, also assign **Loqate User (Apex Access)** (see below). Without that, users will see the error `You do not have access to the Apex class named 'LoqateAddressMappingController'` the moment the component loads, **unless** the package was installed *for all users* — in which case the install-time profile grant covers class access and the Apex Access set is not strictly required (assigning it anyway is harmless and recommended for clarity). **When to choose it:** this is the default end-user object/field choice for most orgs. Pick this set if your org doesn’t have a specific policy against “View All” on custom configuration objects. *** ### Loqate User (Restricted View All) **Purpose:** the same end-user role as **Loqate User (All User Types)**, but **without “View All”** on the configuration objects. Users can only see mapping and settings records that your org’s sharing rules already grant them access to. **What it grants:** * Read-only access to the Loqate configuration objects (same as the standard end-user set). * **No** “View All” — record visibility is governed by your org’s sharing model. * App and tab hidden. **What it does *not* grant:** Apex class access. Same caveat as above — stack **Loqate User (Apex Access)** on top for users on licences that support Apex class access. **When to choose it:** assign this instead of the standard end-user set when: * Your org’s security policy forbids granting “View All” on custom configuration objects. * You are preparing for or maintaining a security review (e.g. AppExchange/internal audit) that flags blanket view-all permissions. * You want to intentionally scope which users can see which mapping records. If you choose this option, make sure your sharing rules / record ownership are configured so that the relevant mapping and settings records are visible to the users who need them. If a user can’t see the mapping records, the address-capture component won’t know how to populate fields and the integration will not work for them. *** ### Loqate User (Apex Access) **Purpose:** grants the Apex class access required by the user-facing address-capture components (`AppSettingsController`, `LoqateAddressMappingController`). Designed to be **stacked on top of** one of the User sets above. **What it grants:** * Apex class access to the two controllers the end-user LWCs call at runtime. **What it does *not* grant:** any object, field, tab, or app visibility. It must be combined with **Loqate User (All User Types)** or **Loqate User (Restricted View All)** to be useful. **Why it is a separate set:** Salesforce automatically restricts which user licences can be assigned a permission set that declares Apex class access. Bundling that restriction into the main user sets would break their licence-agnostic promise and would silently fail to assign for users on licences such as **Chatter Free**, **Chatter External**, **Identity Only** and certain legacy portal licences. By keeping the class access in its own set, the user sets remain assignable to anyone, and the Apex Access set only narrows assignment for users who actually need the class access. **When to assign it:** * Always, for any end user on a licence that supports Apex class access on permission sets — internal Salesforce users, Salesforce Platform users, Customer Community / Customer Community Plus / Partner Community / External Apps users, and similar. * **Skip it** for users on licence types that do not support Apex class access on permission sets (Chatter Free, Chatter External, Identity Only, certain legacy portal licences). Those users cannot use the Loqate components anyway — the underlying licence does not allow them to call Apex from an LWC — but the User set on its own can still be assigned to them without error. **Strictly optional case:** if the package was installed using the *Install for All Users* option, the install-time profile grant already covers Apex class access for internal user profiles. You can technically skip the Apex Access set for those users, though assigning it anyway is harmless and removes the dependency on the install-time grant (which can be lost if a profile is later cloned or modified). *** ### Loqate User (Salesforce Users Only) — *deprecated* **Purpose:** the original end-user permission set, retained for backwards compatibility with installations that were configured before the licence-agnostic variants were introduced. **Why it’s deprecated:** this set is restricted to **Salesforce-licensed users only**. That excludes Experience Cloud, Platform, and other licence types that many customers need to grant address-capture access to. **What you should do:** * **New installations:** do not assign this set. Use **Loqate User (All User Types)** or **Loqate User (Restricted View All)** instead, plus **Loqate User (Apex Access)** for Apex-capable users. * **Existing installations:** continue to work. When convenient, migrate existing assignments to one of the supported sets above. *** ### Quick decision guide | Need | Assign | | - | - | | Configure the package, enter the API key, edit field mappings | **Loqate Administrator** | | Standard end user on an Apex-capable licence (internal Salesforce, Platform, Community, Partner, External Apps, …) | **Loqate User (All User Types)** + **Loqate User (Apex Access)** | | End user as above, but your org’s security policy disallows “View All” on configuration objects | **Loqate User (Restricted View All)** + **Loqate User (Apex Access)** | | User on a licence that does not support Apex class access on permission sets (Chatter Free, Identity Only, …) | **Loqate User (All User Types)** only — note: address capture will not function for these users; the licence itself blocks Apex from running on their behalf | | Existing assignment from an older installation using the deprecated set | *Loqate User (Salesforce Users Only)* — migrate to the supported sets above | *** ### How to assign a permission set 1. In Salesforce, go to **Setup → Users → Users**. 2. Open the user record you want to grant access to. 3. Under **Permission Set Assignments**, click **Edit Assignments**. 4. Move the relevant Loqate permission set(s) from **Available** to **Enabled**. For end users on Apex-capable licences this means selecting **two** sets — one User set (All User Types or Restricted View All) and **Loqate User (Apex Access)**. 5. Click **Save**. The user will gain access at next login (or immediately, depending on session state). *** ### Troubleshooting **“You do not have access to the Apex class named ‘LoqateAddressMappingController’”** — the user has one of the User sets assigned but not **Loqate User (Apex Access)**, and the package was not installed *for all users* (or the profile-level grant has been lost). Assign **Loqate User (Apex Access)** in addition to the User set. **“Can’t assign permission set Loqate User (Apex Access) to user X. The user license doesn’t allow Apex Class Access”** — the user is on a licence type that does not permit Apex class access on permission sets (Chatter Free, Chatter External, Identity Only, certain legacy portal licences). Assign **Loqate User (All User Types)** alone. Address capture will not work for the user, but this is a constraint of their Salesforce licence, not of the Loqate package — no permission-set configuration can grant Apex access to a licence that does not support it. ## Public Experience Cloud sites If your public **Experience Cloud site** (formerly Community) is unable to perform address searches using the Loqate components, the issue may be caused by Salesforce’s **Secure Guest User Record Access** model. Even when the **Loqate Settings** record has external organization-wide defaults (OWD) set to **Public Read Only**, Salesforce enforces an additional restriction for guest users—effectively treating all objects as **Private**.\ This means you must **explicitly share** the Loqate Settings record with your site’s guest user. ### Configure guest access to Loqate Settings Follow these steps to create a sharing rule that grants your guest user read access to the Loqate Settings record: 1. In **Setup**, navigate to\ **Sharing Settings → Loqate Settings Sharing Rules**. 2. Click **New**. 3. Enter a **Label** and **Rule Name** of your choice. 4. Select **Guest user access, based on criteria** as the **Rule Type**. 5. Under **Criteria**, set: * **Field:** `ApiKey` * **Operator:** `not equal to` * **Value:** *(leave blank)* 6. In the **Share with** dropdown, select your **site’s guest user**. 7. Set the **Access Level** to **Read Only**. 8. Click **Save**. Once the sharing rule has been created and processed, guest users should be able to access the Loqate Settings record, and address searches will begin to function correctly again. ## Accented Characters Display Incorrectly If accented characters in the country list show as "�", for example "R�union" instead of "Réunion (RE, +262)", your page is using an encoding other than UTF-8. The Loqate app is not the cause. Loqate's script is served as `Content-Type: text/javascript;charset=UTF-8`, so you fix this in your own page, files or data. ### Check the Encoding On the affected page, open your browser's developer console and run: ```javascript theme={null} console.log(document.characterSet); // page encoding, e.g. "UTF-8" [...document.querySelectorAll('option')] .filter(o => /union/i.test(o.text)) .map(o => [o.text, [...o.text].map(c => c.charCodeAt(0).toString(16))]) ``` Find the code for the accented character in the result: | Code | What it means | | - | - | | `fffd` | The page is reading Latin-1 data as UTF-8. | | `c3 a9` (shows as "é") | The reverse: a Latin-1 page is showing UTF-8 data. | | `e9` | The text is correct in the page. The problem is elsewhere, such as the font or how the text is displayed. | ### Fix the Encoding 1. Make sure your page is served as UTF-8. In the browser console, `document.characterSet` returns `"UTF-8"`. In the **Network** tab, the page response header shows `Content-Type: text/html; charset=UTF-8`. 2. Re-save as UTF-8 any files or data stored in another encoding, such as Latin-1. Once the page is UTF-8, anything still stored as Latin-1 shows "�". 3. Reload the page and run the check again. The accented character returns `e9`. ## In use With the Loqate app installed and configured, you can start using the Address finder, Email validator and Phone number validator controls when inputting addresses, email addresses and phone numbers into Salesforce. For example, here's how the Address finder control looks during an address search: ![In use](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/in-use-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=34d33d393fb65be140fd8c1b6fdae007) ## Legacy Visualforce elements In some cases you may want to use a more legacy approach to including Address Capture in your Salesforce instance, for example by overriding the **New** button action on a record listing page. In the following examples we’ll use the standard **Contact** record type to demonstrate the use of the included legacy Visualforce component. The Loqate app ships with a Visualforce page that can be used to replace the **New** button action via Object Manager, and is a reference build for the outcome of this example. ### Building the page In this example we will be creating a new page to replace the standard Contact Create page and allow for Address Capture to be used in that process. Please note that this is a legacy approach, and we would recommend you use Flow views for this kind of action. ![Building the page](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/visualforce-1.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=474fdcb2af033f2c28c65701ce53cf9f) Each of the address controls in the above screenshot are an example of the `legacyLoqateAddressCapture` Visualforce component. The full Visualforce page looks like this: ```apex theme={null} ``` As you can see the controls are included like this: ```apex theme={null} ``` You may need one, or as in this case multiple instances of the control for your page. The attributes for this component are as follows: | Attribute name | Description | Example | | :- | :- | :- | | label | This is the label for the control, and will appear alongside the control input box on pages. | Mailing Address | | namespace | Optional. This attribute is important when you have multiple controls on a single page, as this allows the controls to operate independently of each other. It must be unique across rendered controls. | mailing | | onAddressSelectedFunction | This should be set to the name of the callback function that selected addresses will be returned to. | handleMailingAddressSelected | | Mapping | Optional. If a mapping group name is provided, the second argument passed to the callback function will be an object whose keys and values are those of the mapped fields. | Contact Mailing | Let's look in more detail at some of the aspects of the callback function and how the data gets into a record. The page itself (as well as using Lightning stylesheets to give a Lightning look and feel) uses the standard Contact controller: ```apex theme={null} ``` This allows it to act as a creation form for the standard Contact object. This in turn means that you can set values against the Contact records properties within the page. For the first and last name fields, this is achieved by binding the field to the FirstName and LastName fields of the controller: ```apex theme={null} ``` However, for the address lookups controls this is a little more involved. You can’t map directly from JS to the values, so instead you expose the properties you want to set via a selection of hidden inputs: ```apex theme={null} ``` You can then declare a callback function for each of the address lookups on the page. These will take the address output of the lookup, and push it into the record fields defined above: ```apex theme={null} ``` Finally, you can add a command button that will call the Save function on the standard controller: ```apex theme={null} ``` The response to this button press off a standard controller is to redirect to the record, so that flow is taken care of. ### Using the page in place of the standard New view With a Visualforce page in place that uses the Address Capture components, you now need to override the default behaviour of the New button on the contact listing page. This is achieved through the Object Manager, so navigate to Setup and search for Object Manager. Once there, select **Contact** from the list. ![Object manager](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/visualforce-2.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=8cd5a247e049801919f8e057fe656cf2) Next select **Button, Links and Actions** from the left-hand menu, then edit the **New** action – you should be able to select the new page from the **Visualforce** page dropdown field: ![New action](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/salesforce-crm/visualforce-3.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=59c29f9c1e6fb50d7a9471600978136d) Click **Save**, and from now on the New action on the contact listing page will open your new page, and you can create contacts with verified addresses. # Shopify Plus Integration Source: https://docs.loqate.com/integrations/shopify-plus Native Shopify integration with Address Capture, Address Verify, and Email Validation. Subscribe through your Shopify store and improve checkout data quality. ### Works with: All Shopify plans (checkout features on Shopify Plus) ### Supported Loqate Services:
                    [Integrate in 3 steps](#integrate-in-3-steps) ## About this app Add enterprise-grade address validation to your Shopify store with type-ahead address lookup, post-checkout verification, and email validation. Built on Shopify's Checkout Extensibility framework, the Loqate integration reduces delivery failures and improves data quality without requiring technical knowledge. If you found Loqate in the Shopify App Store, you buy it through your Shopify store's billing. Choose a monthly plan in the app, approve the charge on Shopify's billing screen, and Loqate sets up your account for you. Every plan includes all three services, and the plan you pick sets your monthly usage cap. If you are an existing Loqate customer, use the API key from your Loqate account instead and your billing stays with Loqate. > [!NOTE] > > The app installs on any Shopify plan, but your Shopify plan decides where Loqate can appear. Shopify reserves the checkout steps, such as the address and email fields, for Shopify Plus stores. Post-checkout features on the order confirmation page work on Basic, Grow, Advanced and Plus. See [what works on your Shopify plan](/integrations/shopify-plus-integration-in-practice#what-works-on-your-shopify-plan). ## Completely Modular Validation Suite > [tab] Address Capture > > ### Type-Ahead Address Lookup > > Active by default once configured, Address Capture adds intelligent type-ahead functionality to both delivery and billing address fields. Customers start typing their address and select from a list of verified suggestions, dramatically reducing input time and errors. > > **Key Features:** > > * Works in both delivery and billing address sections > > * Respects your Shopify shipping country settings > > * Reduces checkout time by up to 60% > > * Supports 245+ countries and territories > > * Suggestions in the checkout need a Shopify Plus store > > > [!NOTE] > > > > The countries in your **Country/Region** dropdown are controlled by your Shopify store's shipping settings. Only countries you ship to will appear in the list. > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Address Verify > > ### Post-Checkout Address Verification > > Address Verify adds an intelligent verification layer on the order confirmation (Thank You) page, checking delivery addresses through correction, standardization, and enhancement processes. If improvements are found, customers can approve or decline the suggested changes. > > **Key Features:** > > * Runs post-checkout on the order confirmation page (recommended), or during checkout on Shopify Plus > > * Post-checkout verification works on Basic, Grow, Advanced and Plus stores > > * Compatible with wallets (Apple Pay, Google Pay) > > * Works with logged-in customer addresses > > * Updates delivery address in your Shopify orders automatically > > * Customers can also correct the address from their Shopify customer account > > * Three possible outcomes: verified, alternative found, or not validated > > > [!WARNING] > > > > Verifying during the checkout uses a Verify transaction for every address that reaches the verification step, including abandoned checkouts, and does not run for express payments. The post-checkout option uses fewer transactions because it only runs on orders you took. > > [Learn more about Address Verify](/our-services/address-verify/overview) > [tab] Email Validation > > ### Real-Time Email Address Verification > > Email Validation ensures customers enter valid email addresses before completing checkout. Invalid addresses trigger an inline notification, preventing customers from proceeding until a valid email is provided. Valid entries pass through seamlessly without interruption. > > **Key Features:** > > * Real-time validation as customers type > * Inline error messaging for invalid addresses > * No visual impact for valid addresses > * Reduces bounce rates and improves deliverability > * Catches common typos and formatting errors > * Needs a Shopify Plus store, because it runs in the checkout email field > > Invalid email addresses may include non-existent domains, syntax errors, disposable addresses, or known invalid patterns. See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [card] [Integration in practice](/integrations/shopify-plus-integration-in-practice) > > What the app does, what works on your Shopify plan, how subscriptions work, and how it looks in practice > [card] [Setup guide](/integrations/shopify-plus-setup-guide) > > Set up the app, configure each service, and manage your settings and subscription ## Integrate in 3 steps 1\) Install Shopify App 2) Choose a plan or connect your API key 3) Configure Services > [card] > > Install Shopify App and then Choose Your Plan > > Install the Loqate Shopify app, subscribe through your Shopify store's billing, and start validating addresses in minutes. Already a Loqate customer? [Connect the API key from your Loqate account](/integrations/shopify-plus-setup-guide#connect-an-existing-loqate-account) instead. > > 1. Install Shopify App > > [Open](https://apps.shopify.com/loqate) > > 2. Choose Your Plan > > [Open](/integrations/shopify-plus-setup-guide#set-up-loqate-as-a-new-customer) > > 3. Configure Services > > [Open](/integrations/shopify-plus-setup-guide#enabling-loqate-services) ## Additional Resources [Video Tutorial](/integrations/shopify-plus-setup-guide#setup-video) [What works on your Shopify plan](/integrations/shopify-plus-integration-in-practice#what-works-on-your-shopify-plan) [Custom field mappings](/integrations/shopify-plus-custom-field-mappings) ## Pricing > [card] [Subscribe through Shopify](/integrations/shopify-plus-integration-in-practice#subscriptions-and-usage-caps) > > For merchants coming from the Shopify App Store. Monthly plans billed through your Shopify store: each plan's price is its monthly usage cap, every plan includes all three services, and you can change your cap at any time. > [card] [Existing Loqate customer?](/integrations/shopify-plus-setup-guide#connect-an-existing-loqate-account) > > Use an API key from your Loqate account and your billing stays with Loqate. > [card] [View Loqate Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans for Loqate accounts, starting with a 45-day free trial. ## Frequently Asked Questions > [accordion] How quickly can I install and set up the Loqate app in my Shopify store? > > Installation takes less than 5 minutes through the Shopify App Store. You don't need any technical knowledge—just install the app, choose a plan and approve the charge in Shopify (or, if you're an existing Loqate customer, enter the API key from your Loqate account), and configure which services to enable. Account activation after approving a plan usually takes a few minutes. Address Capture activates automatically on both delivery and billing address fields. See the [integration guide](/integrations/shopify-plus-setup-guide) for each step. > [accordion] Do I need a Shopify Plus store? > > No. The app installs on any Shopify plan, but Shopify reserves the checkout steps for Shopify Plus stores. On Basic, Grow and Advanced you can use post-checkout Address Verify, address capture after the order is placed, and address correction from a customer account. Address Capture suggestions and Email Validation in the checkout need Shopify Plus. Shopify Starter stores can install the app, but none of the checkout or order confirmation page features run on them. See [what works on your Shopify plan](/integrations/shopify-plus-integration-in-practice#what-works-on-your-shopify-plan). > [accordion] How does billing through Shopify work? > > Shopify billing is for merchants who come to Loqate through the Shopify App Store. You take out a monthly subscription in the app and approve the charge on Shopify's billing screen. Each plan's price is also its monthly usage cap, issued to you automatically in small credit packs as your store uses Loqate, so you pay for what you use up to your cap. Your subscription renews each month on the date of your first payment, and your cap resets at the start of each cycle. See [subscriptions and usage caps](/integrations/shopify-plus-integration-in-practice#subscriptions-and-usage-caps). > [accordion] I already have a Loqate account. Can I use it? > > Yes. Existing Loqate customers create an API key in their Loqate account at [account.loqate.com](https://account.loqate.com/), then select **I already use Loqate** on the welcome screen and enter that key. You won't take out a Shopify subscription, and your billing and usage allowance stay with your Loqate account. See [connect an existing Loqate account](/integrations/shopify-plus-setup-guide#connect-an-existing-loqate-account). > [accordion] Can I change my usage cap or cancel my subscription? > > Yes. Select **Change cap** on the Loqate settings screen to move to a different plan. A higher cap is available straight away, and a lower cap can wait until your next billing cycle. If no plan is large enough, select **Need a higher cap?** to ask for a custom plan. To cancel, go to the Shopify admin where you manage your other app charges; your subscription stays active until the end of the period you have paid for. See [change your usage cap](/integrations/shopify-plus-setup-guide#change-your-usage-cap) and [cancel and restart your subscription](/integrations/shopify-plus-setup-guide#cancel-and-restart-your-subscription). > [accordion] Can I use each validation service independently? > > Yes, all three services (Address Capture, Address Verify, and Email Validation) are included in every plan and can be used independently. Address Capture is enabled by default, and you switch Address Verify and Email Validation on in the app's settings, so you have complete control over which services to use based on your business needs. > [accordion] Will Address Verify work with Apple Pay, Google Pay, and logged-in customers? > > Yes, with the recommended post-checkout option. Address Verify then runs on the order confirmation (Thank You) page, making it fully compatible with wallet payments (Apple Pay, Google Pay) and addresses from logged-in customer accounts. Verifying during the checkout cannot run for express payments such as Apple Pay, Google Pay, Shop Pay and PayPal, which is why we recommend the post-checkout approach. > [accordion] Does it work with international customers and all Shopify markets? > > Yes, we support 245+ countries and territories worldwide. The app automatically respects your Shopify store's shipping country settings, so only the countries you ship to will appear in the country dropdown. Address suggestions and validation adapt to each country's specific address format. [Custom field mappings](/integrations/shopify-plus-custom-field-mappings) can be used to overwrite the defaults. > [accordion] What happens if Address Verify can't validate an address? > > If an address is too low quality to validate, customers see a notification that "Your shipping address could not be validated," but their order still processes normally. This ensures you never lose a sale due to validation issues while still improving overall address quality. > [accordion] Will this slow down my checkout process? > > No. Our validation APIs are optimized for speed with sub-100ms response times. Address Capture actually speeds up checkout by reducing typing, and Address Verify runs post-checkout so it never interrupts the purchase flow. The app typically improves completion rates by reducing form errors. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Shopify App Details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB ### Launched April 2, 2024 ### Data access This app needs access to the following data to work on your store. Learn why in the developer's [privacy policy](https://www.loqate.com/en-us/privacy/). View personal data:Customers, store owner View and edit store data:Orders, Online Store [See details](https://help.shopify.com/en/manual/apps/app-permissions) # Shopify Plus Custom Field Mappings Source: https://docs.loqate.com/integrations/shopify-plus-custom-field-mappings Configure how Loqate address data maps to Shopify checkout fields, with support for templates, conditional logic, and country-specific overrides. Custom field mappings give you full control over how address data from Loqate is mapped into Shopify's checkout fields. By default, the Loqate app uses built-in logic to populate fields such as Address Line 1, Address Line 2, City, and so on. Custom field mappings allow you to override this behaviour when the default mapping doesn't suit your needs. > [!NOTE] > > Custom field mappings are optional. If you don't configure any, the app continues to use its built-in mapping logic. > You only need this feature if you want to change how address components are assigned to Shopify fields. ## When to use custom field mappings Common scenarios where custom field mappings are useful: * **Combining address components** — for example, merging a building name and street into a single Address Line 1 field * **Country-specific formatting** — some countries have address structures that don't map neatly to Shopify's standard fields * **Conditional logic** — including or excluding address components based on whether they have values, to avoid empty separators or trailing commas * **Field transforms** — converting field values to uppercase or truncating long values ## Accessing custom field mappings 1. Open **Loqate** under **Apps** in your Shopify admin 2. Select **Advanced Settings** in the Loqate app's menu 3. In the **Custom field mappings** summary, select **Manage field mappings** This opens the field mappings editor, where you can configure default mappings and country-specific overrides. *** ## How it works The field mappings editor has two main sections: ### Default mapping The default mapping applies to all countries unless overridden by a country-specific mapping. For each Shopify target field, you choose how to populate it — either by selecting a single source field from a dropdown, or by writing a custom template for more complex formatting. You can configure separate mappings for **Capture** (type-ahead address lookup) and **Verify** (post-checkout address verification), because these two services return different sets of address fields. ### Country overrides Country overrides let you define mappings that apply only to addresses in a specific country. When a country override exists, it is used instead of the default mapping for that country. This is useful when certain countries have unique address formats that require different field assignments. To add a country override, select the country from the dropdown and click **Add**. You can then configure Capture and Verify mappings for that country independently. *** ## Shopify target fields These are the Shopify checkout fields you can map to: | Field | Description | | - | - | | `address1` | Address Line 1 | | `address2` | Address Line 2 | | `company` | Company name | | `city` | City / Town | | `zip` | Postal / ZIP code | | `countryCode` | Country code (ISO 2-letter) | | `provinceCode` | Province / State code | *** ## Simple field mapping For straightforward one-to-one mappings, select the source field from the **Source Field** dropdown. This maps a single Loqate field directly to the Shopify target field. For example, mapping `line1` to `address1` will populate Shopify's Address Line 1 with the value of the Loqate `line1` field. *** ## Custom templates For more complex mappings, select **Custom template** from the Source Field dropdown to enter a template string. Templates use a Handlebars-style syntax that lets you combine fields, add conditional logic, and apply transforms. ### Basic syntax Insert a field value using double curly braces: ``` {{line1}} ``` Combine multiple fields with literal text between them: ``` {{buildingName}}, {{street}} ``` ### Conditional blocks Use `{{#if}}` to include content only when a field has a value. This prevents empty separators or trailing commas when optional fields are absent: ``` {{line1}}{{#if line3}}, {{line3}}{{/if}} ``` In this example, if `line3` has a value the output is `123 Main St, Apt 4B`. If `line3` is empty, the output is simply `123 Main St` — without the trailing comma. You can also use `{{else}}` for fallback content: ``` {{#if buildingName}}{{buildingName}}{{else}}{{line1}}{{/if}} ``` ### Transforms Apply transforms using the pipe (`|`) character: | Transform | Description | Example | | - | - | - | | `upper` | Convert to uppercase | `{{city \| upper}}` | | `lower` | Convert to lowercase | `{{city \| lower}}` | | `truncate N` | Truncate to N characters | `{{line1 \| truncate 30}}` | | `replace A B` | Replace A with B | `{{line1 \| replace "St" "Street"}}` | *** ## Source fields The available source fields differ depending on whether you are configuring a **Capture** or **Verify** mapping, because the two services return different address data structures. > [tab] Capture source fields > > Capture source fields come from the Loqate Address Capture (Retrieve) API response. > > **Address lines:** `line1`, `line2`, `line3`, `line4`, `line5` > > **Organisation:** `company`, `department` > > **Building / premise:** `subBuilding`, `buildingName`, `buildingNumber` > > **Street:** `street`, `secondaryStreet`, `block`, `neighbourhood` > > **Geographic hierarchy:** `district`, `city`, `adminAreaName`, `adminAreaCode`, `province`, `provinceName`, `provinceCode` > > **Postal:** `postalCode`, `pOBoxNumber` > > **Country:** `countryName`, `countryIso2`, `countryIso3` > > **Other:** `domesticId`, `language`, `languageAlternatives`, `sortingNumber1`, `sortingNumber2`, `barcode`, > `field1` through `field20` > [tab] Verify source fields > > Verify source fields come from the Loqate Address Verify API response. > > **Delivery address lines:** `deliveryAddress`, `deliveryAddress1` through `deliveryAddress8` > > **Address lines:** `address`, `address1` through `address8` > > **Organisation:** `organization`, `organizationName`, `organizationType` > > **Geographic hierarchy:** `superAdministrativeArea`, `administrativeArea`, `administrativeAreaIso2`, > `administrativeAreaName`, `administrativeAreaType`, `subAdministrativeArea`, `locality`, `localityName`, > `localityType`, `dependentLocality`, `dependentLocalityName`, `doubleDependentLocality` > > **Thoroughfare:** `thoroughfare`, `thoroughfareName`, `thoroughfareType`, `thoroughfarePreDirection`, > `thoroughfarePostDirection`, `dependentThoroughfare`, `dependentThoroughfareName` > > **Building / premise:** `building`, `buildingName`, `buildingType`, `premise`, `premiseNumber`, `premiseType`, > `premiseExtra`, `subBuilding`, `subBuildingName`, `subBuildingNumber`, `subBuildingType`, `subBuildingFloor` > > **Postal:** `postalCode`, `postalCodePrimary`, `postalCodeSecondary`, `postBox`, `postBoxNumber`, `postBoxType` > > **Country:** `country`, `countryName`, `iSO3166-2`, `iso3166_3`, `iso3166_n` > > **Other:** `sequence`, `contact`, `department`, `floorNumber`, `floorType`, `lotNumber`, `route`, `routeNumber`, `routeType` *** ## Examples ### Combine building name and street into Address Line 1 **Capture mapping for `address1`:** ``` {{buildingName}}{{#if street}}, {{street}}{{/if}} ``` **Result:** `Chester Business Park, Wrexham Road` or just `Wrexham Road` if there is no building name. ### Country-specific formatting for Japan Create a country override for **JP** and set the Verify mapping for `address1`: ``` {{thoroughfare}} {{subBuilding}} ``` ### Uppercase city names **Capture mapping for `city`:** ``` {{city | upper}} ``` **Result:** `LONDON` instead of `London` ### Fallback when a field might be empty **Capture mapping for `address2`:** ``` {{#if line2}}{{line2}}{{else}}{{#if line3}}{{line3}}{{/if}}{{/if}} ``` Uses `line2` if available, otherwise falls back to `line3`. *** ## Validation The app validates your templates when you save. Common validation errors include: * **Invalid field names** — only recognised source fields (listed above) can be referenced in templates * **Malformed template syntax** — unclosed `{{#if}}` blocks or mismatched braces * **Template too long** — templates have a maximum length to prevent unexpected behaviour If validation fails, you'll see an error message describing the issue. Fix the template and save again. *** ## Tips * Start simple. Use one-to-one field mappings where possible and only use custom templates when you need conditional logic or field combination. * Test with real addresses. After saving your mappings, run through the checkout with addresses from the countries you've configured to verify the output looks correct. * Country overrides take precedence. If both a default mapping and a country override exist for a given country, the country override is used and the default is ignored entirely for that country. * Capture and Verify are independent. You can configure custom mappings for Capture only, Verify only, or both. Whichever service doesn't have a custom mapping will continue using the built-in logic. *** > [card] [Back to Setup Guide](/integrations/shopify-plus-setup-guide) > > Return to the Shopify Setup Guide for full setup instructions. # Shopify Integration in Practice Source: https://docs.loqate.com/integrations/shopify-plus-integration-in-practice What the Loqate Shopify app does, which services run on your Shopify plan, how subscriptions and usage caps work, and how it looks in practice. The Loqate app adds address and email checking to your Shopify store. This page explains what the app does, where your customers see it, what runs on your Shopify plan, and how subscriptions work, so you know what you are buying before you install it. It finishes with a video and screenshots of the app in use. When you are ready to set it up, go straight to the task for your situation: > [card] [Set up Loqate as a new customer](/integrations/shopify-plus-setup-guide#set-up-loqate-as-a-new-customer) > > Coming from the Shopify App Store? Install the app, choose a plan through Shopify billing, and go live. > [card] [Connect an existing Loqate account](/integrations/shopify-plus-setup-guide#connect-an-existing-loqate-account) > > Already a Loqate customer? Use an API key from your Loqate account. ## What the app does The app installs from the Shopify App Store and runs inside your Shopify admin. It is built on Shopify's Checkout Extensibility framework, and adds three Loqate services to your store: * **Address Capture** suggests full addresses as a customer types, so they pick an address instead of typing one. * **Address Verify** checks an address a customer typed themselves and offers a correction. * **Email Validation** checks an email address as the customer enters it, so you can reach them about their order. Address Capture is on as soon as your store is set up. Address Verify and Email Validation are optional, and you switch them on in the app's settings. The services are designed to work together, but each one can be used on its own. > [!NOTE] > > The new Loqate app experience is being released to stores in stages. Until your store is included, > the app shows the previous settings screen. The welcome screen shows a **Rolling out gradually** > label while this is happening. ### Where your customers see Loqate | Where | Service | What the customer sees | | - | - | - | | Checkout, delivery address | Address Capture | Address suggestions while they type | | Checkout, email field | Email Validation | A message if the email address cannot be validated | | Checkout, delivery address | Address Verify, checkout option | A suggested correction before the order is placed | | Order confirmation page | Address Verify, post checkout option | A prompt to correct the delivery address after the order is placed | | Customer account, order details | Address correction | A prompt to correct the address on an order already placed | ### What you need * A Shopify store. The app installs on any Shopify plan, but your plan decides which Loqate services you can use — see [what works on your Shopify plan](#what-works-on-your-shopify-plan). * If you found Loqate in the Shopify App Store, a Loqate subscription bought through Shopify's billing. You choose one during setup, and the app creates your Loqate account for you. * If you are an existing Loqate customer, your Loqate account (created the standard way at [account.loqate.com](https://account.loqate.com/)) and an API key from that account. * A checkout that is not password protected, if you want to use the order confirmation page. ## What works on your Shopify plan You can install the Loqate app on any Shopify plan. What changes between plans is *where* Loqate is allowed to appear, because Shopify reserves parts of its checkout for stores on a Shopify Plus plan. | Loqate feature | Where the customer sees it | Basic, Grow, Advanced | Plus | | - | - | - | - | | Address Capture, suggestions as the customer types | Checkout, address fields | No | Yes | | Email Validation | Checkout, email field | No | Yes | | Address Verify, checkout option | Checkout, address fields | No | Yes | | Custom Loqate address capture input | Checkout, address fields | No | Yes | | Address Verify, post checkout option | Order confirmation page | Yes | Yes | | Address capture after the order is placed | Order confirmation page | Yes | Yes | | Address correction from a customer account | Customer account, order details | Yes | Yes | | The Loqate app, its settings and your subscription | Shopify admin | Yes | Yes | Shopify Starter sits outside this list of plans. A Starter store can install the app, but none of the checkout or order confirmation page features run on it. ### Why your Shopify plan decides this Shopify controls where an app is allowed to appear during a checkout, and reserves the checkout steps themselves — the address fields and the email field — for stores on a Shopify Plus plan. Anything that appears after the customer has paid is open to Basic, Grow, Advanced and Plus. Loqate does not gate any of this, and no Loqate plan unlocks it. Every Loqate subscription includes all three services. Your **Loqate** plan sets your monthly usage cap; your **Shopify** plan sets where those services can appear. ### If your store is not on Shopify Plus Be clear about what you lose: Address Capture does not suggest addresses in your checkout, and Email Validation does not check email addresses there. Your customers type their address the way they do today. What you keep is the way Loqate recommends running Address Verify anyway: * **Address Verify, post checkout option.** Loqate checks the delivery address once the order exists and offers the customer a correction on the order confirmation page. It uses fewer transactions than verifying during the checkout, because it runs only on orders you took. * **Address capture after the order is placed.** If the address could not be verified, the customer picks the right one from a list of suggestions on the order confirmation page. * **Address correction from a customer account.** A customer who has left the confirmation page can still correct the address from that order in their Shopify customer account. Each of these writes the corrected address back to the order itself, so the order ships to a checked address. ## Loqate services in your checkout Every subscription includes all three services. Your Loqate plan sets your monthly usage cap, not which services you get. Your **Shopify** plan is a separate thing, and it decides where each service is allowed to appear — [what works on your Shopify plan](#what-works-on-your-shopify-plan) covers that. ### Address Capture Address Capture is **enabled by default** once your store is set up. As a customer types in the address field, Loqate suggests matching addresses. The customer selects one and the address fields fill in. ![A list of matching addresses offered while a customer types a postcode into the checkout address field](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-suggestion.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=8ce4f9b9c6c7b7dc39ce9bf97a8039c5) Address Capture works in both the delivery address and billing address sections of the checkout. ### Address Verify Address Verify is **optional**. When a customer types an address themselves instead of choosing a suggestion, Address Verify checks it against Loqate's reference data using a process of correction, standardisation, formatting, enhancement and verification, and offers a correction. The customer can accept the correction or keep their original entry. Address Verify changes the delivery address only; it doesn't affect the billing address. ![A checkout showing a suggested corrected address for the customer to accept](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-correct-address.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=abfe3ec59b8d1d6a686918be3fc5fc3f) In the Loqate settings, Address Verify has three options and you can choose one: ![The Address Verify card in Loqate settings, showing three options: disable, post checkout, and checkout](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-address-verify-options.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=ba482275d799f7865356b470b65845f7) | Option | What it does | | - | - | | **Disable address verification** | Turns Address Verify off in the checkout and on the order confirmation page. | | **Enable address verification for post checkout (recommended)** | Checks the address after the order is placed, on the order confirmation page. | | **Enable address verification for checkout (use with caution)** | Checks the address during the checkout, before the order is placed. | > [!WARNING] > > Verifying during the checkout uses a Verify transaction for every address that reaches the > verification step, including checkouts the customer later abandons. It also cannot run for express > payments such as Apple Pay, Google Pay, Shop Pay and PayPal, because those skip the standard > address form. It also runs only on a Shopify Plus store, because Shopify reserves the checkout > steps for that plan. The post checkout option verifies the address only once an order exists, so > usage is lower, easier to predict, and it works on Basic, Grow, Advanced and Plus stores. > [!NOTE] > > Address Verify is not available with a Loqate SaaS platform key. If your store is connected with > one, both enabled options are greyed out and the settings screen says so. ### Email Validation Email Validation is **optional**. It checks the email address a customer enters during the checkout and tells them when it cannot be validated, so an order confirmation is less likely to bounce. Customers who enter a valid email address see no change to their checkout. You turn it on with the **Email Validation** switch in the Loqate settings. ![Email validation error message](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-email-validation-error.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=f3cd069e1dce1b3a9be49eb2a69592b7) Learn more about the [Email Validation Service](/api-reference/email-validation/individual). ## Subscriptions and usage caps Merchants who come to Loqate through the Shopify App Store buy it through Shopify's billing, as a monthly subscription with a usage cap. This section explains what you are charged for and what happens each month. Existing Loqate customers connect an API key from their Loqate account instead, and their billing stays with Loqate. ### Your plan is your monthly usage cap Each plan's price is also its cap. A £100 plan gives you £100 of address lookups, verifications and validations to use in that month. Every plan includes the same three Loqate services, so the only thing that changes between plans is the cap. ![The Choose your subscription screen, showing plan cards with a monthly usage cap, a credit pack size and the three included services](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-credit-pack.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=2973663b1a9146e6762aac1e1473e552) One plan carries a **Recommended** label. The plans your store is offered, and the prices shown, come from Loqate and can change, so treat the plans in this screenshot as an example. If none of them is large enough, you can [ask for a higher usage cap](/integrations/shopify-plus-setup-guide#ask-for-a-higher-usage-cap). ### Credit packs Your cap is issued to you in small amounts called credit packs, rather than as one large balance. Each plan card shows the pack size for that plan. * Packs are used up automatically as your store uses Loqate services. * New packs are created for you during the billing period, up to your cap. * You do not create, assign or top up packs yourself. Because packs are created as you need them, you pay for what you use rather than for the whole cap up front. ### Approving and activating You choose a plan in the Loqate app, then approve the charge on Shopify's own billing screen. Shopify sends you back to Loqate, and the app sets up your Loqate account. Activation takes a few minutes, and the app shows the status changing from **Activating** to **Activated**. You are not charged if the setup fails before Shopify takes over. ### Renewal and cap changes Your subscription renews automatically each month, on the same date as your first payment. Your cap resets at the start of each cycle. Keep your Shopify payment details up to date: if a charge fails, Shopify pauses collection until a payment succeeds. You can move to a different plan at any time. | Change | When it takes effect | | - | - | | A higher cap | Immediately, so the extra allowance is available straight away | | A lower cap | At the start of your next billing cycle if the new cap is lower than your current consumption; otherwise immediately | Lowering your cap does not affect usage you have already had this cycle. *** ## Shopify Integration In use See the Loqate Shopify app in use after it has been installed and configured. ### Video overview Here's what this looks like, using an example checkout page: [YouTube video player](https://www.youtube.com/embed/jKsEiiuqxac?si=1-X2VmPmFFXhPUJH) ### Example screenshots We've also put together some screenshots of how it looks on an example checkout page, to give you a sense of what to expect. > [tab] Address Capture in use > > Here's what it looks like during an address lookup and after an address has been selected in the Delivery address section: > > ![Address Capture Checkout](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-capture-checkout.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=a0d94602adaee90ec685c3a414e2475c) > > And here's what it looks like during an address lookup and after an address has been selected in the Billing address section: > > ![Address Capture Billing](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-capture-billing.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=110cb6a7580decd5ae75bbed24d62fe9) > > Note: the countries listed in the **Country/Region** dropdown list are tied directly to what you've set in the 'Shipping and delivery' > section of your Shopify store settings. Therefore, if you only ship to certain countries, only those countries will appear in the dropdown. > If a customer enters an address outside of those countries, Address Capture will not be able to return suggestions in the country they're > looking for and Address Verify will not recognise the inputted address (see the Address Verify section below). > > ![Country Dropdown](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-country-dropdown-1.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=8dbddde91d57394ea428bfa717f0e737) > > **NOTE:** We now recommend using the new Custom Capture Search Input for an improved search experience when finding sub-buildings. > > ![Custom Capture Search 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-containers-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=72e46985eb189e77627d41485d85aecb) > > ![Custom Capture Search 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-containers-2.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=9cf22dcf744509e4824677395263d20b) > [tab] Address Verify in use > > If you have enabled Address Verify, this functionality will trigger on the Thank You page after a customer has confirmed an order. > > Immediately after the Thank You page loads, a message will appear saying "Please wait while we verify your address..." > > This message will adjust depending on the results that Address Verify can return, with three main possibilities > > * No changes required > * Alternative address found > * Address not validated > > ### No changes required > > If the customer's address is successfully verified with no changes required, the Address Verify message will change to > "Your shipping address has been verified!" > > ### Alternative address found > > If, however, Address Verify finds an alternative address to suggest, the message will instead change to say > "We've found an alternate address", and give the customer the option of either applying or declining the proposed changes > > If the customer clicks **Apply changes**, the message will change to say "Your shipping address has been updated" > > **NOTE:** customers will not see the updated address reflected on the Thank You page, however if you check the Orders section > of your Shopify admin and find the transaction in question, you'll see that the shipping address has been updated. > > For example, here you can see that the billing address remains as it was originally inputted, but the shipping address has been > corrected by Address Verify > > ![Verify Thankyou](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-verify-thankyou-4-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=a88b47c0f445eff78c6ba3bdc143485b) > > You can also see evidence of the update in the order's timeline > > Not all customers will choose to use the alternative addresses offered by Address Verify, however. > If a customer chooses to ignore the suggestion, they will instead see a message which says "Your shipping address was not updated" > > ### Address not validated > > Lastly, if an address is sufficiently low quality that Address Verify can't validate it, > the customer will instead see a message reading "Your shipping address could not be validated, your order will still be processed." > [tab] Email Validation in use > > If you have enabled Email Validation, this functionality will trigger when a customer enters an invalid email address. > Here's what that will look like: > > ![Email Validation Usage](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-email-validation-usage-august-2024.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=d86006c416bbf9892b8ab0dba4c2cadb) > > When a customer enters a valid email address, this notification will disappear and they will be able to proceed through the checkout. *** ## Next step The [Shopify Setup Guide](/integrations/shopify-plus-setup-guide) covers installing the app, connecting an existing account, adding each service to your checkout, changing your settings, changing your cap, and cancelling or restarting a subscription. # Shopify Setup Guide Source: https://docs.loqate.com/integrations/shopify-plus-setup-guide Install Loqate in your Shopify checkout in minutes. Subscribe through Shopify or connect an existing account, then enable Address Capture, Address Verify, and Email Validation. In this guide we will provide all of the information you need to get up and running using the Loqate Shopify Integration: setting up the app, adding each Loqate service to your checkout, managing your settings, and handling your subscription and usage cap. If you're looking for the full details of what the Loqate Shopify Integration does, what runs on your Shopify plan, how subscriptions work, and what it looks like in practice, you can find that here: > [card] [Shopify Integration in Practice](/integrations/shopify-plus-integration-in-practice) > > What the app does, what works on your Shopify plan, and how subscriptions and usage caps work. ## Setup Video [YouTube video player](https://www.youtube.com/embed/y4_Brz0DOIk) *** ## Choose your setup route How you set up the app depends on how you came to Loqate: | You are | Use this route | Where you are billed | | - | - | - | | A Shopify merchant who found Loqate in the Shopify App Store | [Set up Loqate as a new customer](#set-up-loqate-as-a-new-customer), using Shopify billing | Shopify | | An existing Loqate customer | [Connect an existing Loqate account](#connect-an-existing-loqate-account), using an API key from your Loqate account | Loqate | If you are new to Loqate and coming from the Shopify App Store, subscribe through Shopify — you don't need to create a Loqate account or an API key first, because the app sets up your account for you. If you already have a Loqate account, created the standard way at [account.loqate.com](https://account.loqate.com/), connect it with an API key from that account instead. ## Prerequisites Before you start installing and setting up the Loqate Shopify Integration, you will need the following: * A Shopify store. The app installs on any Shopify plan, but your plan decides which Loqate services you can use. See [what works on your Shopify plan](/integrations/shopify-plus-integration-in-practice#what-works-on-your-shopify-plan). * A checkout that is not password protected, if you want to use the order confirmation page. If you are subscribing through Shopify: * You need permission to approve app charges for your store. * Have a few minutes spare at the end, while your account is set up. If you are an existing Loqate customer: * You need a live Loqate account at [account.loqate.com](https://account.loqate.com/). * You need an API key from that account (see the API keys section below). ### API keys You only need an API key if you are an existing Loqate customer. If you subscribe through Shopify, the app sets up your Loqate account for you once you approve your plan. Create the key in your Loqate account. Our [Creating API Keys page](/loqate-basics/create-an-api-key) explains how to do this. We recommend you create a generic API key dedicated to this service, but any key will work. **Note** You use Address Capture, Address Verify and Email Validation from a single API key. For information about how to ensure your Loqate integration is as secure as possible, see our [API Security page](/loqate-basics/api-security). *** ## Installation There are a few quick steps to get the Loqate Shopify Integration up and running: * Install the Loqate app, then either [set up Loqate as a new customer](#set-up-loqate-as-a-new-customer) or [connect an existing Loqate account](#connect-an-existing-loqate-account) * [Enable Address Capture, Address Verify and Email Validation](#enabling-loqate-services) * [Recommended - include company name](#recommended-include-company-name) As well as those key actions, there are also some additional steps that you can follow if required: * [Use without Address Capture (not recommended)](#optional-use-without-address-capture-not-recommended) * [Advanced Settings (optional)](#optional-advanced-settings) Follow these steps in order, and you'll get up and running quickly and easily. If you need help you can contact [LoqateSupport@GBG.com](mailto:LoqateSupport@GBG.com). ### Set up Loqate as a new customer Follow this route if you found Loqate in the Shopify App Store and your store has no Loqate account yet. You subscribe and pay through Shopify's billing. At the end you will have an active subscription and a working Loqate settings screen. **1. Install the Loqate app** Install [the Loqate app](https://apps.shopify.com/loqate) from the Shopify App Store. The [Shopify app installation instructions](https://help.shopify.com/en/manual/apps/installing-apps) explain how installing an app works. **2. Open Loqate in your Shopify admin** In your Shopify admin, open **Loqate** under **Apps**. The **Welcome to Loqate** screen opens. ![Welcome screen](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-welcome-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=8c9c66e47ea9af4461980edfae29211c) **3. Tell Loqate you are new** Select **I'm new to Loqate**, then select **Continue**. **4. Accept the terms and conditions** Select **Open the agreement in a new tab** and read the Loqate End User Licence Agreement. Return to the app, tick **I accept the Terms and Conditions**, then select **Continue**. ![Terms and Conditions](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-t-and-c.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=7dc1928fb94b47ff595dafa82303f342) **5. Choose your plan** On **Choose your subscription**, select the plan whose monthly usage cap suits your store, then select the approve button for that plan. If no plan is large enough, select **Need a higher cap?** to [ask for a custom plan](#ask-for-a-higher-usage-cap). ![The Choose your subscription screen, showing plan cards with a monthly usage cap and a credit pack size](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-credit-pack.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=2973663b1a9146e6762aac1e1473e552) [Subscriptions and usage caps](/integrations/shopify-plus-integration-in-practice#subscriptions-and-usage-caps) explains how plans, caps and credit packs work. **6. Approve the charge in Shopify** Shopify opens its own billing screen. Confirm your payment details and approve the subscription. Shopify then returns you to Loqate. **7. Wait for activation, then open settings** Loqate sets up your account. **Go to settings** stays unavailable until **Status** reads **Activated**, which usually takes a few minutes. Nothing is needed from you while you wait. ![The subscription outcome screen showing the plan, usage cap, an Activated status and the Go to settings button](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-subscription-activation.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=60cbf9b1ee1c6023aa1e7be7ef4e62da) When **Go to settings** becomes available, select it. You are set up when the Loqate settings screen opens. From now on, selecting **Loqate** in your Shopify admin takes you straight there. Next, [enable the Loqate services](#enabling-loqate-services) you want to use. #### If activation does not finish If the app is still setting up after five minutes, it offers **Check again**. If Shopify declines the charge, the app asks you to check your store's billing details in Shopify and try again. In both cases you can select **Contact support** to reach the Loqate team. ### Connect an existing Loqate account Follow this route if you are an existing Loqate customer. Your account is created the standard way at [account.loqate.com](https://account.loqate.com/), and you connect your Shopify store with an API key from that account, so your billing stays with Loqate and you do not take out a Shopify subscription. **1. Get an API key from your Loqate account** Sign in to [account.loqate.com](https://account.loqate.com/) and create an API key, as described in [API keys](#api-keys) above. **2. Install the Loqate app** Install [the Loqate app](https://apps.shopify.com/loqate) from the Shopify App Store. **3. Open Loqate in your Shopify admin** In your Shopify admin, open **Loqate** under **Apps**. The **Welcome to Loqate** screen opens. **4. Tell Loqate you are an existing customer** Select **I already use Loqate**. An **API key** field opens. **5. Enter your API key** Paste your Loqate API key into the field, then select **Use this key**. Keys look like `WA99-MC49-DU84-ZG25`, or like a 36-character identifier such as `0f8fad5b-d9cb-469f-a165-70867728950e`. If the key is not in one of those shapes, the app reports **The API key entered isn't in a known format** and stays on this screen. The settings screen opens once the key is accepted, and the **Authentication** card reports **Your Loqate API key is connected**. Next, [enable the Loqate services](#enabling-loqate-services) you want to use. > [!NOTE] > > Address Verify is not available with a Loqate SaaS platform key. If you connect one, both Address > Verify options are unavailable and the settings screen says why. #### What is different from a Shopify subscription | | Connected with your own key | Bought through Shopify | | - | - | - | | Where you are billed | Loqate | Shopify | | Usage allowance | Set by your Loqate account | Your monthly usage cap | | Managed from | [account.loqate.com](https://account.loqate.com), through **Open account & plan** on the settings screen | The Loqate settings screen | Your settings screen shows the **Authentication** card rather than a subscription cap, because there is no Shopify subscription to report. #### Change your API key On the settings screen, the **Authentication** card shows your key masked. Select **Show API key** to reveal it, or **Use a different key** to replace it. ### Enabling Loqate services > [tab] Enabling Address Capture > > > [!NOTE] > > > > Address Capture in the checkout, and the Custom Capture Search Input, need a Shopify Plus store. On Basic, Grow and > > Advanced, customers can still pick a verified address after the order is placed (see > > [Advanced Settings](#optional-advanced-settings)). > > With the app set up, the Standard Address Capture is automatically available. We however > recommend adding the Custom Capture Search Input as it offers an improved experience when > searching sub-building addresses. > > ![Custom Capture Search 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-containers-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=72e46985eb189e77627d41485d85aecb) > > First, you need to add the **Loqate-Checkout** app block to your store on the Checkout page. > (see [https://www.shopify.com/enterprise/blog/customize-shopify-checkout](https://www.shopify.com/enterprise/blog/customize-shopify-checkout)). > App blocks allow you to customise the look and functionality of your checkout layout. This block is required in order to > use the Custom Capture Search Input on the Checkout page. Here's how to add this block: > > 1. In the Admin section of your Shopify Plus account, go to Settings > Checkout. From here you can either edit your existing checkout, > or create a new draft of your checkout layout > > 2. Next, select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate' > > 3. Select the **loqate-checkout** app, then click the plus button and select **Checkout** from the drop-down list - this adds the > app block to the Checkout page > > 4. Next the [Standard Address Capture search must be disabled.](/integrations/shopify-plus-setup-guide#optional-use-without-address-capture-not-recommended) > This will not turn off Capture entirely. Capture will now only run in the app block added using the instructions above. If the standard search is left enabled, > Capture address searches will happen in two places on the checkout page (in the custom search input as well as the address text input) > > 5. With that done, make sure to save the changes to your checkout, then exit the editor. If you created a new checkout draft, > you can click the **Publish** button to make it live. > > [!WARNING] > > > > Only stores which are not password protected will successfully allow app > > blocks to be added. If the site is password protected, please disable this > > before adding. > > The final step is to enable the Custom Capture Search Input in the Loqate app. Select **Advanced Settings** in the Loqate app's menu, > tick **Display a custom Loqate address capture input on the checkout page**, then select **Save** in the **Unsaved changes** bar. > Note that the custom input cannot search for a billing address. Please test and check that on checkout a new address search > input has been added above the address form and addresses become available when searching addresses there. It's best practice to test these changes in a lower environment before going to production if possible. > > If continuing with the Classic Capture Search which places the address dropdown in the default address text input there is, however, an additional step to make sure Address Capture > is added to your checkout. Here are the steps to follow: > > * In the Admin section of your Shopify Plus account, go to **Settings > Checkout**. From here you can either edit your existing > checkout, or create a new draft of your checkout layout. > > * To edit your existing checkout click the **Customize** button, or to create a new draft checkout click the **Duplicate** button > followed by **Customize** on the new version. > > ![Duplicate Checkout](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-duplicate-checkout.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=cbda52a541ca431caeaebca4c22383d6) > > * Once you're editing your checkout, go to the Settings menu (the cog icon on the left-hand side), scroll down to the > **Address autocompletion** section and select the **Loqate** option to set Loqate as your provider: > > ![Address Autocompletion](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-autocompletion.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=b44cc7c788566bbee3f31924ada08b2d) > > * Make sure you save the changes to your checkout, then exit the editor. If you created a new checkout draft, > you can click the **Publish** button to make it live. > > Address Capture will now be available on your checkout. If you also want to enable Address Verify and/or Email Validation, > carry on through the Address Verify and Email Validation tabs. > [tab] Enabling Address Verify > > There are a few steps required to enable Address Verify functionality on your checkout. The post checkout option works on > Basic, Grow, Advanced and Plus stores; the checkout option needs Shopify Plus. > > First, you need to add the **Loqate-Checkout** app block to your store > (see [https://www.shopify.com/enterprise/blog/customize-shopify-checkout](https://www.shopify.com/enterprise/blog/customize-shopify-checkout)). > App blocks allow you to customise the look and functionality of your checkout layout and process, and this block is required in order to > use Address Verify on the Thank You (order confirmation) page. Here's how to add this block: > > * In the Admin section of your Shopify store, go to Settings > Checkout. From here you can either edit your existing checkout, > or create a new draft of your checkout layout (see the Address Capture section above for more details) > > * Next, select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate' > > * Select the **loqate-checkout** app, then click the plus button and select **Thank you** from the drop-down list - this adds the > app block to the Thank You page > > ![Add App Block](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-add-app-block-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=de252ca096d45b70e698b9b83101289b) > > * With that done, make sure you save the changes to your checkout, then exit the editor. If you created a new checkout draft, > you can click the **Publish** button to make it live. > > > [!WARNING] > > > > Only stores which are not password protected will successfully allow app blocks to be added. If the site is password protected, please disable this before adding. > > The next step is to disable the default address verification by Shopify. If this is left enabled, additional suggestions may be > displayed against individual address fields, which can cause confusion for customers. > > * Still in Settings > Checkout, scroll down to the **Address collection preferences** section: > > ![Address Collection](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-collection-small.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=13ae16e7b6419658ce371d50d6455526) > > * Make sure the **Validate shipping address** option is unticked, then click the Save button > > The final step is to enable Address Verify on the Loqate settings screen. > > Once your subscription is activated or your API key is connected, the **Address Verify** card on the settings screen becomes > editable. It has three options, and you choose one: > > ![Address Verify options](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-address-verify-options.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=ba482275d799f7865356b470b65845f7) > > * **Disable address verification** turns Address Verify off in the checkout and on the order confirmation page > * **Enable address verification for post checkout (recommended)** checks the address after the order is placed, on the > order confirmation page > * NOTE: to use the post checkout option, please ensure your store is not > [password protected](https://help.shopify.com/en/manual/online-store/themes/password-page) > * **Enable address verification for checkout (use with caution)** checks the address during the checkout, before the order > is placed. This is not recommended because it consumes Verify transactions during checkout (including abandoned checkouts), > and it only runs on Shopify Plus stores. See the note below. > > Select **Save** in the **Unsaved changes** bar, and Address Verify will now be available. > > > [!NOTE] > > > > Address Verify is not available with a Loqate SaaS platform key. If your store is connected with one, both enabled options > > are greyed out and the settings screen says so. > > > [!NOTE] > > > > **Address Verify on the checkout page ("Enable address verification for checkout")** > > > > Use this option with caution. When Address Verify runs on the checkout page (rather than after checkout), the customer's address is verified while they are still completing their order. > > > > This has a few important implications: > > > > * It uses Verify transactions during checkout. Every address that reaches the verification step is checked against Loqate Verify and counts towards your usage — including checkouts that customers later abandon before placing an order. The post checkout option only verifies the address once the order has actually been placed, so it typically results in fewer Verify requests and more predictable usage. > > * It does not work with express / wallet payments. Apple Pay, Google Pay, Shop Pay, PayPal and similar express checkouts bypass the standard address form, so Address Verify cannot run for those orders and the customer will not be prompted to correct their address. > > * It adds a step to the checkout flow. Because verification happens before the order is placed, customers may be asked to confirm or correct their address as part of completing checkout. > > * It needs a Shopify Plus store. Shopify reserves the checkout steps for Shopify Plus, so this option does not run on Basic, Grow or Advanced stores. > > > > For most stores we recommend the **Enable address verification for post checkout** option, which verifies the address after the order is placed and avoids the points above. Only enable verification on the checkout page if you specifically need the address corrected before the order is created and you understand the additional Verify usage this can incur. > [tab] Enabling Email Validation > > > [!NOTE] > > > > Email Validation runs in the checkout email field, so it needs a Shopify Plus store. > > The steps to enable Email Validation in your checkout are similar to those for Address Verify. > > First, add the **Loqate-Checkout** app block to your store (if it hasn't already been added by the Capture installation) - It needs to be added to the **Checkout** section. > > * In the Admin section of your Shopify Plus account, go to Settings > Checkout. From here you can either edit your existing checkout, > or create a new draft of your checkout layout (see the Address Capture section above for more details) > * Select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate' > * Select the **loqate-checkout** app, then click the plus button and select **Checkout** from the drop-down list > > ![Add App Block 2](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/shopify-plus/shopify-add-app-block-2-june-25.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=0d11ce8c547a25bb7d479c3a669c4006) > > Once that's done, you just need to turn on the **Email Validation** switch on the Loqate settings screen. > > Once that's done, select **Save** in the **Unsaved changes** bar and move on to the next section. *** ### Recommended - Include company name By default, Shopify is set to not include a **Company name** address field. As such, if an address includes a company name (for example if a customer orders a delivery to their place of work) it won't be included in the address that's populated in Shopify. We recommend setting Shopify to include Company name as an optional address field, so that it will be populated any time an address does include a company name. Here's how to change that setting: * Go to the site Settings page for your Shopify store * Select the **Checkout** option from the left-hand menu * Scroll down to the **Customer information** section ![Company Name Settings](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-company-name-settings-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=ccd1dd782c35c4ed29de31907c3528f5) * Set Company name to **Optional**, then click the Save button With that done, you should now see an optional Company address field in the checkout: ![Company Name 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-company-name-1-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=c47adb99270a36a4985a1d0dc16a3fb9) *** ### Optional - Use without Address Capture (not recommended) We recommend always using Address Capture, as this helps reduce the chances of mistakes caused by manual address entry, ensuring addresses can be trusted as correct and giving the best customer experience. It is, however, possible to use just Address Verification or just Email Validation if you don't want any kind of address autocompletion functionality. If you want to use Address Verification and/or Email Validation on their own, follow the full installation and setup process as above, then you can manually disable Address Capture. Here's how to do that: * First, make sure that you've enabled at least one of Address Verification and/or Email Validation (see the [Enabling Loqate services](#enabling-loqate-services) section earlier) * Then, go to Settings > checkout and click the **Customize** option for your checkout * Click on the **Settings** icon on the left-hand side, then scroll down to the **Address autocompletion** section ![Address Autocompletion](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-verify-1-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=cefb80bdc8491f0d8fd11c15c3fb7bd7) * Untick the **Use address autocompletion** option, then save the change to your Checkout configuration This will have disabled the Address Capture functionality, while leaving Address Verify and/or Email Validation running. *** ### Optional - Advanced Settings Select **Advanced Settings** in the Loqate app's menu to open the Advanced Settings page. It includes the following optional settings, as well as the **Display a custom Loqate address capture input on the checkout page** option described in the [Address Capture](#enabling-loqate-services) tab above. Select **Save** in the **Unsaved changes** bar after making a change. > [accordion] Force addresses to be returned in latin character sets where available > > With this selected, Address Capture will always attempt to use any English results to set the delivery address, even with non-latin > results. Note that for this setting to work, the **Display a custom Loqate address capture input on the checkout page** option > must be **enabled**. > > For example, here's a Japanese address searched for using Kanji characters: > > ![Non-Latin 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-non-latin-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=a66afa2d3bb464c86b3898d97561c1c3) > > And here's the result populated using the English version of the address: > > ![Non-Latin 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-non-latin-2.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=9918afbf3932b99d95b2557cda8f87b5) > > This is useful for when carriers have difficulty processing non-latin addresses. > [accordion] Use address capture to allow customers to update their address if the shipping address cannot be verified > > With this enabled, customers can manually amend their addresses post-checkout, if what they initially entered can't be verified. > This runs on the order confirmation page, so it works on Basic, Grow, Advanced and Plus stores. > For example, if a customer hasn't entered their building number or apartment number they can go back and add it in. > > Under these circumstances, after an order has been confirmed the customer will be presented with a list of possible addresses to > choose from: > > ![Post Checkout Verify 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-post-checkout-verify-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=23efc21483cc4300c72e63aa5b14bfd5) > > If the customer selects one of the suggested addresses, they will then see a notification acknowledging the address they've selected > and giving them the option to update their shipping address: > > ![Post Checkout Verify 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-post-checkout-verify-2.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=06f7c6ec392f1a2f6ba15e0150fca60c) > [accordion] Use enhanced country validation on unverified addresses > > Sometimes it can be possible for a customer to enter an address with the wrong country, which as standard will be flagged as an > unverified address. > > Selecting this option enables Address Verify to be automatically called for a second time whenever an address is returned as unverified. > For the second call, Address Verify will run using enhanced country verification, providing another opportunity to verify the address > with the correct country. > > For this to function Address Verify must be enabled on the **Thank you** page. This functionality uses an extra Verify transaction > for each second check, which counts towards your usage cap or Loqate account usage. > [accordion] Custom field mappings > > Custom field mappings allow you to control how Loqate address data is mapped into Shopify's checkout fields. By default, the app uses > built-in logic to populate fields like Address Line 1, Address Line 2, City, and so on. With custom field mappings, you can override > this behaviour — either globally or on a per-country basis — to handle address formats that don't fit the default mapping. > > This is useful when you need to combine multiple address components into a single Shopify field, apply conditional logic based on > whether certain fields have values, or handle country-specific formatting requirements. > > To configure custom field mappings, select **Manage field mappings** in the **Custom field mappings** summary on the Advanced Settings page. For full details on how > to set up and use this feature, see the dedicated guide: > > > [card] [Custom Field Mappings Guide](/integrations/shopify-plus-custom-field-mappings) > > > > Learn how to configure custom field mappings with template syntax, country overrides, and examples. *** ## Manage your Loqate settings The settings screen is where you turn Loqate services on and off and check your subscription. Open it by selecting **Loqate** under **Apps** in your Shopify admin. ![Shopify Settings Screen for New Loqate Users with subscription](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-settings-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=cf1c17cfcdb651e3972b2c233c942d99) ### What is on the screen | Card | What it is for | | - | - | | Subscription | Your usage cap, your API key, or a prompt to buy a subscription. The card you get depends on how your store pays for Loqate. | | **Loqate services** | A summary of Address Capture, Address Verify and Email Validation. Nothing to set here. | | **Address Verify** | Choose one of the three verification options. | | **Email Validation** | Switch email checking on or off. | The page header also carries **Open integration guide**, which opens this documentation. [Loqate services in your checkout](/integrations/shopify-plus-integration-in-practice#loqate-services-in-your-checkout) explains what each Address Verify option does before you choose one. ### Your subscription card The screen shows one of three subscription cards, chosen from your store's own records. | Your situation | What you see | What you can do | | - | - | - | | You have a Shopify subscription | **Current subscription cap** and your monthly figure | Select **Change cap** to move to a different plan | | Your Shopify subscription has ended | **No subscription**, with the message that your subscription has ended | Select **Choose a subscription** to buy one | | You pay Loqate directly | **Authentication**, with your API key masked | Select **Show API key**, or **Use a different key**. **Open account & plan** opens your Loqate account | If the card reads **Cap unavailable**, Shopify could not report your cap at that moment. Your subscription is unaffected and **Change cap** still works. Refresh the page to try again. ### Save a change The save bar appears at the top of the screen as soon as you edit a setting, and it is the only way to save. 1. Change a setting. 2. Select **Save** in the **Unsaved changes** bar, or **Discard** to undo your edits. If you leave the screen with unsaved changes, the app asks whether to **Leave page** or **Stay**. *** ## Change your usage cap Move to a different plan when your store needs more or less monthly allowance. This applies to stores subscribed through Shopify; if you connected your own API key, manage your allowance in your Loqate account. 1. Open the Loqate settings screen. 2. On the subscription card, select **Change cap**. The **Change your subscription cap** screen opens. 3. Select the plan whose monthly usage cap suits your store. If no plan is large enough, select **Need a higher cap?** to [ask for a custom plan](#ask-for-a-higher-usage-cap). A higher cap is available straight away. A lower cap can wait until your next billing cycle — see [renewal and cap changes](/integrations/shopify-plus-integration-in-practice#renewal-and-cap-changes). ## Ask for a higher usage cap If none of the plans on offer has a large enough monthly usage cap, use the contact form in the app to ask for a custom plan. Have an idea of the cap you need and how many orders your store processes in a month. The Loqate team uses both to work out a plan for you. ### Send a request **1. Open the contact form** On **Choose your subscription** or **Change your subscription cap**, select **Need a higher cap?**. ![Contact screen](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-contact-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=08e6b8256bacd7f53dbc1abf56b98841) **2. Check your details** **Shop domain**, **Your name** and **Email address** are filled in from your Shopify account. **Shop domain** cannot be edited. Correct your name or email address if they are wrong, because the reply goes to the email address on the form. **3. Choose a topic** **Topic** is already set to **Higher usage cap**. The other options are **Billing question**, **Technical issue** and **Other**. **4. Describe what you need** In **Tell us more**, say what cap you are looking for and how many orders you process a month. **Send message** stays unavailable until you write something. **5. Send it** Select **Send message**. A **Message sent** banner confirms the request, and the Loqate team replies to the email address on the form. Select **Back to plans** to return to the plans you came from, or **Cancel** to go back without sending. ### If the message does not send The screen reports **Message not sent** when it cannot reach Loqate. The **Call us** card on the same screen lists a phone number and the hours the team is available, and calling gets you a faster answer than the form. ## Cancel and restart your subscription Cancel a Loqate subscription from the Shopify admin, in the same place you manage your other app charges. Your subscription stays active until the end of the billing period you have paid for, then it does not renew. After it ends, the Loqate settings screen shows **No subscription**. The app stays installed, but the services need an active subscription to run. To start again, select **Choose a subscription** and pick a plan. Your access is restored once the new subscription is approved and activated. *** ## Troubleshooting > [accordion] I can't see some of the Admin options described in this guide > > The app installs on any Shopify plan, but Shopify reserves the checkout steps for Shopify Plus stores. If you don't use Shopify Plus, > you won't see the checkout editor options for Address Capture, Email Validation or the Address Verify checkout option. The post > checkout features on the order confirmation page still work on Basic, Grow and Advanced. See > [what works on your Shopify plan](/integrations/shopify-plus-integration-in-practice#what-works-on-your-shopify-plan). > [accordion] My subscription is still activating > > Activation usually takes a few minutes. See [if activation does not finish](#if-activation-does-not-finish). > [accordion] The Capture autocomplete field is not showing on my checkout > > Checkout autocomplete needs Shopify Plus; on Basic, Grow and Advanced it will not appear even with an active subscription or connected key. On Shopify Plus, check that your subscription shows as active on the Loqate settings screen, or, if you connected your own key, that the **Authentication** card reports **Your Loqate API key is connected**. > [accordion] When selecting an address, the fields do not populate > > Check that your subscription is active and that you have not used up your monthly usage cap. If you connected your own key, check > that your API key is correct on the **Authentication** card and that you have sufficient credit on your Loqate account. If you need > more allowance, [change your usage cap](#change-your-usage-cap). > [accordion] How do I uninstall the Loqate app? > > If you no longer want to use the Loqate Shopify integration, you can uninstall it from your Shopify store. > > **Please note:** if you uninstall the Loqate app and then want to start using it again at a later date, you will need to go through the > full installation process again. > > To uninstall the Loqate app, go to the Admin page of the app within your Shopify account and click on the three dots at the top-right of > the screen. You will see an option to uninstall there: > > ![Uninstall](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-uninstall-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=23898b227eae9ff0ff619ac7e561b9d8) > > When you click **Uninstall**, you'll be prompted to choose a reason for uninstalling: > > ![Uninstall 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-uninstall-2.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=3c38e422e6f3e51ea836a47ca8b7df53) > > Select one or more reasons, then click the **Uninstall** button. This will uninstall the app and return you to the 'Installed Apps' > section of your Admin page. *** > [card] [Further reading](/integrations/shopify-plus-integration-in-practice) > > If you haven't already, check out our 'Shopify Integration in Practice' > article for what runs on your Shopify plan, how subscriptions and usage caps > work, and examples of the integration in use. # Shopware 6 Integration Source: https://docs.loqate.com/integrations/shopware Add Loqate address, email and phone validation to Shopware 6. Install from the Shopware Store and configure each service per sales channel. ### Works with: Shopware 6 ### Supported Loqate Services:
                      [Integrate in 3 steps](#integrate-in-3-steps) ## About this integration The Loqate extension for Shopware 6, available from the [Shopware Store](https://store.shopware.com/en/loqat57696326011f/address-verification-with-email-and-phone-validation.html), adds address, email and phone validation to your store. You choose which services to activate, and whether settings apply to all of your sales channels or only to specific ones. ## Supported Loqate Services > [tab] Address Validation > > ### Address Validation > > Help customers enter accurate addresses so orders reach the right place. > > **Key Features:** > > * Activate for all sales channels or dedicated sales channels only > > [Learn more about Address Capture](/our-services/address-capture/overview) > [tab] Email Validation > > ### Email Validation > > Check that the email addresses customers enter are valid. > > **Key Features:** > > * Activate for all sales channels or dedicated sales channels only > > See the [Email Validation API documentation](/api-reference/email-validation/individual) to learn more about the service. > [tab] Phone Validation > > ### Phone Verification > > Check that the phone numbers customers enter are valid. > > **Key Features:** > > * Activate for all sales channels or dedicated sales channels only > > See the [Phone Validation API documentation](/api-reference/phone-validation/individual-validate) to learn more about the service. > [card] [Setup guide](/integrations/shopware-setup-guide) > > Install the extension, add your API key and activate your services ## Integrate in 3 steps 1\) Get your API key 2) Install from the Shopware Store 3) Configure the plugin > [card] > > Get your API key, then install from the Shopware Store > > Add your key in the plugin configuration and choose which services to activate for each sales channel. > > 1. Get Your API Key > > [Open](https://account.loqate.com/) > > 2. Install the Extension > > [Open](https://store.shopware.com/en/loqat57696326011f/address-verification-with-email-and-phone-validation.html) > > 3. Configure the Plugin > > [Open](/integrations/shopware-setup-guide#configure-the-plugin) ## Pricing > [card] [View Pricing Plans](https://www.loqate.com/pricing) > > Flexible plans starting with a 45-day free trial. Choose the plan that fits your business needs. ## Frequently Asked Questions > [accordion] Can I use different settings for different sales channels? > > Yes. You can apply the plugin settings to all sales channels, or activate the individual Loqate services for dedicated sales channels only. > [accordion] How do I check my API key is working? > > After entering your API key in the plugin configuration, click **check API key** to verify that a connection to the Loqate API has been established. > [accordion] Can I restrict how my API key is used? > > Yes. Each key has its own security settings, including URL and IP restrictions and usage restrictions, and you can set up as many keys as you need. See [API Security](/loqate-basics/api-security) for more information. Still have questions or need support? [Send us an email](mailto:LoqateSupport@gbgplc.com) ## Integration details Resources [Privacy policy](https://www.loqate.com/en-us/privacy/) Developer GB GROUP PLC [Website](https://www.loqate.com/) 128 Queen Victoria Street, London, ENG, EC4V 4BJ, GB Platform Shopware 6 [View on Shopware Store](https://store.shopware.com/en/loqat57696326011f/address-verification-with-email-and-phone-validation.html) # Shopware 6 Setup Guide Source: https://docs.loqate.com/integrations/shopware-setup-guide Install the Loqate extension from the Shopware Store, add your API key and activate address, email and phone validation per sales channel. > [card] [Get the Shopware 6 plugin](https://store.shopware.com/en/loqat57696326011f/address-verification-with-email-and-phone-validation.html) For an overview of what the integration does, see the [Shopware 6 integration overview](/integrations/shopware). ## Install the extension from the store Install the Loqate extension from the [Shopware Store](https://store.shopware.com/en/loqat57696326011f/address-verification-with-email-and-phone-validation.html). ## Configure the plugin Open your extensions after installing the plugin and switch to the configuration mode. ### Define the sales channel Here you can choose if you want the plugin settings to apply to all the sales channels. You can also choose to activate the separate Loqate services for dedicated sales channels only. ### Provide the API key APIs require authentication through a key, which is created by adding a service to your account. Each key has its own security settings (URL and IP restriction, usage restrictions). As many keys as necessary can be set up with these restrictions. Enter the API key in the dedicated field. By clicking the “check API key” you can verify whether a connection to the Loqate API has been successfully established. ### Activate your services Here you can define, which Loqate services you want to activate for your sales channel. * Address validation * Email validation * Phone verification Save your settings by clicking “save” and verify that the extension has been set to “active”. # Welcome to GBG Loqate Docs Source: https://docs.loqate.com/introduction Find all the guides and resources you need to build with Loqate > [card] [Quickstart](/loqate-basics/create-an-api-key) > > Learn how to get started with Loqate's services > [card] [API Reference](/api-reference/introduction) > > Explore our comprehensive API documentation and endpoints > [card] [Integrations](/integrations/all-integrations) > > Native integrations with leading e-commerce platforms and CRMs > [!TIP] > > **🤖 New: Reach — Loqate for Agents** > Building agentic workflows? Reach verifies addresses, emails, and phone numbers in real time — returning a confidence score, a policy-aware recommendation, and a full audit trail in one command. > > [Explore Reach](https://agents.gbg.com/reach.html) > [!TIP] > > **🎉 New: Loqate Core SDKs (Beta)** > We've launched early-access SDKs for TypeScript and .NET as part of our wider DevEx revamp.\ > They're ready to explore and already used internally — try them out and let us know how they feel. > > See the [SDK Overview](/sdks/overview) for details. Try Loqate for free with a [45-day trial](https://www.loqate.com/en-gb/get-started/) ## Explore Products > [card] [Address Capture](/our-services/address-capture/overview) > > Speed up a user's address entry with our address capture service > [card] [Address Verify](/our-services/address-verify/overview) > > Review and clean up existing address data with our verification service > [card] [Email Validation](/our-services/email-validation/overview) > > Real-time email address verification and validation > [card] [Phone Validation](/our-services/phone-validation/overview) > > Validate and verify phone numbers across global networks > [card] [Bank Validation](/our-services/bank-validation/overview) > > Real-time verification of bank account details and routing numbers See all location and data validation [solutions](/loqate-basics/list-of-endpoints) ## Get Started From an API call to successful delivery in 3 steps Step 1 Create an API Key Get your API key from the dashboard to make requests. [Get started here](/loqate-basics/create-an-api-key) Step 2 Make your first call Send your first API request to validate an address or email. [View API Reference](/api-reference/introduction) Step 3 Parse the response Handle the response data to improve your user experience. [Response Guide](/api-reference/introduction) ## Supported Integrations Native integrations with leading e-commerce platforms and CRMs > [card] > > ![Shopify Plus](https://uat.loqate.com/media/dgfnoekv/shopify-plus.svg) > > ### Shopify Plus > > Native integration for Shopify Plus stores > > [Open](/integrations/shopify-plus) > [card] > > ![Adobe Commerce](https://uat.loqate.com/media/gjrk4ijt/adobe-commerce.svg) > > ### Adobe Commerce > > Magento and Adobe Commerce integration > > [Open](/integrations/adobe-commerce) > [card] > > ![BigCommerce](https://uat.loqate.com/media/n4papthm/bigcommerce.png) > > ### BigCommerce > > BigCommerce platform integration > > [Open](/integrations/bigcommerce) > [card] > > ![Microsoft Dynamics 365](https://uat.loqate.com/media/wuhpl5sr/dynamic365.svg) > > ### Microsoft Dynamics 365 > > Dynamics 365 CRM integration > > [Open](/integrations/microsoft-dynamics-365) > [card] > > ![Salesforce](https://uat.loqate.com/media/rzehm0gb/salesforce.svg) > > ### Salesforce Commerce Cloud > > Salesforce Commerce Cloud integration > > [Open](/integrations/salesforce-commerce-cloud) > [card] > > ![commercetools](https://uat.loqate.com/media/ow3bk2m2/commercetools.svg) > > ### commercetools > > commercetools headless commerce platform > > [Open](/integrations/commercetools) > [card] > > ![Salesforce](https://uat.loqate.com/media/rzehm0gb/salesforce.svg) > > ### Salesforce CRM > > Salesforce CRM integration > > [Open](/integrations/salesforce-crm) > [card] > > ![Shopware](https://uat.loqate.com/media/43wgb1x0/shopware.svg) > > ### Shopware > > Shopware e-commerce platform > > [Open](/integrations/shopware) > [card] > > ![Reapit](https://mintcdn.com/loqate/lWfUs4aqJ-lwssBc/images/integrations/reapit/reapit.png?fit=max\&auto=format\&n=lWfUs4aqJ-lwssBc\&q=85\&s=ab2a28d2e3fd32a65cc0b6929dcd0b6a) > > ### Reapit > > Reapit property software integration > > [Open](/integrations/reapit) Don't see your platform? [Request an Integration](mailto:LoqateSupport@gbgplc.com) ## Help and Support Get the assistance you need from our expert team > [card] [Visit Help Center](/getting-started/introduction/) > > Access documentation, guides, and technical support resources > [card] [Speak to an Expert](https://www.loqate.com/en-gb/contact/customer-support/) > > Connect with our team for Sales or Support ## Security & Compliance Enterprise-grade security and compliance standards you can trust > [card] ISO 27001 > > International security management standard > [card] Trust & Privacy > > [GBG Privacy Approach](https://www.loqate.com/en-us/privacy/privacy-approach/) > [GBG Trust Center](https://secureandtrusted.gbgplc.com/) > [card] [Upguard Score](https://www.upguard.com/security-report/gbg) > > 905+Out of 950 ## Engineering Thoughts and Resources > [card] [Developer Blog](https://www.loqate.com/en-gb/blog/?usecase=Developers\&page=1) > > Find out about use cases and Loqate features > [card] [Community Slack](https://join.slack.com/t/loqate-workspace/shared_invite/zt-2xhkfmb38-3iIhtlRGO88k6dub4F4qzQ) > > Join our developer community > [card] [Code Tutorials](/tutorials) > > Step-by-step coding tutorials and best practice guides > [card] [Video Tutorials](/videos) > > Step-by-step video guides > [card] > > Self-Hosting > Get started with self-hosting Loqate. > [More on Self-Hosting](/getting-started/introduction/) > > Verification > > Geocoding > > Parsing > > Batch Processing > > [Open](/getting-started/introduction/) ## Frequently Asked Questions Everything you need to know about our services and APIs > [accordion] What is the difference between the Capture & Verify services? > > Capture is a user-present address capture service, designed to ensure accuracy and standardization at the point of entry by guiding users to select validated addresses in real time. In contrast, Verify is a data cleansing service that processes and corrects address data already held within a system, ensuring it conforms to postal and formatting standards. Verify can operate in both user-present scenarios e.g. validating input within a form and non-user-present contexts e.g. bulk cleansing of existing datasets or automated background validation. > [accordion] What are the rate limits and how do you handle scaling? > > Our APIs are designed to handle high-volume requests with automatic scaling. Rate limits vary by plan, starting from 1,000 requests per month on our free tier to unlimited requests on enterprise plans. > [accordion] How do you ensure data privacy and GDPR compliance? > > We are fully GDPR compliant and follow strict data privacy standards. We use 256-bit encryption, implement zero data retention policies, and provide data processing agreements for enterprise customers. > [accordion] Which countries and address formats do you support? > > We support 245+ countries and territories worldwide with comprehensive address format coverage including postal codes, administrative areas, and locality information. > [accordion] Do you provide webhooks for bulk processing and status updates? > > Yes, we provide webhook support for bulk processing operations and real-time status updates. You can configure webhooks to receive notifications when bulk jobs complete or encounter errors. > [accordion] How accurate is the validation and what's your error handling? > > Our validation accuracy exceeds 99% for most countries. We provide detailed error codes and messages to help you handle edge cases and provide meaningful feedback to your users. Still have questions? [Send us an email](mailto:LoqateSupport@gbgplc.com) # Local API Source: https://docs.loqate.com/local-apis/introduction Loqate's local APIs provide native libraries on a wide variety of platforms to allow the use of fast, embedded functionality within a client environment. The Loqate API is a multithreaded library able to make excellent use of multi-core CPUs and multiprocessor systems. Client applications interact with the Loqate server making calls to Loqate's Local API. The Loqate Local API is installed in a single directory on the physical server. A /data subdirectory contains Loqate's Global Knowledge Repository (GKR). The Loqate Local API product is self-contained and does not require any third-party database to be installed. All required reference data is contained in the application itself. No complex installation nor configuration is required. ## API Documentation > [card] [C++/Java/.Net Functional Reference](/support/installed-api/) > [card] [Command Line Batch Processor](/support/batch-processor/) > [card] [Available Processes](/available-processes/introduction/) > [card] [SERP Overview](/local-apis/serp-overview/) > [card] [CASS Overview](/support/usa-cass-v2/) > [card] [AMAS Overview](/support/address-matching-approval-system-amas/) ## Transaction Recording Service Being a random-access data-based application, the Loqate Engine will show higher performance with faster I/O systems and more memory available for caching. Better performance is achieved when the Global Knowledge Repository data files and the Loqate application are co-located in the same server. It may be useful to mention that the use of the term "Loqate server" should be interpreted as being a software application instead of an application server such as, for example, the Apache server. The Loqate server does not include server-client capabilities related to load balancing, failover, nor wait for client requests on certain physical port number. High availability, load balancing, failover capabilities are expected to be handled by the physical server or network hosting the Loqate Engine. # SERP Overview Source: https://docs.loqate.com/local-apis/serp-overview ## What is SERP The Address Accuracy Software Evaluation and Recognition Program (SERP) ensures the best postage rates for your mailing list. ### Platform Availability SERP is currently only available on the following platforms: > [card] [Windows 32-bit](/getting-started/system-requirements/win32bit/) > [card] [Windows 64-bit](/getting-started/system-requirements/win64bit/) > [card] [Linux 64-bit](/getting-started/system-requirements/linux64bit/) > [card] [AIX](/getting-started/system-requirements/aix/) ### Release Cycle Please note, SERP dataset expiration dates are set by the postal authority. Please ensure that you have the latest library and data installed to avoid loss of service through these products. ### How To Run SERP There are two ways to run the SERP certified certification in the Loqate Engine: **Option 1: Direct SERP Process** Invoke the SERP certification process for Canada directly by adding the process "SERP" to the process-list. In batch mode, run lqtbatch with the process set as "serp": ```bash theme={null} lqtbatch -p serp -r SERP ``` This will generate a SERP address accuracy report. **Option 2: Via Verify Process** Invoke the certification process by calling the "verify" process while setting the server-option `CertifiedCountryList` to "CAN" – this will internally invoke the SERP process for Canadian addresses in your dataset. As we extend our certification process support to other countries, you will be able to specify the countries for which you want to run the certified process (as opposed to the Loqate "verify" process) through comma-separated list of country code values for the `CertifiedCountryList` option. ### Input Requirement **Important note:** SERP process requires the input addresses to be in the following format as input. The input headers must also match Loqate address fields, found on the support site [here](/field-descriptions/addfields/). * Address1 (required) * Address2 (optional) * Locality (optional) * AdministrativeArea (optional) * PostalCode (optional) * Country (required) ### Output Component Fields The following page includes detailed information regarding the SERP Fields: * [SERP Fields](/field-descriptions/serp-fields/) ### Sample Outputs #### Example 1 **Input address:** `550 BURRARD ST RM 1230 VANCOUVER BC V6C2K2` **Result Codes:** | Field | Output | | - | - | | **SerpStatusEx** | V | | **Questionable** | Empty | **Components:** | Address Field | Output | | - | - | | **PremiseNumber** | 550 | | **ThoroughfareName** | BURRARD | | **ThoroughfareTrailingType** | ST | | **SubBuildingType** | RM | | **SubBuildingNumber** | 1230 | | **Locality** | VANCOUVER | | **AdministrativeArea** | BC | | **PostalCodePrimary** | V6C2K2 | #### Example 2 **Input address:** `PO BOX 1200 SUCC POINTE-CLAIRE POINTE-CLAIRE QC H9R4R6` **Result Codes:** | Field | Output | | - | - | | **SerpStatusEx** | V | | **Questionable** | Empty | **Components:** | Address Field | Output | | - | - | | **PostBoxType** | 1200 | | **DeliveryInstallationType** | SUCC | | **DeliveryInstallationQualifierName** | POINTE-CLAIRE | | **Locality** | POINT-CLAIRE | | **AdministrativeArea** | QC | | **PostalCodePrimary** | H9R4R6 | #### Example 3 **Input address:** `GD STN MAIN PARKSVILLE BC V9P2G2` **Result Codes:** | Field | Output | | - | - | | **SerpStatusEx** | V | | **Questionable** | Empty | **Components:** | Address Field | Output | | - | - | | **GeneralDelivery** | GD | | **DeliveryInstallationType** | STN | | **DeliveryInstallationQualifierName** | MAIN | | **Locality** | PARKSVILLE | | **AdministrativeArea** | BC | | **PostalCodePrimary** | V9P2G2 | #### Example 4 **Input address:** `RR 1 LOT 89 CONC 3 MARYSTOWN NL A0E2M0` **Result Codes:** | Field | Output | | - | - | | **SerpStatusEx** | V | | **Questionable** | Empty | **Components:** | Address Field | Output | | - | - | | **RouteType** | RR | | **RouteNumber** | 1 | | **AdditionalContent** | LOT 89 CONC | | **Locality** | MARYSTOWN | | **AdministrativeArea** | NL | | **PostalCodePrimary** | A0E2M0 | # Consuming Premium Data Sets Source: https://docs.loqate.com/location-solutions/premium-data-sets/consuming-premium-data-sets There are a series of extra datasets available via our Address Capture services. Currently we have Business Data, AddressBase Premium, AddressBase Islands and Geo+ (Loqates premium UK address dataset) available. As these datasets are covered by separate terms and agreements they will need to be activated on your account for you, please get in touch if you are interested in taking advantage of any of our premium datasets. There are a few approaches you can take in consuming these extra datasets, and which one is appropriate depends on how you want to integrate with the service. ## Direct Via the API ### Find Your extra dataset can be activated by us as a setting on the key itself. This means that the selected API key will always return data from the selected dataset. Alternatively, you can use any API key from your account and specify the dataset required via a parameter on the request. **Note:** If a premium dataset is requested using an API key from an account that does not have that dataset enabled, the request will fail. If the dataset has not been enabled on the key itself, you will need to add the datasets parameter to the Find request. The following example requests the Business dataset be used for this Find request: `https://api.addressy.com/Capture/Interactive/Find/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Text=wr5 3da&Datasets=gb_db` The Find request will then continue as normal using the Business data as its dataset. Once the user selects an address from the list you will pass the Id of that address into the retrieve request as per a normal flow. ### Retrieve Each premium dataset contains certain extra fields that are available in addition to the standard fields provided by a Retrieve request. By default, if you use an Id from a premium dataset Find request, the Retrieve will still only return the standard set of fields. In order to retrieve these special fields, you will need to supply field format strings for them into the FieldFormat Parameters of a Retrieve request. These fields are in the style of FieldXFormat, with X being the number of that field. The requested field will then be returned in the corresponding response field, FieldX. A normal field format will be in the style of `{FIELDNAME}`. For example, in order to retrieve the Company number from the Business dataset you would use the following request: `https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Id=IDFROMFIND&Field1Format={CompanyNumber}` This would return the the Company number in the returned property Field1. The Retrieve request is limited to 20 Field Format fields by default. Should you require more fields than this you will need to specify a fields property along with your field formats that will set the number of extra fields to respond with, for example: `https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Id=IDFROMFIND&Field1Format={CompanyNumber}......................&Field21Format={TelephoneNumber}&Fields=21` ## Using the JavaScript SDK If you are using our JavaScript SDK to make requests to the service, as outlined in our [advanced guide](/our-services/address-capture/sdk), you can enable premium datasets via the options object used in the construction of the control object, e.g.: ``` var options = { key: 'AA11-AA11-AA11', search: { datasets: ['gb_db'] }, advancedFields: [ '{CompanyNumber}' ] } ``` The same restrictions apply to the datasets as apply when directly integrating via API. ## Using the simple setup If you are using our simple setup wizard to install your lookup control you can specify the field formats directly in the field mapping control using the field format syntax, `{FIELDFORMAT}`. * **Business Data** * "CompanyNumber", * "TelephoneNumber", * "UK2003Code", * "SICCode", * "SICDescription", * "LineOfBusiness", * "EmployeesAtCompany", * "EmployeesAtSite", * "LocationIndicator", * "Sales", * "YearStarted", * "Executive1Function", * "Executive1FirstName", * "Executive1Surname", * "Executive1Saluation", * "Executive2Function", * "Executive2FirstName", * "Executive2Surname", * "Executive2Saluation", * "Executive3Function", * "Executive3FirstName", * "Executive3Surname", * "Executive3Saluation", * "Executive4Function", * "Executive4FirstName", * "Executive4Surname", * "Executive4Saluation", * "Executive5Function", * "Executive5FirstName", * "Executive5Surname", * "Executive5Saluation", * "Executive6Function", * "Executive6FirstName", * "Executive6Surname", * "Executive6Saluation", * "Executive7Function", * "Executive7FirstName", * "Executive7Surname", * "Executive7Saluation", * "Executive8Function", * "Executive8FirstName", * "Executive8Surname", * "Executive8Saluation", * **Geo+** * "PropertyType", * "UPRN", * "UDPRN", * "UMRRN", * "Owning\_UDPRN", * "InferredParentUPRN", * "AddressKey", * "OrganisationKey", * "DPS", * "LargeSmallUserFlag", * "SmallOrganisationFlag", * "NotYetBuiltFlag", * "Eastings", * "Northings", * "Latitude", * "Longitude", * "UPRNDerivation", * "GeoDerivation", * "LinkedUDPRNs", * "LinkedUMRRNs", * "LinkedUPRNs", # Property Intelligence Flat File for GB Source: https://docs.loqate.com/location-solutions/premium-data-sets/property-intelligence-data-directory The Property Intelligence database is designed to assist in the process of providing insurance quotes for customers in GB supplying property related metadata for residential properties. [User Guide](https://github.com/loqate/release-docs/blob/main/prop-intel-release-notes/202609%20Property%20Intelligence%20User%20Guide.pdf) The data dictionary contains details of the metadata elements provided with examples of the values provided and the % coverage. # Property Intelligence Data Dictionary Loqate Property Intelligence provides location, building, energy, risk and sale-history attributes for residential properties, with availability varying by field and geography. This page describes the fields returned in the dataset. > **Data release:** September 2026 ## How to read this page | Column | Meaning | | - | - | | **#** | Position of the field in the output file. | | **Field** | Field name exactly as it appears in the output. | | **Type** | Data type: `Integer`, `Float`, `Text` or `Lookup` (a coded value — see [Lookup fields](#lookup-fields)). | | **Description** | What the field contains and where it comes from. | | **Example** | A sample value for a single property. | | **Fill rate** | Percentage of records in the dataset with a populated value. | | **Coverage** | Geography the field is available for. | :::note Fill rates are indicative and are refreshed with each data release. Fields marked *England & Wales only* are not populated for properties in Scotland or Northern Ireland. ::: ## Field summary | Category | Groups | Fields | | - | - | - | | [Location](#location-fields) | Address, Postcode, Mapping, Statistical, Region | 15 | | [Property](#property-fields) | Type, Area, Rooms, Year built, Tenure, Sale History, Financial, Energy, Risk, Automotive, Planning | 39 | ## Location fields ### Address | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 1 | `UPRN` | Integer | The Unique Property Reference Number originating from the Ordnance Survey. | `100010011866` | 95.3% | UK | | 2 | `UDPRN` | Integer | The Unique Delivery Point Reference Number originating from the Royal Mail. | `4584729` | 100.0% | UK | | 3 | `UMRRN` | Integer | The Unique Multiple Residence Reference Number originating from the Royal Mail. | `0` | 100.0% | UK | | 4 | `address1` | Text | A standardised first line of address containing house name or number and street. | `30, Garth Drive` | 99.8% | UK | ### Postcode | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 5 | `postcode` | Text | A full postcode. | `CH2 2AG` | 99.8% | UK | ### Mapping | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 6 | `easting` | Float | Ordnance Survey National Grid Easting. | `340446.33` | 95.3% | UK | | 7 | `northing` | Float | Ordnance Survey National Grid Northing. | `368152.12` | 95.3% | UK | | 8 | `latitude` | Float | Latitude in ETRS89 converted from the easting/northing pair using OSTN02. | `53.2070999` | 95.3% | UK | | 9 | `longitude` | Float | Longitude in ETRS89 converted from the easting/northing pair using OSTN02. | `-2.8931134` | 95.3% | UK | ### Statistical | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 10 | `OA11CD` | Text | Census 2011 Output Area (OA) code from the ONS Postcode Directory. | `E00092698` | 99.3% | UK | | 11 | `LSOA11CD` | Text | Census 2011 Lower Super Output Area (LSOA) code from the ONS Postcode Directory. | `E01018374` | 99.3% | UK | | 12 | `OA21CD` | Text | Census 2021 Output Area (OA) code from the ONS Postcode Directory. | `E00092698` | 99.3% | UK | | 13 | `LSOA21CD` | Text | Census 2021 Lower Super Output Area (LSOA) code from the ONS Postcode Directory. | `E01018374` | 99.3% | UK | ### Region | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 14 | `country` | Text | One of England, Northern Ireland, Scotland, or Wales from the ONS Postcode Directory. | `England` | 99.3% | UK | | 44 | `congestion_zone` | Lookup | A flag indicating if a property is in the London Congestion Zone. | `0` | 0.4% | UK | ## Property fields ### Type | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 42 | `business_usage` | Lookup | A flag indicating potential business usage. | `0` | 8.3% | UK | | 54 | `is_multires` | Text | A flag to identify properties that are multi-residential. | `0` | 99.8% | UK | ### Area | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 15 | `property_type` | Lookup | Whether the property is semi-detached, detached, terraced or a flat. | `1` | 88.6% | UK | | 16 | `floors` | Text | The estimated number of floors in the property based on the height of the building. | `2` | 74.9% | UK | | 23 | `cadastral` | Text | The area of the cadastral parcel in which the building sits expressed in square metres using data from Land Registry. | `401.3` | 83.7% | England & Wales only | | 24 | `height` | Text | The building height in metres. | `7.09` | 57.5% | UK | | 25 | `footprint` | Text | The approximate footprint of the building expressed in square metres. | `76.5` | 57.5% | UK | | 26 | `volume` | Text | The approximate volume of the building expressed in cubic metres. | `386.66` | 57.5% | UK | | 27 | `avg_roof_slope` | Text | The average slope of the property roof, can be used to identify properties with flat roofs. | `0.81` | 57.5% | UK | | 28 | `flat_roof_fraction` | Text | The estimated fraction of a building which has a flat roof. | `0.16` | 56.1% | UK | | 29 | `distance_to_tree` | Text | Distance from the nearest tree over 10 metres tall to the property geocode. | `47.51` | 57.5% | UK | | 30 | `geocode_multiplicity` | Text | The number of property geocodes falling within the footprint of the building at 1.8 metres above ground level. | `2` | 57.5% | UK | | 31 | `floor_area` | Text | The liveable floor area in square metres. | `0` | 65.3% | UK | | 46 | `flat_floor` | Text | Storey on which a flat sits. This typically contains N/A where it is not available or applicable or a number which may have been derived from a model based on the text found in the original data source. | — | 0.6% | England & Wales only | | 47 | `top_floor_flat` | Lookup | Is a flat on the top floor of the building. | `0` | 16.4% | England & Wales only | | 48 | `extensions` | Text | The number of extensions to a property, typically 1 but up to 4. | `0` | 55.1% | UK | ### Rooms | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 17 | `bedrooms` | Text | The number of bedrooms in a property. | `3` | 84.7% | UK | | 18 | `bathrooms` | Text | The number of bathrooms in a property. | `1` | 39.2% | UK | | 19 | `total_rooms` | Text | The number of rooms excluding bathrooms and kitchens. | `6` | 60.3% | UK | ### Year built | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 20 | `age` | Lookup | The construction date of a building in one of the following periods: (before 1719 (old), 1720-1839 (Georgian), 1840-1919 (Victorian/Edwardian), 1920-1945 (Inter-war), 1946-1979 (Post-war) and 1980 to date (Modern)). | `3` | 60.3% | UK | | 21 | `year_built` | Text | The year built, only available for those buildings in the Land Registry Price Paid data, built after 1995. | `0` | 10.4% | UK | ### Tenure | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 22 | `listed` | Lookup | The grade of listing of a building, if it is listed, using data supplied by English Heritage, Cadw or Historic Scotland. | `0` | 1.6% | UK | | 51 | `tenure` | Lookup | Type of tenure: owner-occupier, rented or social housing. | `0` | 35.9% | UK | ### Sale History | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 32 | `last_transaction_price` | Text | The price paid at the last transaction recorded by the Land Registry (England and Wales only, back to 1995). | `225000` | 48.4% | England & Wales only | | 33 | `last_transaction_date` | Text | The date of the last transaction recorded by the Land Registry (England and Wales only, back to 1995). | `2004-08-01` | 48.4% | England & Wales only | | 34 | `last_transaction_duration_type` | Lookup | The duration type of the last transaction recorded by the Land Registry (England and Wales only, back to 1995). | `1` | 48.4% | England & Wales only | | 35 | `est_current_value` | Text | Estimated current value based on data from Land Registry (England and Wales only, back to 1995). | `416133` | 45.3% | England & Wales only | | 36 | `n_transactions` | Text | The number of transactions recorded by the Land Registry (England and Wales only, back to 1995). | `2` | 48.4% | England & Wales only | ### Financial | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 37 | `est_council_tax` | Lookup | Estimated council tax from price at reference years using Land Registry data (England and Wales only, back to 1995). | `3` | 82.1% | UK | ### Energy | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 49 | `wall_type` | Lookup | The type of wall used in construction, possible values cavity wall, solid brick, sandstone, granite, timber frame, system built and SAP05. | `0` | 63.3% | UK | | 50 | `main_fuel` | Lookup | Main central heating fuel, possible values include gas, electricity, oil, coal, LPG, wood, B30K (a biofuel mix) and also 'not known' and 'none'. | `0` | 64.8% | UK | | 52 | `energy_rating` | Lookup | Energy rating as indicated in the EPC Energy Certificate. | `3` | 63.3% | UK | | 53 | `epc_inspection_date` | Text | Inspection date indicated in the EPC Energy Certificate. | `1` | 65.3% | UK | ### Risk | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 38 | `watercourse_200M` | Lookup | Flag indicating whether there is a watercourse within 200 metres. | `0` | 100.0% | UK | | 39 | `distance_to_water` | Text | Distance (in metres) to a watercourse, if it is within 200 metres. | `0` | 16.6% | UK | | 45 | `burglary_rate` | Text | The number of burglaries per property per year averaged over a LSOA (England and Wales only). | `0.0068` | 99.3% | England & Wales only | ### Automotive | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 40 | `distance_to_road` | Text | The distance to the centre line of the nearest road from the property geocode, not necessarily accessible. | `16` | 95.3% | UK | | 41 | `road_class` | Lookup | Road class, as provided by Ordnance Survey. | `0` | 95.3% | UK | ### Planning | # | Field | Type | Description | Example | Fill rate | Coverage | | - | - | - | - | - | - | - | | 43 | `planning_classification` | Lookup | Planning classification as per Town and Country Planning (Use Classes) Order 1987 for non-domestic properties. | `0` | 2.3% | UK | ## Lookup fields The following fields return a numeric code rather than a descriptive value. Contact your Loqate account manager for the full code lists. `property_type`, `age`, `listed`, `last_transaction_duration_type`, `est_council_tax`, `watercourse_200M`, `road_class`, `business_usage`, `planning_classification`, `congestion_zone`, `top_floor_flat`, `wall_type`, `main_fuel`, `tenure`, `energy_rating` ## Data sources Property Intelligence is compiled from authoritative UK sources including Ordnance Survey, Royal Mail, the ONS Postcode Directory, HM Land Registry Price Paid data, EPC (Energy Performance Certificate) records, and Historic England, Cadw and Historic Environment Scotland listings. # Loqate Utilities Register Provides UK Meter Point Data Source: https://docs.loqate.com/location-solutions/utilities-register/loqate-utilities-register UK meter point data for gas and electricity suppliers. Retrieve MPxN information, REL details, and switching data by address. The Utilities Register (UR) is a web service providing access to a property’s address and meter-point data needed to provide consumers with tariff estimates and for energy suppliers to execute a switch through the Central Switching Service or CSS. > [!NOTE] > > **Last updated: September 2025.** Market-wide Half Hourly Settlement (MHHS) enabled electricity supply points will commence rollout across the country from September 2025. > In line with this, the Utilities Register provides MHHS-related attributes for all electricity meter points, and these will become populated with data as and when these > meters are enabled for MHHS over the course of the next 18 months or so. The Utilities Register provides you with the ability to add address and MPxN searching into your websites and server-side applications. The service returns both gas and electricity supply point data from a single request. Making use of Gas and Electricity Enquiry Services (GES and EES) provided by the Retail Energy Code Company (RECCo), the Utilities Register provides you with accurate data that’s updated by the industry on a daily basis. The Utilities Register can be used to retrieve meter point and other information for a specific address. Where a complete address is not immediately available or the implementation benefits from interactive address input, the service can also be used for the purposes of postcode or partial address lookup, retrieving meter point information with a follow up request in this instance. Additionally, GBG’s service benefits from being able to verify and standardise unformatted or ‘free-format’ address strings into structured addresses, providing a far higher chance of a successful match when searching the GES and EES. This can be useful where a user is not present to select or validate an address. For example, when an energy supplier receives uploads of hundreds or thousands of addresses from Price Comparison Websites and brokers. Critically, the Utilities Register also returns the Retail Energy Location (REL) details, required to execute a switch within the CSS. > [!NOTE] > > **Note:** Loqate's Utilities Register is only available to UK customers. This guide is only relevant to customers who have set up Utilities Register with their account manager. If you haven't set up the service yet, please contact your account manager before accessing this guide. [Download the guide](https://www.loqate.com/media/siekgpgr/loqate-utilities-register-user-guide-v3.pdf) # We're Upgrading Your GBG Loqate Account Source: https://docs.loqate.com/loqate-basics/account-migration At GBG Loqate, we're committed to providing the best possible user experience for our customers. As part of our ongoing efforts to improve usability, we're introducing enhanced user management features within our SaaS platform. ![User Migration Message](https://mintcdn.com/loqate/fSj5oxczvcI2RUMZ/images/notifications/Screenshot-migration.png?fit=max\&auto=format\&n=fSj5oxczvcI2RUMZ\&q=85\&s=6e1faa06eb426fe9b9bd129c2497f17e) ## Why We're Making These Changes? We've moved to a new authentication system that unlocks several benefits, including improved diagnostics and enhanced security features soon to be implemented such as multi-factor authentication (MFA) and passkeys. One of the most frequently requested improvements is the ability for organisations to have multiple users on the same account. This allows teams to collaborate more effectively without relying on a single shared login. New customers already have access to this functionality, and we're now rolling it out to our existing users. ![User Management](https://mintcdn.com/loqate/fSj5oxczvcI2RUMZ/images/notifications/Screenshot-user-mang.png?fit=max\&auto=format\&n=fSj5oxczvcI2RUMZ\&q=85\&s=99ed0cb23b1e84483754a40eac80539b) ## What Changes Will You See? When you next log in, you'll see an invitation to upgrade your account. Simply follow the on screen instructions to create a new account using your existing credentials. All your current settings and data will be transferred automatically. After upgrading, you'll be able to invite additional users to your organisation and manage access more easily. Simply click on your company name in the top right corner of our account section and select “Your Team”. From here you will be able to add and remove users to your organisation. If you experience any issues, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/), or reach out to us on [Slack](https://join.slack.com/t/loqate-workspace/shared_invite/zt-2xhkfmb38-3iIhtlRGO88k6dub4F4qzQ) for any questions. ![User Details](https://mintcdn.com/loqate/fSj5oxczvcI2RUMZ/images/notifications/Screenshot-details.png?fit=max\&auto=format\&n=fSj5oxczvcI2RUMZ\&q=85\&s=cbbca27b789a0a3100451d05c1c82964) ## Frequently Asked Questions > [accordion] When can I upgrade my account? > > You should see an invitation when you log in. If you don't see the invitation, please contact support. > [accordion] If I skip the invitation, can I upgrade later? > > Yes. The invitation will continue to appear each time you log in with the same credentials until the full upgrade rollout is completed. > [accordion] What is the difference between an Admin and a Member? > > Admins can invite or remove users. Members can access the platform but cannot manage users. All other functionality is the same. > [accordion] What is the difference between a Contact and a User? > > A **User** is someone who can log in to your Loqate Account. A **Contact** is simply an email address we use to send important account‑related information. > > Your Loqate Account has always included *contacts*—these are used for notifications such as balance alerts, security alerts, invoices, and receipts. > > *Users*, on the other hand, have login access to your Loqate Account and are managed in the **Organisation** area. You can find this by clicking your company name in the top‑right corner of the account screen and selecting **“Your Team”**. > [accordion] How do I log in once my account is converted? > > You will continue to use the same [login page](https://auth.loqate.com/en/sign-in), however, after your account is converted, you must log in using your **email address**, not your Account Code and Password. > > If you attempt to log in using the old Account Code and Password combination, it will no longer work. > [accordion] I have more than one account to migrate. How can I do it? > > After you have migrated one of your accounts, the **Switch Organisation** page will appear. This page lists the other organisations that you can migrate to our new system. > > In the top‑right corner, you will find a button to **log out** of the current account. > > After selecting this option, you will be able to log in and migrate your other accounts. If any of those accounts have not yet been migrated, see [Legacy Sign-In](/loqate-basics/legacy-login) for instructions on how to access them. > [accordion] Why can’t I log in? > > **Are you trying to log in with an Account Code?** > > Once your account is converted, the Account Code and Password combination is disabled. You must log in using your **email address**. > > **Have you been added to the Organisation?** > > If your email address hasn’t been invited to the Organisation, you won’t be able to log in.\ > Please contact the person who converted the account and ask them to confirm that you appear in the **Organisation** area (found by clicking your company name in the top‑right corner of the account screen and selecting **"Your Team"**). > > **Are you trying to log in with the email address of a "Contact" on your Account?** > > See the FAQ titled **"What is the difference between a Contact and a User?"** above. > > **Can’t switch to an organisation?** > > Maybe you are a member of an account that hasn't been migrated to the new system. > > A tooltip will appear with some information that will tell you the current status so you can contact the Admin of that organisation to migrate it or invite you. If you need to sign in to an unmigrated account directly, see [Legacy Sign-In](/loqate-basics/legacy-login). > > If you are still having problems logging in, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/) who will be happy to help. # AI Agent Docs Integration Source: https://docs.loqate.com/loqate-basics/ai-agent-integration Learn how to integrate AI agents with Loqate documentation using llms.txt, Skills or MCP. > [!TIP] > > **🤖 New: Reach — Loqate for Agents** > Building agentic workflows? Reach verifies addresses, emails, and phone numbers in real time — returning a confidence score, a policy-aware recommendation, and a full audit trail in one command. > > [Explore Reach](https://agents.gbg.com/reach.html) Loqate publishes machine-readable documentation metadata that allows AI agents and developer tools to understand Loqate capabilities programmatically. These integration points can be used by agent frameworks, MCP-compatible tools, IDE extensions, or custom automation. ## Available integration options Depending on your tooling and integration model, use one or more of the following options. ### The `llms.txt` file The `llms.txt` file is a structured documentation index. It lists all the available documentation pages so agents can discover relevant content before answering questions. See the `llms.txt` file at: ```url theme={null} https://docs.loqate.com/llms.txt ``` ### Skills CLI The Skills CLI is a command-line tool that allows you to query the documentation and retrieve relevant information programmatically. If your agent supports the [Skills CLI](https://www.npmjs.com/package/skills), then you can install the skill using: ```bash theme={null} npx skills add https://docs.loqate.com/ ``` During the installation, you'll be prompted to select an agent to install the skill for. Select the agent you want to integrate with Loqate documentation. If you don't see your agent listed, use the Search option to find it. This command loads the Loqate documentation into the agent's context. Start with a query like: ```bash theme={null} based on the loqate .claude skill what is Loqate? ``` ### MCP When an AI application connects to the Loqate documentation Model Context Protocol (MCP) server, it can search the documentation and retrieve full page content directly, in response to your prompts. Instead of relying on information from its training data or making a generic web search, your MCP server provides access to all indexed content on the documentation site. Loqate exposes its documentation through a remote MCP server. This enables MCP-compatible clients to query the documentation dynamically. To connect, register the following URL as a remote MCP server in your client configuration: ``` https://docs.loqate.com/mcp ``` #### MCP tools Your MCP server provides two tools that AI applications can use: * **Search**: Searches across the Loqate documentation to find relevant content, returning snippets with titles and links. Use this when you need to discover information or find pages matching a query. * **Get page**: Retrieves the full content of a specific documentation page by its path. Use this when you already know the page path, such as from search results, and need the complete content rather than a snippet. AI applications determine when to use each tool based on the context of the conversation. For example, an AI application might first search your documentation to find relevant pages, then use the get page tool to retrieve the full content of the most relevant result. #### Use MCP server The Loqate documentation provides different options for using the MCP server: > [tab] Claude > > Add the Loqate MCP server to Claude: > > 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. > 2. Select **Add custom connector**. > 3. Add the Loqate MCP server: > * **Name**: Loqate Docs > * **URL**: `https://docs.loqate.com/mcp` > 4. Click **Add**. > > Access the MCP server in your chat: > > 1. When using Claude, click the attachments button (the plus icon). > 2. Navigate to **Connectors**, you'll see the Loqate docs MCP connector you just added automatically enabled. > 3. Ask Claude a question about Loqate. > [tab] Claude Code > > To use the Loqate MCP server with Claude Code, run the following command: > > ```bash theme={null} > claude mcp add --transport http loqate-docs https://docs.loqate.com/mcp > ``` > > Test the connection by running: > > ```bash theme={null} > claude mcp list > ``` > [tab] Cursor > > To connect the Loqate MCP server to Cursor, follow these steps: > > **1. Open MCP settings** > > 1. Use `Command` + `Shift` + `P` (`Ctrl` + `Shift` + `P` on Windows) to open the command palette. > 2. Search for "Open MCP settings". > 3. Select **Add custom MCP**. This opens the `mcp.json` file. > > **2. Configure the Loqate MCP server** > > In `mcp.json`, add: > > ```json theme={null} > { > "mcpServers": { > "loqate-docs": { > "url": "https://docs.loqate.com/mcp" > } > } > } > ``` > > **3. Test the connection** > > In Cursor's chat, ask "What tools do you have available?" Cursor should show the Loqate MCP server as an available tool. > [tab] VS Code > > To connect the Loqate MCP server to VS Code, create a `.vscode/mcp.json` file and add: > > ```json theme={null} > { > "servers": { > "loqate-docs": { > "type": "http", > "url": "https://docs.loqate.com/mcp" > } > } > } > ``` # Loqate API Security: Best Practices and Configuration Source: https://docs.loqate.com/loqate-basics/api-security Configure security options for Loqate API keys. Restrict by service, limit by IP or URL, and choose between client-side and server-side integration. ## Integration options There are two ways of integrating with [Loqate's APIs](/api-reference/introduction/) - client-side and server-side - and it's worth considering the security implications of both when you're deciding how to integrate. Both options provide access to the same services, and only require an API key. * In a **client-side** integration all of the processing for an API in completed via a browser, on the end-user's device * In a **server-side** integration all of the processing for an API is completed on a web server A **server-side** integration is recommended to ensure the highest level of security, but the following sections explore the security implications of both options. ### Client-side integrations Client-side integrations are quick and easy to set up, and don't requite a large amount of technical expertise, so they give you the ability to get up and running without too much time or effort. The downside to this approach, however, is that it doesn't allow you to implement any of your own monitoring, which means you have less control over and visibility on the journey your customers go on. From a security perspective they are also more vulnerable than server-side integrations, as they don't hide your API keys, which means your keys are visible to anyone viewing the source code of your website. The previously-discussed security measures are in place to help, including allow-listing features that let you specify which domains and IP addresses can use your API keys, but if you're a high-profile business, a server-side integration is recommended. If you do decide to use a client-side integration, make sure you use the available measures to be as secure as you can. For instance, use the key-specific limits/restrictions mentioned earlier to lock your API keys down as much as possible. ### Server-side integrations Server-side integrations require more technical expertise and resources to set up, but offer you a greater degree of control over the user experience. Using this approach you have complete control over your monitoring, in terms of what your users are requesting and what they see in response. This approach is also typically more secure, as it won't make any of your API keys visible, and as such this is always recommended as the best option. No API integration is invulnerable however, so using as many of the provided security options as possible is still recommended even with a server-side integration. ## Security options Loqate provides you with various security options, some of which can be applied across your whole account (and will therefore apply regardless of which services you're using) and others that can be applied to individual API keys (and therefore individual services). Applying as many of these as possible is recommended. ## Securing your account There are several features available to you in the [Security section of your account](https://account.loqate.com/account#/Security), that apply across the whole of your account. Some of these features are more or less suitable depending on the type of integration you use, whether it's client-side or server-side. For each one there's a note regarding which integration type it's most suited to. ### Restrict IP addresses > [!NOTE] > > This tool is most suited to server-side integrations. Use this feature to block one or more specific IP addresses, and ensure that they can't access any of your Loqate services. ![BlockedIPs](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/api-security/blocked-ips-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=823531067e816d9b9bafcdfa84967fce) If someone then tries to access one of your services via a restricted IP address, you'll receive an email notification which contains details of the error that was generated, as well as information about which service was affected, what the source IP was, etc. Here's an example: ![AccountError](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/api-security/account-error.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=1f79ee54d6a5c8efd60b9cafdf53c6a6) ### Account password Make sure you use a strong password to prevent unauthorised access to your Loqate account. ![AccountPassword](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/api-security/password-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=6673fd413370e50d89e7948c0533c851) ## Securing your API keys All Loqate services authenticate your requests using the API key relevant to that request or service. In order to ensure your keys' security, it's recommended that you: * Restrict your keys to specific services (strongly recommended) * Limit your keys by URLs or IP addresses * Don't embed your keys anywhere that they could be extracted from You can restrict and/or limit any key in the [Your Services page of the Account section](https://account.loqate.com/account#/Dashboard/). Select the key you want to edit, then click on the **Limits** tab where you'll see these options: ![APILimits](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/api-security/limits-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=2cb6086edd2edc88aaa6ce9a5bd7bc39) ### Limit by URL > [!NOTE] > > This tool is suitable for both client-side and server-side integrations. To help prevent fraudulent or accidental use of one of your keys across domains, add the URLs that you expect the requests to be coming from. Enter a URL address you wish to limit in the text box and then click the plus icon. You can add as many URLs as you like. You will also need to specify any subdomains and combinations of URLs that might be used. i.e. `http://www.mysite.co.uk`, `http://www.mysite.com`, `https://mysite.co.uk`, etc. ### Limit by IP > [!NOTE] > > This tool is most suited to client-side integrations. Similar to the Daily Limit, this allows you to place request limits against a group of IP addresses, which should help manage your cashflow and cap individual usage. Enter an IP address you wish to limit in the text box and then click the plus icon. You can add as many IP addresses as you like. ### Limit by Service > [!NOTE] > > This tool is suitable for both client-side and server-side integrations. Making use of this option is strongly recommended, as it allows you to restrict each API key to one or more Loqate services, rather than allowing each key to be used for any service. The default value for this option is blank, in which case that key can be used for any Loqate service. You can select more than one service to limit an API key to, for example if you use the same key for Address, Email and Phone Validation. ![LimitByService](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/api-security/limit-by-service-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=cc9ae491baac639673d766e08eded956) Each of those values represents a set of Loqate services. Here's how they're broken down: * Address Capture * [Capture Find](/api-reference/address-capture/find) * [Capture Retrieve](/api-reference/address-capture/retrieve) * [Geolocation](/api-reference/address-capture/geolocation) * Legacy Capture products * Address Verify * [Verify (International Batch Cleanse)](/api-reference/address-verify/international-batch-cleanse) * Legacy Verify products including AddressCleansing, CleansePlus/Batch, CleansePlus/Interactive and Cleansing/International * [Bank Validation](/our-services/bank-validation/overview/) * All Bank Validation APIs * [Email Validation](/our-services/email-validation/overview/) * All Email Validation APIs * [Phone Validation](/our-services/phone-validation/overview/) * All Phone Validation APIs * Geocode * DistancesAndDirections * [Distance](/api-reference/geocode/distances-and-directions/distance) * [Directions](/api-reference/geocode/distances-and-directions/directions) * [Geocoding](/api-reference/geocode/geocoding/apis) * All Geocoding APIs * StoreFinder * [Find](/api-reference/geocode/store-finder/findplacenames) * [Retrieve](/api-reference/geocode/store-finder/retrievecoordinates) * All GovernmentData APIs * Legacy * A variety of legacy products including PostcodeAnywhereNorthAmerica, PostcodeAnywhereInternational and PostcodeAnywhere/Interactive This list includes all currently-supported Loqate products. If you can't see a product you're using on this list, it's likely a legacy product and will be included either under Capture or Verify (if it's an older version of them) or the specific Legacy option. Please check with the Loqate Support team if you'd like to clarify which option to choose. **NOTE:** if you created an Address Verification service via your Account section (i.e. following the instructions in the [Tag Setup Guide](/our-services/tag-setup-guide)), choose the Address Capture option rather than Address Verification (as this refers to the Verify product instead). > [!NOTE] > > Whichever approach you take to integrating with Loqate, make sure you consider the security implications and take steps to ensuring the security of your site. \ > \ > If you have any further questions about API security, please get in touch with the [Loqate support team](https://www.loqate.com/en-gb/contact/customer-support/). # Developer Blog Source: https://docs.loqate.com/loqate-basics/blog # Create an API Key Source: https://docs.loqate.com/loqate-basics/create-an-api-key Step-by-step guide to creating and configuring Loqate API keys. Set up authentication, configure service limits, and test your first API request. **All Loqate services require a valid and active API key for authentication.** ## Prerequisites You need a valid Loqate account. [Sign up for a free trial](https://account.loqate.com/register/) to get started. ## Steps 1. Navigate to the **Setup** page in the Loqate Account section by clicking the **Add service +** button from the left-hand menu. 2. Select the **API Key** option to create a generic API key. 3. You'll be taken to the **Service Settings** page for your new key. Click **Save** to activate it. 4. Copy and save your API key immediately. You'll need it to authenticate all API requests. ## Using Your API Key > [!NOTE] > > **Loqate Core SDKs are now in Early Access (Beta)** — our new TypeScript and .NET SDKs are available to try today.\ > They're stable, generated from our live API definitions, and form the first stage of our developer-tools refresh.\ > We'd love your feedback as we continue to expand them. > > See the [SDK Overview](/sdks/overview) for details. Include your API key in the `Key` parameter of your requests: ```http theme={null} https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws?Key=YOUR-API-KEY&Text=search ``` Replace `YOUR-API-KEY` with your actual key. ## Service Settings Configure your key in the Service Settings page: * **Configuration:** Edit the key name, toggle between active/inactive, or set to internal use only * **Limits:** Set daily lookup limits and restrict the key to specific URLs, IPs, and/or services For detailed security options, see the [API Security](https://docs.loqate.com/loqate-basics/api-security) page. Generic API keys can enable additional datasets for expanded coverage. ## Try It Out Test your API key with the [Address Capture Find Playground](/api-reference/address-capture/find?playground=open) to make your first request. # Frequently Asked Questions Source: https://docs.loqate.com/loqate-basics/faq Answers to common Loqate questions: API key errors, account limits, Tag setup, security settings, and troubleshooting. ## Account Troubleshooting Questions > [accordion] Why do I get the error 'License key is no longer valid, it may have expired'? > > This error is generated whenever you try and do a lookup using a key that has been deleted, or has expired. Licence keys can be deleted through your account online; if you do this by mistake you’ll need to contact us to get them reinstated. With annual user licences available for the Royal Mail's Postcode Address File (PAF®) data, this error will be displayed if you have not renewed and the licence has expired; again please contact us. > [accordion] What does the error 'The licence key has reached its daily limit, please check your settings or wait until tomorrow' mean? > > Each per-click licence key has a setting that dictates the total credit it can consume from the account on a single calendar day. This is a security setting to help protect your credit from being consumed too quickly. It can be changed within the edit wizard of the licence key in question. If you are using a user licence key then the daily limit will be set at the time of purchase, in accordance with our fair usage policy. > [accordion] What does the error 'This license key cannot be used from this website, the security settings for the license key may not include this domain' mean? > > Within your key settings you have the option to limit our service to only accept requests on that key that are coming from specified website addresses. This is a security feature to prevent your key from being used anywhere other than the site you intended. If you set this up and get this error message please check the URL is formatted correctly and is available. The website address will be detailed in the table in the email. > [accordion] Why do I have the error 'Your credit has run out'? > > This means your account has run out of credit. An error message email will be generated when a user tries to do a lookup. The error will usually show the IP, or URL where the request originated and details of the service that was used. To fix this, log into your account and top up with credit. > [accordion] What does the error message 'Free Service Limit Exceeded' mean? > > The Free Service Limit Exceeded error occurs automatically when there are a significantly higher number of uncharged requests in comparison to charged. For example, when using the address validation service, a find (free) request should usually be followed by a retrieve (charged) request. This error is highlighting an imbalance in free and charged calls to the service. Check the usage on your account under Menu > Reporting to see if the service has been installed correctly. If the calls to the service are dramatically imbalanced please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) with our Support team. > [accordion] What does the error message 'Request not allowed from this URL' mean? > > Each of our services can have its own security settings. One of these is an allowed URL list, which restricts your service for use on specific web pages. This error message is highlighting that the security you have in place on your account is working as it should by blocking off any unknown URLs from accessing your service. > > The URL in question can be found in the ‘Additional information’ section of the error message. > > * If you recognise the URL you might like to add it to your list of allowed URLs. > * If you do not recognise the URL you can ignore this message with the understanding that your security settings are working as intended. > * Blank source URL? Blank URLs can be caused due to a number of reasons. This can be caused by internal coding, how the service is being used or (most commonly) by pop-up blockers used by customers which can occasionally remove the URL from the request. We block these URLs too because we can’t be certain of the source. > > You can find these settings in your account under the security tab for each key. > [accordion] Why do I get the error 'Request not allowed from this IP'? > > In your account, there are a number of optional security settings, one of these being an ‘allowed IP list’. This error has occurred due to a request coming through to us from an IP not currently on this list. The IPs in question can be found in the “Additional information” section of your error message. If you recognise the IP address then you can add it to your list of allowed IPs. You can add IPs under 'Limit by IP' in your account; you'll find this under Menu > Your Services > Select the specific Key and select 'Limits'. > [accordion] What is the account error 'Surge protector triggered'? > > The surge protector detects when there is a notable or out of average surge in account usage. This protects against spam attacks, problems with code looping requests but above all will protect the account credit from being drained. An alert is automatically sent out when the surge protector is triggered and the service is disabled. > > This setting is commonly triggered when you are load testing the service. While this is not a malicious act this spike in requests will knock out the accounts average usage. We recommend to turn off the surge protector while testing and turning it back on when the testing is completed. > > If you know what triggered the surge, such testing or an unusually busy period, or have fixed the issue, and you'd like to activate your account again, please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) with our Support team. > [accordion] What does the error 'Unknown Key' mean? > > This error occurs when the key submitted is malformed or incorrect. Keys should be in the format AA11-AA11-AA11-AA11 when submitted and should match one of the keys in your account. Please make sure that the key you are using in your request is correct. > [accordion] Why is a 'Management Key' required? > > Certain services within the ‘Management’ family of services require a ‘Management key’ to use. These can only be created by the support team at Loqate. If you believe you require a management key please [contact our Support team](https://www.loqate.com/en-gb/contact/customer-support/#form) directly and they would be more than happy to help. ## Payment Questions > [accordion] What has changed in the payment flow? > > The user-facing payment flow has not changed. Behind the scenes, we have moved to Stripe as our payment supplier to improve reliability and security. This also gives us better visibility into payment activity, helping us diagnose and resolve payment issues more quickly. If you need help with a specific checkout journey, please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) with our Support team. > [accordion] Why do I need to accept new terms to make a payment? > > To complete a payment, you need to accept the new Stripe terms. This ensures your purchase is processed against the latest applicable terms for the updated payment service. If you are unsure which terms apply to your account, please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) and we can confirm this for you. > [accordion] Why do I need to supply my company address to add a card or make a purchase? > > You need to provide your company address when adding a card or making a purchase so we can complete billing and compliance checks. It also helps ensure invoices and account records are accurate and up to date. If you are not sure what address details to provide, please [contact our Support team](https://www.loqate.com/en-gb/contact/customer-support/#form). > [accordion] What happens if I don't have enough credit to cover an entire batch request? > > If your account doesn't have enough credit to cover the full cost of a batch request, you'll receive an 'Account out of credit' or 'Not enough credit for request' error and no results will be returned. To run the batch, top up your credit to cover the full cost before resubmitting; see [Common errors](/api-reference/common-errors). ## Common Integration Questions ## Tag integrations > [accordion] Can I add the Loqate Tag to my website using Google Tag Manager? > > Yes, this is a great way to get the Loqate Tag working on your website quickly and easily. > > If you are unfamiliar with Google Tag Manager, begin by reading [About Google Tag Manager](https://support.google.com/tagmanager/answer/2574305). To add the Loqate Tag to your container in Google Tag Manager: > > * Click ‘Add a new tag’ > * Select ‘Custom HTML Tag’ > * Enter Loqate as the Tag name and paste the Loqate Tag code into the HTML field > * Select ‘Continue’ and then ‘Fire On’ > ‘All pages’ to ensure the Loqate Tag loads on all pages of your website. > * Click ‘Create Tag’ then ‘Publish’ at the top right corner. > > Your Loqate Tag is now installed on your website and you are ready to continue setting up Loqate services, eg: Capture. > [accordion] Can I set up the Loqate Tag on a website that’s not Live/online? > > Yes, you will need to use a program to host the website locally, such as IIS (Windows) or Apache (Mac/Windows). You will need to create a new site in your hosting programme, and then map it to the file or folder containing the pages you want to set the Tag up on. In the site bindings set the port to 80, then run the website, the URL should look something like this: [http://localhost/](http://localhost/) (this is the URL you will need to enter during our Tag setup process). > [accordion] How do I add the Loqate Tag to my website? > > There are two ways to add the Loqate Tag to your website: > > * Add the Loqate Tag to your website using a Tag Manager such as Google Tag Manager > * Add the Loqate Tag directly into the HTML of every page of your website. This is the easiest method, especially if you do not already use a tag manager. > [accordion] What can I do if the setup process can’t find the Loqate Tag on my site? > > Firstly, check that we are looking at the right website - are there any typos in the website address that you entered? Secondly, did you paste the Loqate Tag code in the right place - save and re-upload your webpages to make sure. Finally, it’s possible your website is cached which means we can’t yet retrieve the updated files that contain the Loqate Tag - see the 'What can I do if my website is cached?' question below for help with this. ## General integrations > [accordion] How do I set up Loqate services in an app or intranet page? > > If you’re not setting up the Loqate Tag on a website, you can use the Loqate API to implement our services in any application. > [accordion] What can I do if my website is cached? > > If your website is not showing recent updates you made then it may need its cache cleared. If you host your own site then speak to your technical team for help. If you do not host your own site then you might need to contact the support team at your hosting provider, or inspect your admin tools for an option to clear the site cache. Sometimes the cache will clear automatically after an hour or so, it’s worth checking again later if you have this problem. > [accordion] My account credentials are visible in my website source code - is this safe? > > Your account details can be restricted to your specific URL in fact we recommend you do this. This means that even with code types where your details are visible, they are still safe and secure. Anyone attempting to use them from another site would have their requests rejected and you’d be alerted via email. > [accordion] I'm getting an Invalid ID error when using the Retrieve service - what does this mean? > > The 1001 ID Invalid error message indicates that you are passing the wrong type of ID into the Retrieve service. You should only pass an ID from the Find service where the Type was returned as "Address". Passing IDs of type "Postcode" will not result in a retrieve - instead, these should be passed back into the Find service as "Container" until an "Address" type is returned. > > ### Address API example > > First, use the Find method, triggering a lookup after each user keystroke in a search box. > > Example request: `https://api.addressy.com/Capture/Interactive/Find/1/json.ws?key=AA11-AA11-AA11-AA11&Text=wr2&Container=&Origin=&Limit=&Language=&Countries=` > > Present the Text/Description portion of the response to the user, usually in a container that allows them to click on a desired result. When the user clicks an item, check the "Type" portion of the item: > > * If the Type parameter is anything but "Address", perform another Find putting the Id into the Container parameter. Maintain the Container parameter until another click is made. Note the Type parameter will only be "Address" when it is a full address the user is selecting, otherwise they need to carry on narrowing down their search results by either typing more or clicking a further item from the results. Example subsequent Find: `https://api.addressy.com/Capture/Interactive/Find/1/json.ws?key=AA11-AA11-AA11-AA11&Text=wr2&Method=Match&Container=GB|RM|A|P-WR2-4AA&Origin=&Limit=&Language=&Countries=` > * If the Type parameter is "Address" then perform a Retrieve using the Id for that item from the response. Example Retrieve: `https://api.addressy.com/Capture/Interactive/Retrieve/1/json.ws?key=AA11-AA11-AA11-AA11&Id=GBR%7C52509479` > [accordion] Can I block specific IPs? > > Yes, there are two available methods. Our Blocked IPs setting blocks specific IPs across all of your keys and services. The list of blocked IPs can be found under Menu > Security settings. Our IP Limiter blocks all IPs that are not on your valid IP list. Only the IPs on your valid IPs list can do lookups. The list of your valid IPs can be found under Menu > Your Services > Click on the Key and 'Limits'. > [accordion] IP is blocked but not on blacklist > > If you get a message saying a certain IP is blocked but this IP is not on your blacklist then that means IP Limit is enabled. 'Limit by IP' means you can restrict the service to specific IP addresses. If the blocked IP is not on the 'Limit by IP' list it can't use the service. > > If the IP is valid, you can add it to the 'Limit by IP' list to enable access. You can find 'Limit by IP' under Menu > Your Services > Click on the specific Key and select 'Limits'. ## Contact us In case you have any other questions, please send us an [email](mailto:LoqateSupport@gbgplc.com). # Get Started with Loqate: API Integration Guide Source: https://docs.loqate.com/loqate-basics/get-started Set up your Loqate account, create an API key, and make your first API request. This guide covers API integration from account creation to testing. ## 1. Create a Loqate account [Sign up for a Loqate account](https://account.loqate.com/register/). New accounts include a 45-day free trial. ## 2. Choose an integration method You can integrate with Loqate using auto-generated code snippets placed in your website's `` tag or full API integrations. This guide focuses on API integration. For all integration options, see the [Ways to Integrate page](https://docs.loqate.com/loqate-basics/ways-to-integrate). ## 3. Create an API key All Loqate services require an API key for authentication. For initial testing, create a generic API key. Follow the steps in [Create an API Key](https://docs.loqate.com/loqate-basics/create-an-api-key). ## 4. Make a test API call Make a test call using your API key to verify it. Here's an example of an Address Capture Find call you can run in an API client or your browser. ```http theme={null} https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws?Key=AA11-AA11-AA11-AA11&Text=GBG wr53da ``` **Make sure you replace the placeholder key (AA11-AA11-AA11-AA11) with your own API key.** The example above uses text search to find addresses and places. This specific call is looking for addresses containing `GBG` and the postcode `WR5 3DA`. The response should be this: ```json theme={null} { "Items": [ { "Id": "GB|RM|B|55943629", "Type": "Address", "Text": "G B G, Waterside, Basin Road", "Highlight": "0-5;11-14,15-18", "Description": "Worcester, WR5 3DA" } ] } ``` ## 5. Check your usage Navigate to the **Reporting** page in your account to see usage summaries per key or across your account. This shows both charged and free requests and total costs. ![Usage](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/getting-started/reporting-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=25e8129247e3ef9fbe53b520b62863f6) It's recommended you regularly check usage on your keys to maintain visibility of how your services are being used. For full details, see the [Monitoring Account Usage page](https://docs.loqate.com/loqate-basics/monitoring-account-usage). # Legacy Sign-In Source: https://docs.loqate.com/loqate-basics/legacy-login How to sign in to an unmigrated Loqate account using your account code and password during the migration period. > [!NOTE] > > This page is relevant only while your account is still on the legacy authentication system. If your account has already been migrated, sign in at [https://auth.loqate.com/en/sign-in](https://auth.loqate.com/en/sign-in) with your email address. For migration information, see [Account Upgrade](/loqate-basics/account-migration). ## When to use legacy sign-in Legacy sign-in at `https://auth.loqate.com/en/legacy-sign-in` is for accounts that have not yet been migrated to the new authentication system. You need it if you see the message "Some of your accounts use legacy login" on the Switch Organisation screen. You do not need legacy sign-in if your account has been migrated. Migrated accounts use email and magic link only. ## Signing in ![Legacy sign-in form](https://mintcdn.com/loqate/6sSTppS_A9mBO4jb/images/loqate-basics/legacy-login/legacy-sign-in-form.png?fit=max\&auto=format\&n=6sSTppS_A9mBO4jb\&q=85\&s=af9f8eecebd7e8dfb10a16287b78d195) 1. **Sign out of your current account.** On the Switch Organisation screen, select the **Go to legacy sign-in** button — you will be signed out automatically and redirected to the legacy sign-in page. 2. **Sign in with your account code or contact email.** The field label on the form reads "Account code or Contact email". Enter your account code (e.g. `ABCDE12345`) or the contact email associated with the account. 3. **Enter your password and select Sign in.** After a successful sign-in you will be taken to the account upgrade flow automatically. ## Finding your account code Your account code appears in the top-right area of the Loqate account dashboard at `https://account.loqate.com`. It has the format `ABCDE12345` — five letters followed by five digits. If you have multiple accounts, each has a distinct account code. You will need to sign in separately for each unmigrated account. ## Troubleshooting ### Invalid email or account code, or password Check that the account code is entered exactly (no spaces, correct case). Check caps lock. If you have forgotten your password, select **Forgotten your password?** on the sign-in page — it links to `https://account.loqate.com/password`. Note that this password reset is for the legacy account password only, not for email-based sign-in. ### Account already migrated When a migrated account code is submitted, the form shows "Your account has been migrated to email-based sign-in." with a "Sign in with email" link. This means your account has already been upgraded — select **Sign in with email** and use your email address to access it. ### Migration not completing After signing in successfully, you should be taken to the account upgrade flow automatically. If the upgrade does not complete or you encounter an error on that page, contact the [support team](https://www.loqate.com/en-gb/contact/customer-support/). ## Migration timeline When you sign in at [https://auth.loqate.com/en/legacy-sign-in](https://auth.loqate.com/en/legacy-sign-in), you will be asked to upgrade your account if it has not yet been migrated. Follow the on-screen instructions to complete the upgrade — see [Account Upgrade](/loqate-basics/account-migration) for full details. Until your account is migrated, you can continue to access it using legacy sign-in as described above. ## After migration Once your account is migrated, sign in at [https://auth.loqate.com/en/sign-in](https://auth.loqate.com/en/sign-in) using your email address. No password is required — you will receive a sign-in link by email. You can invite additional users to your organisation from the **Your Team** section. For more information on managing your organisation, see [Managing Your Account](/loqate-basics/managing-account). ## Frequently Asked Questions > [accordion] Can I use my email address instead of my account code? > > Yes. The sign-in field accepts either your account code or the contact email address associated with the account. If your email is linked to multiple accounts, you will see a message asking you to sign in with your account code instead. > [accordion] I have more than one unmigrated account. How do I access all of them? > > Sign in and complete the upgrade for one account, then return to the [legacy sign-in page](https://auth.loqate.com/en/legacy-sign-in) to sign in with the next account code. Each account must be migrated separately. > [accordion] Where can I get more help? > > Contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/) or reach out on [Slack](https://join.slack.com/t/loqate-workspace/shared_invite/zt-2xhkfmb38-3iIhtlRGO88k6dub4F4qzQ). # List of Loqate Endpoints: All APIs by Service Category Source: https://docs.loqate.com/loqate-basics/list-of-endpoints Complete endpoint reference for Loqate APIs. Find endpoints for address capture, verification, email validation, phone validation, banking, and geocoding. Here you can find a list of all current Loqate endpoints, along with brief descriptions of what each one allows you to do. Please note that this list does not include any Legacy endpoints. ## Capture Pass address information into these endpoints - partial addresses, postcodes, geolocation data etc. - and they will output address IDs and/or address information in return. | Endpoint | Description | | :- | :- | | Find | Returns one or more addresses or containers based upon the user's input (use the address IDs generated here to pass to Retrieve) | | GeoLocation | Returns addresses within a specified radius (based on a latitude/longitude point) | | Retrieve | Returns full address details based on an address ID | | Utilities | Returns any addresses matching a specific utility code | [See the Capture documentation](/api-reference/address-capture/apis) ## Verify This endpoint provides our powerful address verification and cleanse service, including certified and enhanced datasets, geocoding and reverse geocoding, and transliteration. | Endpoint | Description | | :- | :- | | International Batch Cleanse | Returns verified, cleansed address data in batches of up to 100 international addresses | [See the Verify documentation](/api-reference/address-verify/apis) ## Store Finder These endpoints work in combination to create a Store Finder tool, allowing you to combine precise location information for your organisation's stores and a customer's location, then determine the relationship between the two sets of information, and present the results in a visual fashion. | Endpoint | Description | | :- | :- | | Create List | Creates a list of locations, including their co-ordinates and their IDs (plus additional relevant information) for use with a Store Finder | | Delete List or Point | Deletes a list of locations or a particular location within a list | | Update List or Point | Updates a list of locations or a particular location within a list | | Get List | Gets a list of locations to see the details of that list and the locations within it | | Global Geocoding | Takes an input of one or more address strings (or alternatively a postcode or locality) and returns latitude and longitudes for the given locations (can also be used for reverse geocoding) | | Global Distance Finder | Takes an input of an origin location and one or more destination locations, and returns road-based distance and travel times for each of them | | Map Tile | Takes an input of your Loqate key and returns a Signed URL that will allow you to visually represent the output from the Distance Finder API on a map | [See the Store Finder documentation](/api-reference/store-finder/store-finder-api-landing) ## Email Validation Use these endpoints to validate email addresses as they're entered using either our Tag install or API, or alternatively validate a batch of email addresses using our API. | Endpoint | Description | | :- | :- | | Batch Validate | Synchronously validates up to 100 emails per request | | Validate | Validates the existence of an individual email address | | Bulk Validate | Asynchronously validates up to 100,000 emails per request | [See the Email Validation documentation](/api-reference/email-validation/apis) ## Phone Validation Use this endpoint to validate phone numbers as they're entered using either our Tag install or API. | Endpoint | Description | | :- | :- | | Validate | Verifies whether a phone number is valid or not | [See the Phone Validation documentation](/api-reference/phone-validation/apis) ## Bank Validation These endpoints allow you to query whether UK account number and sort code combinations are valid, or check IBANs for most European countries. | Endpoint | Description | | :- | :- | | Batch Validate | Validates the bank account/sort code for batches of UK bank accounts. Returns details of the holding branch, IBAN and correct BACS account details | | RetrieveBySortcode | Returns details of any UK holding branch | | Validate | Validates the bank account/sort code for individual UK bank accounts. Returns details of the holding branch, IBAN and correct BACS account details | | International Validate | Validates whether the international bank account number for an international bank account is correct | [See the Bank Validation documentation](/api-reference/bank-validation/apis) ## Geocode These endpoints return direction and/or location information for international locations, including additional data from the Postzon database for UK addresses. | Endpoint | Description | | :- | :- | | Directions | Returns the directions between two points | | Distance | Returns the distance between two points | | International Geocode | Returns the WGS84 latitude/longitude data for a given location | | International PositionToCountry | Returns a country based on WGS84 latitude/longitude data | | International RetrieveNearestPlaces | Returns the nearest places of interest of a given category to a provided location | | International ReverseGeocode | Returns the nearest address or location to given coordinates | | UK Find | Returns locations based on the given input | | UK Geocode | Returns the OS easting + northing along with WGS84 latitude/longitude for a given postcode | | UK Retrieve | Returns the OS easting + northing along with WGS84 latitude/longitude for a given location | | UK RetrieveNearestPlaces | Returns the nearest places of interest of a given category to a provided location | | UK ReverseGeocode | Returns the nearest address or location to given coordinates | | RetrieveByCoordinates | Returns the Postzon record nearest to given coordinates | | RetrieveByPostcode | Returns the Postzon record for a given postcode | | RetrieveByPostcodeOrPlace | Returns the Postzon record for a given postcode or place name | | FindPlaceNames | Returns the names of places | | RetrieveCoordinates | Returns the coordinates of a place found using FindPlaceNames | [See the Geocode documentation](/api-reference/geocode/apis) # Managing Your Account Source: https://docs.loqate.com/loqate-basics/managing-account Manage your account, from who receives key communication to who can access your Loqate Account. > [!NOTE] > > This page and the functionality discussed assumes your account is using our updated login capability. If you have not yet migrated over and would like to know more, please see [here](https://docs.loqate.com/loqate-basics/account-migration). > > Unsure if you have migrated yet? See our FAQs at the bottom of this page. ## Terminology When a new Loqate **Account** is created (or an existing one is migrated), a corresponding **Organisation** is automatically created. The person who creates or migrates the *account* becomes the first **user** in that *Organisation* and is automatically given the **Admin** role. An *Organisation* groups *users* together and is simply a shared space that allows a team of people to access the same Loqate *Account*. All *users* in an *Organisation* can sign into the *Account* using their own email address. In addition to *users*, an *account* also has **contacts** which we use to send important account and business communication. ## Managing Account Details Keeping your account details accurate and up to date helps ensure you can access your services smoothly and securely. Up‑to‑date information also helps you receive important notifications and makes it easier to recover your account in the event of access issues. You can manage your account details from within the "[Your Account"](https://account.loqate.com/account#/Account/) area of the account section allowing you to: * **Add, edit or remove Contacts** and update email preferences : If we need to notify you about important changes, we will email the primary contact on the account. Balance, Security and Billing emails will be sent to all contacts who have these preferences enabled. * **Update company details** : Let us know the registered address of your company including VAT number if applicable. * **Add or update GDPR settings** : Let us know who is responsible for privacy in your organisation. ## Managing your Organisation Controlling access to your online Loqate Account is achieved through our Multi-User functionality. ### Organisation Roles There are two types of roles in the Organisation, an Admin and a Member. Admins can invite or remove users. Members can access the platform but cannot manage users. All other functionality is the same. ### Accessing the Organisation Manager Once logged into the account, users can be managed by using the drop-down at the top right of the account section and selecting the **Your Team** option. Should you be asked to re-log in, just enter your email, no password is required. ![Image](https://mintcdn.com/loqate/c8mexvCRZwwTYBcH/images/image.png?fit=max\&auto=format\&n=c8mexvCRZwwTYBcH\&q=85\&s=a1b734f282ff18e51e81d47f40c1f17d) ### Managing Users From the Organisation Menu a user with the Admin role can * **Invite new users** (Members screen): Invited users will receive an invitation to join the Organisation, once that invite has been accepted, they will be able to log in with their own email address. * **Change users' roles** (Members screen): By default, when invited, users are given the Member role unless otherwise set. * **Remove existing users** (Members screen): Removing users will prevent them from accessing the account, however if they are still listed as a Contact on the account then they may still receive account communication, such as billing information or security notices. Contacts can be deleted from the main account area. * **Manage the Organisation** (Organisation screen): From here you can choose to leave the organisation yourself or rename the organisation in our authentication system. ## Multiple Organisations Thanks to the multiple users in one organisation functionality, you can have multiple organisations under one account. This is useful if you have different teams that need access to the same account but want to manage their own users separately. That means, if you are part of several organisations, when you log in with your email address, we will show a screen where you can choose the organisation you want to use on those accounts. Because you can have different roles in different organisations (for example, Member, Admin, or Contact), the organisation switch screen will list each organisation so you can select the one you want to work with. ### All Organisations This screen shows all the organisations that you belong to being a contact, regardless of if they have been migrated before. ![All organisations](https://mintcdn.com/loqate/A1hDmUwE_kxcpVSx/images/loqate-basics/switch-org/all_orgs.png?fit=max\&auto=format\&n=A1hDmUwE_kxcpVSx\&q=85\&s=113c51a70a8086bd13922ee0a278e3de) The view "All" is the default view but you should also see "Migrated" and "Non migrated" that show the different organisations and their migration status. The top banner has a link to our documentation and support team if you require more information. The "Sign Out" button will only be visable if you are a contact of an organisation that has yet to be migrated. #### Icons and tags on the organisations You have three different icons and tags that indicate the status of each organisation: * Green Icon: This should show an inward arrow that says this account has been migrated and is ready for use because you have been added as a user. * Blue Icon: This should show a user symbol that indicates you are "Awaiting Access". This is because you are listed as a contact for this migrated organisation but have not yet been added as a user * Yellow Icon: This should show two arrows pointing outwards and indicates you are "Not migrated". This means this organisation has not yet been migrated. ### Migrated organisation and user added If the organisation or organisations have been migrated and you have been added as a user, you should see the following: ![Migrated organisations](https://mintcdn.com/loqate/A1hDmUwE_kxcpVSx/images/loqate-basics/switch-org/migrated_ogs.png?fit=max\&auto=format\&n=A1hDmUwE_kxcpVSx\&q=85\&s=c786d31db55286e652b234e7a4f5de78) In the example above, you can see one organisation has been properly migrated where the user is an active member and another organisation that has been migrated with you as a contact but you have yet to be added as a user. You will not be able to access the 2nd account until you have been added as a user. ### Migrated Organisation where you are a contact but not a user This can happen when organisations have been migrated, you are the primary contact but have not been added as a user of that organisation. Because of this, you won't be able to log in to that organisation, but you will be able to see it on the switch organisation screen. If you try to access that organisation, you will see a message asking you to contact your administrator to add you. In this case, you will see an image like the one above. ### Non-migrated organisations Organisations that haven't been migrated yet will show. ![Non migrated organisations](https://mintcdn.com/loqate/A1hDmUwE_kxcpVSx/images/loqate-basics/switch-org/non_migrated_orgs.png?fit=max\&auto=format\&n=A1hDmUwE_kxcpVSx\&q=85\&s=b0d35d1ae2b4743a114f3c3cfc735937) In this case, you will see the above login form with a message asking you to sign out in order to be able to migrate that organisation. To sign in to an unmigrated account, follow the instructions on the [Legacy Sign-In](/loqate-basics/legacy-login) page. ## Frequently Asked Questions > [accordion] What is the difference between a Contact and a User? > > A **User** is someone who can log in to your Loqate Account. A **Contact** is simply an email address we use to send important account‑related information. > > Within the "[Your Account"](https://account.loqate.com/account#/Account/) area of the account section, you can add *contacts* and we use these details for notifications such as balance alerts, security alerts and invoices. > > *Users*, on the other hand, have login access to your Loqate Account and are managed in the **Organisation** area. You can find this by clicking your company name in the top‑right corner of the account screen and selecting **“Your Team”**. > [accordion] How do I log in to my account? > > You can log in [here](https://auth.loqate.com/en/sign-in) using your email address as long as you are a user in the Organisation for the account. > [accordion] I am having problems logging in > > **Are you trying to log in with an Account Code?** > > Historically, customers have been able to log into their account using an Account Code and Password. Once an account is using our updated login capability, the ability to log in with an Account Code and Password is disabled. You must log in using your **email address**. > > **Have you been added to the Organisation?** > > If your email address hasn’t been invited to the Organisation, you won’t be able to log in.\ > Please contact the person who created, or converted the account and ask them to confirm that you appear in the **Organisation** area (found by clicking your company name in the top‑right corner of the account screen and selecting **"Your Team"**). > > **Are you trying to log in with the email address of a "Contact" on your Account?** > > See the FAQ titled **"What is the difference between a Contact and a User?"** above.  > > If your account has not yet been migrated and you need to sign in using an account code and password, see [Legacy Sign-In](/loqate-basics/legacy-login). > > If you are still having problems logging in, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/) who will be happy to help. > [accordion] Is my account using the updated Login capability? > > **Already logged in?** If you logged in with your email address and received a "magic link" or code to log in, then your account is using our updated login capability. > > **Not logged in yet?** If you try to log in using your Account Code and the password that previously worked, and are redirected to a message stating that **“Your account security has been upgraded and you now need to authenticate via email.”**, then your account has been migrated to our updated login capability. > > More information about account migration to the updated Login capability can be found [here](https://docs.loqate.com/loqate-basics/account-migration#why-cant-i-log-in) ## Payment Questions > [accordion] What has changed in the payment flow? > > The user-facing payment flow has not changed. Behind the scenes, we have moved to Stripe as our payment supplier to improve reliability and security. This also gives us better visibility into payment activity, helping us diagnose and resolve payment issues more quickly. If you need help with a specific checkout journey, please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) with our Support team. > [accordion] Why do I need to accept new terms to make a payment? > > To complete a payment, you need to accept the new Stripe terms. This ensures your purchase is processed against the latest applicable terms for the updated payment service. If you are unsure which terms apply to your account, please [get in touch](https://www.loqate.com/en-gb/contact/customer-support/#form) and we can confirm this for you. > [accordion] Why do I need to supply my company address to add a card or make a purchase? > > You need to provide your company address when adding a card or making a purchase so we can complete billing and compliance checks. It also helps ensure invoices and account records are accurate and up to date. If you are not sure what address details to provide, please [contact our Support team](https://www.loqate.com/en-gb/contact/customer-support/#form). > [accordion] What happens if I don't have enough credit to cover an entire batch request? > > If your account doesn't have enough credit to cover the full cost of a batch request, you'll receive an 'Account out of credit' or 'Not enough credit for request' error and no results will be returned. To run the batch, top up your credit to cover the full cost before resubmitting; see [Common errors](/api-reference/common-errors). # Loqate Usage Monitoring Source: https://docs.loqate.com/loqate-basics/monitoring-account-usage Track API usage and costs across all Loqate services with detailed reporting by service, key, and time period. The Loqate Account Section provides a full suite of usage reports in the Reporting page, which you can find [here](https://account.loqate.com/account#/NewReporting/). In this article the reporting functionality and how best to keep track of your usage is explained. Regularly checking the usage for each API key - i.e. how many requests are being made and what the running costs are - is recommended in order to maintain visibility of how your services are being used. Please note that the Charged Requests field in two of the following reports represents the number of API calls that have been made, not the volume of transactions being processed in a batch. For **Capture** or **Bulk Email Validation**, this figure shows the number of addresses or email addresses included in a call. With **Verify's** batch capability, be aware that this figure doesn't represent the number of addresses verified in a batch request. ## Main report The first report you'll see on this page shows the total number and total cost of charged requests over a given time period. You can run this report using various date ranges - note that the date range you select here will apply to all of the other reports on this page too. Here's what it looks like run for three days: ![MainReport1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/monitoring-account-usage/main-report-1-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=7b4e114492c9cb4b49fd17be5f46b1a1) And here's a month - as you can see the list of data underneath the chart increases: ![MainReport2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/loqate-basics/monitoring-account-usage/main-report-2-may-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=dbf1655742b6a55d28fef50824927c0c) ## Usage Summary by Service This report breaks down usage by product, based on the data range selected above. It defaults to All keys, but you can select a specific key if you only want to see the usage for services using that key. ![UsageSummary1](https://mintcdn.com/loqate/VN7o3YzokUitxNJS/images/loqate-basics/monitoring-account-usage/reporting-2.png?fit=max\&auto=format\&n=VN7o3YzokUitxNJS\&q=85\&s=f859f0e1df2486f3d608d610f3ae088e) The **Product Family** column shows the overall product grouping, while the **Service** column shows the specific endpoint. So for example, both **Find** and **Retrieve** calls will be listed as 'Addressing\_Capture' under **Product Family**, but you'll see the separate endpoints under **Service**. ![UsageSummary2](https://mintcdn.com/loqate/VN7o3YzokUitxNJS/images/loqate-basics/monitoring-account-usage/reporting-2a.png?fit=max\&auto=format\&n=VN7o3YzokUitxNJS\&q=85\&s=f3656831df2ef5f7e17e9b94cfe031e8) ## Summary Usage by Key This report breaks down usage for each of your API keys. If you hover the mouse over each key though, you can see which product family it's been used for. ![UsageSummary3](https://mintcdn.com/loqate/VN7o3YzokUitxNJS/images/loqate-basics/monitoring-account-usage/reporting-3-updated.png?fit=max\&auto=format\&n=VN7o3YzokUitxNJS\&q=85\&s=4f380ae6cf2904560a248ebfeba936ba) ### A note on terminology Please note that the **Charged Requests** field in these summaries represents the number of API calls that have been made, not the volume of transactions being processed in a batch. For certain products (such as **Capture** and **Bulk Email Validation**) you will see a number of records in brackets, like this: ![UsageSummary4](https://mintcdn.com/loqate/VN7o3YzokUitxNJS/images/loqate-basics/monitoring-account-usage/reporting-3a.png?fit=max\&auto=format\&n=VN7o3YzokUitxNJS\&q=85\&s=52a8c2d1e22d20fc545738b8e419f1df) This represents the fact that one API call might contain multiple addresses or emails, in which case it will be shown as a single request with multiple records. > [!NOTE] > > If you see any usage which doesn't conform with what you'd expect, please don't hesitate to contact the [Loqate Support team](https://www.loqate.com/en-gb/contact/customer-support/). # Single Sign-On (SSO) for Your Loqate Account Source: https://docs.loqate.com/loqate-basics/single-sign-on Connect your own identity provider to your Loqate Account so your team signs in with your company credentials, and let your IT administrators set it up themselves. > [!NOTE] > > Single Sign-On is available to Enterprise customers only, and needs to be enabled on your Organisation before you can configure it. Please contact your account manager to have it activated. If you do not know who your account manager is, please contact the support team at [support@loqate.com](mailto:support@loqate.com). ## What is Single Sign-On? Single Sign-On (SSO) lets your users sign in to your Loqate Account using your own identity provider (IdP), such as Okta, Microsoft Entra ID or Google Workspace, instead of receiving a magic link or code by email. Once SSO is active, anyone signing in with an email address on one of your verified domains is redirected to your identity provider to authenticate. Your IdP decides whether they get in, which means access to your Loqate Account follows the same rules as the rest of your business systems. SSO is self-administered. Once your account manager has enabled it, your own IT administrators complete the whole setup from within your Loqate Account, so there's no need to raise a ticket with us or wait on our team to configure anything for you. ## Why use SSO? * **Central control of access** : Users are granted and revoked access in your identity provider. When someone leaves your business and is disabled there, they lose access to your Loqate Account too. * **Your own security policies** : Multi-factor authentication, conditional access, password rules and session policies are all enforced by your IdP. * **A simpler sign-in** : Your team signs in with the credentials they already use every day. * **Set up on your own schedule** : Your IT team configures, tests and activates the connection when it suits them. > [!NOTE] > > SSO controls how users sign in to your Loqate Account. It does not change how your integrations authenticate. [Loqate's APIs](/api-reference/introduction/) continue to use your API keys. See [API Security](/loqate-basics/api-security) for how to secure those. ## Before you begin Make sure the following are in place before you start, as you'll need all of them to complete the setup in one sitting. * **SSO enabled on your Organisation** : Your account manager arranges this. You won't see the options described below until it's done. * **The Admin role** : Only users with the Admin role in your Organisation can set up or change an SSO connection. Members cannot. See [Managing Your Account](/loqate-basics/managing-account#organisation-roles) for more on roles. * **Administrative access to your identity provider** : You'll need to be able to create and configure an application in your IdP. * **The ability to publish DNS records** : You'll need to add a `TXT` record to the DNS for each domain you want to use, to prove you own it. If your DNS is managed by another team, involve them early, as this is usually the slowest part of the process. ## Terminology Your Loqate **Account** has a corresponding **Organisation**, which groups your **users** together and lets a team of people access the same account. SSO is configured against your Organisation, and applies to every user who signs in with an email address on a verified domain. If you're new to Organisations and user management, read [Managing Your Account](/loqate-basics/managing-account) first. ## Setting up your connection ### 1. Open the Security tab Sign in to your Loqate Account, click your company name in the top-right corner of the account section and select **Your Team**. Then open the **Security** tab. If you can't see the **Security** tab, either SSO hasn't been enabled on your Organisation yet, or you don't have the Admin role. ### 2. Claim and verify a domain Start by telling us which email domains belong to your business, for example `yourcompany.com`. You can add more than one. For each domain you add, we'll generate a DNS `TXT` record. Ask whoever manages your DNS to publish that record on the domain, then come back and verify it. > [!NOTE] > > DNS changes can take anything from a few minutes to several hours to propagate. If verification fails on the first attempt, wait a while and try again before assuming something is wrong. You must have at least one verified domain before you can continue. Verification also stops anyone else claiming a domain that isn't theirs. ### 3. Choose your identity provider Next, choose the provider you want to connect. The following are supported: | Protocol | Provider | | - | - | | SAML | Okta Workforce | | SAML | Microsoft Entra ID (formerly Azure AD) | | SAML | Google Workspace | | SAML | Custom SAML Provider | | OIDC | OIDC Provider | If your provider isn't listed by name but supports SAML 2.0 or OpenID Connect, use **Custom SAML Provider** or **OIDC Provider**. > [!WARNING] > > Switching an existing connection to a different provider removes the current connection, and you'll need to start the configuration again from the beginning. Choose the right provider before you invest time in configuring it. ### 4. Configure the connection The details you exchange with your IdP depend on which protocol you're using. > [tab] SAML > > Setting up a SAML connection involves swapping details in both directions: ours go into your IdP, and your IdP's come back to us. > > **In your identity provider**, create a new SAML application and enter the values we show you in the **Security** tab: > > * **Assertion Consumer Service (ACS) URL** : where your IdP sends its response after authenticating a user. > * **Entity ID** : identifies your Loqate Account to your IdP. Some providers label this the audience or audience URI. > > Then configure the attribute statements your IdP sends to us: > > | Attribute | Required | Description | > | - | - | - | > | `mail` | Yes | The user's email address | > | `firstName` | No | The user's first name | > | `lastName` | No | The user's last name | > > The `mail` attribute is essential. It's how we match the person signing in to your Organisation, and the domain of that address must be one you've verified. Mapping `firstName` and `lastName` is optional, but it makes your user list much easier to read. > > Finally, assign the users or groups in your IdP who should have access to your Loqate Account. > > **Back in the Security tab**, supply your IdP's details. Most providers publish a **Metadata URL**, which is the quickest and most reliable option, as it keeps things such as certificate rotations up to date automatically. If your provider doesn't offer one, you can enter the details manually instead: > > * **SSO URL** : your IdP's sign-in endpoint. > * **Entity ID (Issuer)** : identifies your IdP to us. > * **Signing certificate** : used to verify that responses genuinely came from your IdP. > [tab] OIDC > > Setting up an OpenID Connect connection takes three steps. > > First, **register the redirect URI**. Copy the **Authorized redirect URI** shown in the **Security** tab and add it to the application you've created in your IdP. Your IdP will refuse the sign-in request if this doesn't match exactly. > > Second, **provide your IdP's endpoints**. If your provider exposes a **Discovery Endpoint** (often ending `/.well-known/openid-configuration`), enter that and we'll read the rest of the configuration from it. Otherwise, enter the endpoints manually: > > * **Authorization URL** > * **Token URL** > * **User Info URL** > > Third, **enter your credentials**: the **Client ID** and **Client Secret** from the application in your IdP. Treat the client secret like any other credential: don't share it outside your IT team, and store it somewhere secure. > > Make sure your IdP returns the following claims in the ID token: > > | Claim | Required | Description | > | - | - | - | > | `sub` | Yes | A stable, unique identifier for the user | > | `email` | Yes | The user's email address | > | `given_name` | No | The user's first name | > | `family_name` | No | The user's last name | > > As with SAML, the email address must be on a domain you've verified. ### 5. Test the connection Before activating the connection, use the test sign-in in the **Security** tab to confirm the connection works from end to end. The test runs against your live configuration but doesn't affect anyone else, so your team continues to sign in as normal while you're checking. If the test fails, the most common causes are a mismatched redirect URI or ACS URL, a missing email attribute or claim, or the test user not being assigned to the application in your IdP. > [!WARNING] > > We'd strongly recommend you don't skip this step. ### 6. Activate the connection Once the connection is active, any user whose email address is on one of your verified domains must authenticate through your identity provider to reach your Loqate Account. They'll no longer receive a magic link or code by email. > [!WARNING] > > Make sure the users who need access are assigned to the application in your identity provider **before** you activate the connection. If they aren't, they'll be locked out of your Loqate Account until you assign them. ## Managing an active connection Changes you make to an active connection take effect immediately, which means an incorrect value can stop your team signing in. You'll see a warning in the **Security** tab reminding you of this before you save. If you need to make significant changes, such as rotating a client secret, moving to a new IdP application, or changing endpoints, it's worth planning them for a quieter period, and keeping a Loqate Admin available who can help if something goes wrong. If you get locked out of your account, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/), who will be happy to help. ## Frequently Asked Questions > [accordion] How do I get SSO enabled on my account? > > Single Sign-On is available to Enterprise customers only. Please speak to your account manager, who will arrange for it to be enabled on your Organisation. If you're not sure who your account manager is, contact the support team at [support@loqate.com](mailto:support@loqate.com). > > Once it's enabled, you'll see a **Security** tab in the **Your Team** area, and you can complete the rest of the setup yourself. > [accordion] Who in my business can set up SSO? > > Only users with the **Admin** role in your Organisation. Members can sign in and use the platform, but cannot configure SSO. See [Managing Your Account](/loqate-basics/managing-account#organisation-roles) for more on roles. > > In practice you'll usually want an Admin and someone with access to both your identity provider and your DNS records. That might be the same person, or it might be two or three people working together. > [accordion] Why do I need to verify my domain? > > Verifying a domain proves that your business controls the email addresses you're claiming. Without it, someone could set up a connection that captured sign-ins for a domain that wasn't theirs. > > You verify a domain by publishing a `TXT` record we generate in that domain's DNS. You need at least one verified domain before you can configure a connection. > [accordion] Can I use more than one domain? > > Yes. Add and verify each domain you want to cover. This is useful if your business uses several email domains, or if you've acquired companies that still use their original domains. > [accordion] What happens to users who aren't on a verified domain? > > They continue to sign in as they do today, using their email address. SSO only applies to users whose email address is on one of your verified domains. > > This is worth bearing in mind if you have contractors or partners in your Organisation on external domains. > [accordion] Does SSO change how my API keys work? > > No. SSO governs how people sign in to your Loqate Account. Your integrations continue to authenticate with API keys exactly as before. To secure those, see [API Security](/loqate-basics/api-security). > [accordion] Can I change identity provider later? > > Yes, but switching an existing connection to a different provider removes the current connection and you'll need to configure the new one from scratch. Plan for a short window where your team may need to sign in another way, and test the new connection before activating it. > [accordion] My test sign-in failed. What should I check? > > Start with the details that have to match exactly between Loqate and your identity provider: the **Authorized redirect URI** for OIDC, or the **Assertion Consumer Service (ACS) URL** and **Entity ID** for SAML. A trailing slash or a copied-in space is enough to break it. > > Then check that your IdP is sending the user's email address (the `mail` attribute for SAML, or the `email` claim for OIDC), that the address is on a verified domain, and that the test user is assigned to the application in your IdP. > > If you're still stuck, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/). > [accordion] Nobody can sign in since we activated the connection. What now? > > The most likely cause is that your users haven't been assigned to the application in your identity provider. Check the assignments there first. > > If you can still reach the **Security** tab, you can deactivate the connection to restore email sign-in while you investigate. If you can't get in at all, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/), who will be happy to help. # Slack Community Source: https://docs.loqate.com/loqate-basics/slack # Support Source: https://docs.loqate.com/loqate-basics/support # Ways to Integrate Source: https://docs.loqate.com/loqate-basics/ways-to-integrate Loqate offers three main integration options: * **Using Tag:** Available for Address Capture, Email Verification and Phone Verification * **Using APIs:** Available for all Loqate products and services * **Integrations by Platform:** Available for Address Capture, Verify, Email Verification and Phone Verification via integrations with tools like Shopify, Adobe Commerce, and Microsoft Dynamics 365 > [!NOTE] > > **🤖 New: Reach — Loqate for Agents** — verify addresses, emails, and phone numbers in real time with a confidence score, policy-aware recommendation, and full audit trail in one command. > > [Explore Reach](https://agents.gbg.com/reach.html) > [!NOTE] > > **Loqate Core SDKs are now in Early Access (Beta)** — our new TypeScript and .NET SDKs are available to try today.\ > They're stable, generated from our live API definitions, and form the first stage of our developer-tools refresh.\ > We'd love your feedback as we continue to expand them. > > See the [SDK Overview](/sdks/overview) for details. > [!NOTE] > > The main focus of this article is on Tag and API integrations, although information about third-party integrations is also included, with a link to the specific documentation. These options are not mutually exclusive, so you can use more than one in conjunction if you want. Regardless of which option(s) you choose, you can make changes in the Account Section for security, customisation and certain features. # Use cases Here are a few examples of possible use cases, and which of the Tag or API integration option might be best for each: | Business Type | Specifics | Recommended option | | :- | :- | :- | | Financial business | Strictly regulated | APIs | | Large ecommerce business | Requires considerable customisation | APIs | | Very small business | Uses simple web forms | Tag | | Small business | Uses cloud-based tools for creating forms | Tag or APIs | ## Tag Integrations The simplest way of setting up Address Verification, Email Validation and Phone Validation is by using the Tag method, which uses automatically-generated code snippets that you can insert into your website to set these services up. This method is designed for simple webforms, allowing you to set up standard configurations via your Loqate account. **Pros:** * **Speed:** you can get started quickly and easily * **Simplicity:** there's no need for technical know-how, as the functionality comes from the JavaScript solution and CSS **Cons:** * **Customisation:** unlike API integrations, you don't have as much control over how your integration works as it will always be based off the JavaScript and CSS * **Security:** adding JavaScript to your website, while an effective way of adding new functionality, does come with some security considerations, and as such may not be appropriate for all circumstances. See the [API Security](/loqate-basics/api-security) article for more information Check out the [Tag Setup Guide](/our-services/tag-setup-guide) for simple instructions that walk you through how to get set up with Tag integrations. From an additional security perspective, consider using the Limits functionality to restrict your integration by IP address, service and/or URL. See the [API Security](/loqate-basics/api-security) article for more details. ## API Integrations All Loqate products can be integrated using the APIs, which are also available for Address Verification, Email Verification and Phone Verification for more flexible integrations. **Pros:** * **Control:** you're not constrained by any existing integrations or ways of working, and you don't need to rely on the preset JavaScript or CSS * **Customisation:** you can shape your customer journey however you see fit **Cons:** * **Complexity:** API integrations require technical knowledge and resources * **Speed:** it takes time to implement and test API integrations Check out the [API documentation](/api-reference/introduction) for details of all of the Loqate APIs. You can still take advantage of all of the security functionality available in the Account Section - see the [API Security](/loqate-basics/api-security) article for more details. ## Integrations by Platform As well as the option of creating your own integration using the Tag and/or API methods, there's also a range of integrations which allow you to access Address Capture, Verify, Email Validation and Phone Validation within various tools. Current integrations include: * [Adobe Commerce](/integrations/adobe-commerce) * [BigCommerce](/integrations/bigcommerce) * [commercetools](/integrations/commercetools) * [Microsoft Dynamics 365](/integrations/microsoft-dynamics-365) * [Reapit](/integrations/reapit) * [Salesforce Commerce Cloud](/integrations/salesforce-commerce-cloud) * [Salesforce CRM](/integrations/salesforce-crm) * [Shopify Plus](/integrations/shopify-plus) If you already use any of these tools, you can use the integrations to quickly and easily add Loqate functionality to your site. Check out the [Integrations documentation](/integrations/all-integrations) for details of how to get up and running. # Address Capture Quick Start Guide Source: https://docs.loqate.com/our-services/address-capture/address-capture-quick-start Start using Address Capture in three steps. Set up your API key, search for addresses with Find, and retrieve full details with Retrieve. **Address Capture provides real-time address search and verification as users type, reducing errors and improving data quality.** *** ## Coverage * **Global:** Address data for over 250 countries and territories * **UK Premium:** AddressBase Premium data with Geolocation support ## Available Endpoints Address Capture provides three API endpoints: ### Core Endpoints * [**Find**](/api-reference/address-capture/find) - Search for addresses and places as users type * [**Retrieve**](/api-reference/address-capture/retrieve) - Get full address details based on the selected ID ### Additional Endpoint * [**Geolocation**](/api-reference/address-capture/geolocation) - Find addresses within a radius of latitude/longitude coordinates (UK AddressBase Premium only) ## Getting Started 1. [Create an API key](https://docs.loqate.com/loqate-basics/create-an-api-key) if you don't have one 2. Make a **Find** request to search for addresses as the user types 3. Make a **Retrieve** request to get the full address when they select one Here's a simple example request for the **Find** endpoint: ```shell cURL theme={null} curl --request GET \ --url https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws ``` ```python Python theme={null} import requests url = "https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws" response = requests.get(url) print(response.json()) ``` ```javascript JavaScript theme={null} const url = 'https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws'; const options = {method: 'GET', body: undefined}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```php PHP theme={null} "https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```go Go theme={null} package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws" req, _ := http.NewRequest("GET", url, nil) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java Java theme={null} HttpResponse response = Unirest.get("https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws") .asString(); ``` ```ruby Ruby theme={null} require 'uri' require 'net/http' url = URI("https://api.addressy.com/Capture/Interactive/Find/v1.20/json6.ws") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) response = http.request(request) puts response.read_body ``` Here's a simple example request for the **Retrieve** endpoint: ```shell cURL theme={null} curl --request GET \ --url https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws ``` ```python Python theme={null} import requests url = "https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws" response = requests.get(url) print(response.json()) ``` ```javascript JavaScript theme={null} const url = 'https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws'; const options = {method: 'GET', body: undefined}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```php PHP theme={null} "https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```go Go theme={null} package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws" req, _ := http.NewRequest("GET", url, nil) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java Java theme={null} HttpResponse response = Unirest.get("https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws") .asString(); ``` ```ruby Ruby theme={null} require 'uri' require 'net/http' url = URI("https://api.addressy.com/Capture/Interactive/Retrieve/v1.30/json6.ws") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) response = http.request(request) puts response.read_body ``` ## What Address Capture Returns A typical Address Capture workflow: * **Find** returns a list of matching addresses based on search text * **Retrieve** returns the complete formatted address in multiple formats ### Find Response Response should be in the following format: ```json theme={null} { "Items": [ { "Id": "GB|RM|B|55605138|ENG", "Type": "Address", "Text": "G B G Evermore 128 Queen Victoria Street", "Highlight": "0-1,2-3,4-5", "Description": "London EC4V 4BJ" } ] } ``` ### Retrieve Response ```json theme={null} { "Items": [ { "Id": "GB|RM|B|55605138|ENG", "DomesticId": "55605138", "Language": "ENG", "LanguageAlternatives": "", "Department": "", "Company": "G B G", "SubBuilding": "", "BuildingNumber": "128", "BuildingName": "Evermore", "SecondaryStreet": "", "Street": "Queen Victoria Street", "Block": "", "Neighbourhood": "", "District": "", "City": "London", "Line1": "G B G Evermore", "Line2": "128 Queen Victoria Street", "Line3": "", "Line4": "", "Line5": "", "AdminAreaName": "", "AdminAreaCode": "", "Province": "", "ProvinceName": "", "ProvinceCode": "", "PostalCode": "EC4V 4BJ", "CountryName": "United Kingdom", "CountryIso2": "GB", "CountryIso3": "GBR", "CountryIsoNumber": "826", "SortingNumber1": "", "SortingNumber2": "", "Barcode": "", "POBoxNumber": "", "Label": "G B G Evermore\n128 Queen Victoria Street\nLondon\nEC4V 4BJ\nUnited Kingdom", "Type": "Commercial", "DataLevel": "Premise", "Field1": "", "Field2": "", "Field3": "", "Field4": "", "Field5": "", "Field6": "", "Field7": "", "Field8": "", "Field9": "", "Field10": "", "Field11": "", "Field12": "", "Field13": "", "Field14": "", "Field15": "", "Field16": "", "Field17": "", "Field18": "", "Field19": "", "Field20": "" } ] } ``` And you can use this information below to interpret the response fields: > [accordion] Find Response Fields > > ### Search Results > > | Field | Type | Description | > | - | - | - | > | `Id` | string | Unique identifier for the address or container (for further results). Can change over time | > | `Type` | string | Type of result: Address, Container, Postcode, Street, BuildingName, or Building. If Type is Address, pass Id to Retrieve. Otherwise, pass Id as Container to another Find request | > | `Text` | string | First half of the address displayed to the user | > | `Highlight` | string | Number ranges showing which characters match the search term. Use to highlight matching text in bold. Empty if Container Id included in request | > | `Description` | string | Second half of the address, including address count for Containers | > [accordion] Retrieve Response Fields > > ### Address Label Format > > | Field | Type | Description | > | - | - | - | > | `Label` | string | Complete formatted address with line breaks (\n). Ideal for display or printing on envelopes | > > ### Address Lines Format (Recommended) > > | Field | Type | Description | > | - | - | - | > | `Company` | string | Company name | > | `Line1` | string | First line of formatted address | > | `Line2` | string | Second line of formatted address | > | `Line3` | string | Third line of formatted address | > | `Line4` | string | Fourth line of formatted address | > | `Line5` | string | Fifth line of formatted address | > | `City` | string | Town or city name | > | `Province` | string | Either ProvinceName or ProvinceCode based on country standards | > | `PostalCode` | string | Full postal code (Postcode, ZIP Code, etc.) | > > ### Address Elements Format > > | Field | Type | Description | > | - | - | - | > | `Department` | string | Department name for business addresses | > | `SubBuilding` | string | Sub-building identifier (Flat 4, Unit 2, etc.) | > | `BuildingNumber` | string | House or building number | > | `BuildingName` | string | Building name if applicable | > | `SecondaryStreet` | string | Secondary thoroughfare name | > | `Street` | string | Main thoroughfare name | > | `Block` | string | Block details | > | `Neighbourhood` | string | Neighbourhood name | > | `District` | string | District name | > > ### Geographic and Administrative > > | Field | Type | Description | > | - | - | - | > | `AdminAreaName` | string | Administrative area name (e.g., county council) | > | `AdminAreaCode` | string | Administrative area code | > | `ProvinceName` | string | Largest administrative division name (state, county) | > | `ProvinceCode` | string | Administrative division code | > | `CountryName` | string | Full country name (ISO 3166-1) | > | `CountryIso2` | string | Two-character ISO country code | > | `CountryIso3` | string | Three-character ISO country code | > | `CountryIsoNumber` | string | ISO numeric country code | > > ### Additional Fields > > | Field | Type | Description | > | - | - | - | > | `Id` | string | Unique address identifier | > | `DomesticId` | string | Reference number in source dataset (e.g., UDPRN) | > | `Language` | string | Three-letter language code | > | `Type` | string | Address type: Residential, Commercial, or Unknown (available in select countries) | > | `DataLevel` | string | Data precision level: Unknown, Premise, RangedPremise, Street, or City | > | `POBoxNumber` | string | PO Box number if applicable | > | `Barcode` | string | Barcode for bulk mailing schemes | > | `Field1` - `Field20` | string | Custom fields when using Field1Format - Field20Format parameters | > > **Note:** Use Field1Format through Field20Format request parameters to return custom data (e.g., latitude, longitude) in these fields. > [accordion] Error Response Fields > > When an error occurs, the API returns an error response with the following structure: > > | Field | Type | Description | > | - | - | - | > | `Error` | string | The error ID | > | `Description` | string | A description of the error | > | `Cause` | string | The cause of the error | > | `Resolution` | string | Actions to resolve the error | > > ### Common Error Codes > > | Status Code | Meaning | Common Causes | > | - | - | - | > | **400** | Bad Request | Invalid parameters, malformed request, missing required fields | > | **401** | Unauthorized | Invalid or missing API key | > | **403** | Forbidden | API key doesn't have permission for this service, or daily limit exceeded | > | **500** | Internal Server Error | Server-side issue, temporary service disruption | > > **Tip:** Check the `Resolution` field for specific steps to fix the error. For more details on error responses, see [Find](/api-reference/address-capture/find) in API documentation. **Note:** Address Capture provides three response formats: Label (single string), Lines (recommended for forms), and Elements (individual components). Use one format consistently to avoid duplication or missing data. ## Integration Methods Beyond direct API integration, Address Capture can be integrated using: * **Tag:** Automatically-generated code snippets for your website forms - [Tag Setup Guide](/our-services/tag-setup-guide) * **SDK:** Pre-built SDK for quick custom integration - [Capture SDK](/our-services/address-capture/sdk) * **Pre-built integrations:** Ready-made integrations for Adobe Commerce, Shopify Plus, and more - [All Integrations](/integrations/all-integrations) See the [Ways to Integrate](/loqate-basics/ways-to-integrate) page for guidance on choosing the best method. ## Try Address Capture Test Address Capture using the [Find Playground](/api-reference/address-capture/find?playground=open) to make your first request. ## FAQ > [accordion] Which integration method works best for me? > > The best method depends on your technical requirements and resources. Use Tags for quick website integration, the SDK for custom web applications, direct APIs for full control, or pre-built integrations for supported platforms. See the [Ways to Integrate](/loqate-basics/ways-to-integrate) page for detailed guidance. > [accordion] How do I map Address Capture fields to my form? > > Address Capture provides three formats: **Label** (single formatted string), **Lines** (recommended for multi-line forms), and **Elements** (individual address components). Choose one format based on your form structure. The Lines format works best for most forms with separate fields for company, address lines, city, and postcode. Do not mix formats to avoid duplication or missing data. See the [Retrieve API documentation](/api-reference/address-capture/retrieve) for all available fields. > [accordion] Should I make API calls client-side or server-side? > > Consider performance, complexity, and security when deciding. Client-side calls provide faster user experience but expose your API key. Server-side calls are more secure but add latency. See the [API Security](/loqate-basics/api-security) page for detailed guidance on integration options and security best practices. > [accordion] Can I get latitude and longitude coordinates? > > Yes. Use the `field1format={Latitude}` and `field2format={Longitude}` parameters in your Retrieve request to return coordinates in Field1 and Field2. Coordinates are returned where available in the dataset. For Tag integrations, configure these parameters in the mappings wizard. See the [Retrieve API documentation](/api-reference/address-capture/retrieve) for details on custom field formatting. # Address Capture API Endpoints Source: https://docs.loqate.com/our-services/address-capture/apis Three Address Capture endpoints: Find searches for addresses as users type, Retrieve returns formatted details, Geolocation uses coordinates. Address Capture consists of two main API requests: * A **Find** request is used to narrow down a possible list of addresses * A **Retrieve** request is used to retrieve a fully formatted address A typical address search is made up of a series of Find requests, followed by a Retrieve based on the selected address id. > [card] [Quickstart](/api-reference/address-capture/quickstart) > > Check out our API Quickstart Guide to make your first Address Capture request. Also available for customers using AddressBase Premium data for UK addresses is **Geolocation**, which takes latitude and longitude coordinates and returns a list of addresses that are within a specified radius. This must be followed by a Retrieve to obtain a fully formatted address. Choose a service below to find out how to use each request. > [card] [Find](/api-reference/address-capture/find) > > Uses a text search to find addresses and places. > [card] [Retrieve](/api-reference/address-capture/retrieve) > > Returns the full address details based on the Id. > [card] [Geolocation (UK AddressBase data only)](/api-reference/address-capture/geolocation) > > Takes latitude/longitude coordinates and returns a list of addresses within a specified radius # Address Capture Implementation Guide Source: https://docs.loqate.com/our-services/address-capture/implementation-guide Add real-time address autocomplete to your website with copy-paste code examples **Reduce address entry errors and improve data quality with real-time address autocomplete as users type.** ## Who Should Use This Guide **For:** Business owners and developers integrating address autocomplete without complex setup. **You'll need:** A Loqate API key and basic HTML knowledge. **Not covered:** Tag-based integrations ([see Tag Setup](/our-services/tag-setup-guide)) or pre-built platform integrations ([see Integrations](/integrations/all-integrations)). ## What You'll Build An address autocomplete form that: * Shows address suggestions as users type * Fills in complete address details when selected * Works with addresses in over 250 countries * Provides formatted address lines for easy form population ## Quick Start To set up Address Capture, you'll need an API key. Find out how to get yours [here](/loqate-basics/create-an-api-key/). ### Choose Your Approach > [tab] Standalone Form > > **Use case:** Testing the API or adding to a static page > > A self-contained HTML file you can copy and use immediately. > > Jump to [standalone HTML example](#standalone-html-example) > [tab] Integrate with Existing Form > > **Use case:** Add autocomplete to your current checkout or registration forms > > Step-by-step guide to add autocomplete code to forms you already have. > > Jump to [integration example](#integration-example) **Using Shopify or WordPress?** Check [pre-built integrations](/integrations/all-integrations). ### Add Your Key Replace `YOUR_API_KEY` in the code with your actual Loqate API key. ### Test 1. Open your page 2. Start typing an address like "10 Downing" 3. Select from the suggestions 4. Complete address populates automatically > [!NOTE] > > Address Capture supports over 250 countries and territories. Use the Countries parameter to restrict results to specific countries. *** ## Sample Project: Checkout Form Integration This walkthrough shows how to add address autocomplete to a checkout form. Follow along to see a basic form transform into an intelligent address capture form. > [!NOTE] > > This is a detailed walkthrough. If you just want working code, skip to [Integration Example](#integration-example) or [Standalone HTML Example](#standalone-html-example). ### Before: Manual Address Entry A checkout form with manual address entry: Code Example **This form works, but users must type complete addresses manually.** Let's add autocomplete. *** ## How Address Capture Works Address Capture uses a two-step process: ### 1. Find Step **What it does:** Searches for addresses as users type. **When to use:** On every keystroke or with debouncing (recommended). **What you get:** A list of matching addresses and containers (groups of addresses). **API endpoint:** `https://api.addressy.com/Capture/Interactive/Find/v1.10/json6.ws` **Key parameters:** * `Text` - The search term (what the user typed) * `Container` - Optional ID for drilling down into results * `Countries` - Optional filter (e.g., "GBR" for UK only) ### 2. Retrieve Step **What it does:** Gets the complete address details. **When to use:** When a user selects an address from the suggestions. **What you get:** Full address in multiple formats (lines, elements, label). **API endpoint:** `https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/json6.ws` **Key parameter:** * `Id` - The unique address identifier from Find results ### How They Work Together ``` User types "10 Dow" ↓ Find API returns suggestions ↓ User selects "10 Downing Street" ↓ Retrieve API returns complete address ↓ Form fields populate automatically ``` *** ## Standalone HTML Example A minimal address autocomplete form for quick testing: Code Example **Perfect for:** * Quick API testing * Learning how address autocomplete works * Simple integrations without checkout flows **To use:** 1. Copy the code 2. Replace `YOUR_API_KEY` 3. Save and test with different addresses > [!NOTE] > > This example searches all countries by default. Add a Countries parameter to restrict results. ## Code on GitHub If you'd like to browse the code snippets in this implementation guide or clone them, visit the repository on [GitHub](https://github.com/loqate/javascript-docs-sample/tree/main/address-capture). ## Integration Example Here's the checkout form with full address autocomplete integrated: Code Example **To use this code:** 1. Copy the code 2. Replace `YOUR_API_KEY` with your actual Loqate API key 3. Save as an HTML file 4. Open in a browser to test 5. Customize styling to match your brand **Key features in this example:** * Real-time address suggestions as users type * Debounced API calls to reduce requests * Automatic form population on selection * Support for multiple countries * Clean, production-ready code structure > [!NOTE] > > This example uses debouncing (300ms delay) to reduce API calls while users type. Adjust the delay based on your needs. *** ## Integration Tips ### Adding to Your Existing Forms To add address autocomplete to your current forms: 1. **Add the autocomplete functions** from the integration example to your page's ` ``` **NOTE:** minified versions of these files are available. To use them, update the above snippets with .min before the file type (i.e. .../address-4.05.min.css and .../address-4.05.min.js). ## Mapping your fields The address capture control needs to know which elements of the address should be put into each of your fields. It also needs to know which fields should be used for searching and which field (if any) contains the country. This information is provided in a standard format, which is an array of objects that have an **element**, **field** and optional **mode** property. ```javascript theme={null} var fields = [ // Search field - triggers autocomplete when user types { element: "search", field: "" }, // Company - preserves existing value if already populated by user { element: "company", field: "Company", mode: pca.fieldMode.DEFAULT | pca.fieldMode.PRESERVE }, // Address lines - Line1 uses default behavior (SEARCH + POPULATE) { element: "line1", field: "Line1" }, // Line2 and subsequent fields only populate, don't trigger search { element: "line2", field: "Line2", mode: pca.fieldMode.POPULATE }, { element: "city", field: "City", mode: pca.fieldMode.POPULATE }, { element: "state", field: "Province", mode: pca.fieldMode.POPULATE }, // Postal code field { element: "postcode", field: "PostalCode" }, // Country field - displays country list on focus and sets search context { element: "country", field: "CountryName", mode: pca.fieldMode.COUNTRY } ]; ``` ### Field Configuration Properties * **element**: The id or name attribute of your field. Accepts partial id match (e.g., "\_line1" matches "frm1\_line1") or JavaScript regex for complex matching. * **field**: The name of the address element for this field. See [Capture Interactive Retrieve](#security) for available fields. Also accepts format strings (detailed in next section). * **mode**: Controls field behavior. Default is **SEARCH** and **POPULATE**. Modes are declared in **pca.fieldMode** and can be combined using bitwise OR (|): * **SEARCH**: Enables autocomplete searching from the field * **POPULATE**: Sets the field value based on selected address * **COUNTRY**: Displays country list on field select and reads field value to set search country * **PRESERVE**: Prevents overwriting fields already populated by user (useful for company name) ## Formatting fields To define complex or custom field values, the control makes use of template strings. The template strings work by replacing field values from the selected address, based on field names which are enclosed in curly brackets, for example `{PostalCode}`. Any regular text or HTML can be included in the template strings around the field values, such as `{Line1}, {Line2}`. Conditional formatting can be added by enclosing the field, and any additional text which is conditional on the field having a value, in a second set of curly brackets. If the template string was `{Line1}{, {Line2}}` then the comma would not appear unless the selected address had a second address line. Finally, field values will always appear in title case, but can easily be capitalised by adding an exclamation mark (!) at the end of the field name, like this `{City!}`. ## Setting options The second parameter that is required by the address control is a configuration object. This is used to set options and customise how the control behaves. The only required option is the API key that you will be using to access the web services, and is defined by creating an object literal in JavaScript. ```json theme={null} { key: "AA11-AA11-AA11-AA11" } ``` Further options can be set by adding more information to the configuration object. To create a control that was limited to the United States and Canada, but set the country based upon the users IP address, you would define the following object: ```json theme={null} {key: "AA11-AA11-AA11-AA11", countries: { codesList:"USA,CAN"}, setCountryByIP: false} ``` ## Countries Capture+ is designed to be a truly international address verification and standardisation solution, and will by default allow you to search through all of the [countries that are covered](https://www.loqate.com/en-gb/address-verification/). However, you can limit the countries that Capture+ will search by adding search settings into your options object. For example, to create a control that was limited to the United States and Canada, but set the country based upon the users IP address, you would define the following object: ```json theme={null} {key: "AA11-AA11-AA11-AA11", countries: { codesList:"USA,CAN"}, setCountryByIP: false} ``` ## Geolocation options (Available only for UK addresses) Loqate's address capture also supports address lookup based on your end user's current location. In order to access this additional functionality, you will have to add the following to your options object: `GeoLocationEnabled`: true, `GeoLocationRadius`: 50, `GeoLocationMaxItems`: 10 These attributes are defined as follows: * `GeoLocationEnabled`: Boolean to determine if the Geolocation functionality is active * `GeoLocationRadius`: Integer to determine the radius of the requested search in metres * `GeoLocationMaxItems`: The number of results to display in the dropdown You also need your site to run under https to enable this functionality. This will add an additional item to the address capture bar, allowing your user to search for their address based on their current location. An example of the complete options object is as follows: ```json theme={null} { key: "AA11-AA11-AA11-AA11", search: { countries: "GBR" }, setCountryByIP: true, GeoLocationEnabled : true, GeoLocationRadius : 50, GeoLocationMaxItems : 10} ``` Note: "GBR" is the ISO 3166-1 alpha-3 country code for the United Kingdom. Geolocation is currently available only for UK addresses, so when using `GeoLocationEnabled` you must include "GBR" in the `countries` setting. ## Language Both the control and web service API support a variety of language cultures. The language is automatically detected from the user's web browser but a **culture** option and **setCulture** method are also provided. The culture is based on 2-character code (e.g. "en", "fr") or culture name (e.g. "en\_GB", "en\_US", "fr\_FR", "fr\_CA"). ## The control object When you instantiate a new **pca.Address** object you will get a reference to an object commonly referred to as the **control** object. ```javascript theme={null} var control = new pca.Address(fields, options); ``` This is the main object for address capture on your address form and provides all methods and properties to customise the address capture experience. You will typically have one of the these objects for each of your address forms, so it is important to give them individual references or store them in a list. ```javascript theme={null} var billingControl = new pca.Address(billingFields, billingOptions); var shippingControl = new pca.Address(shippingFields, shippingOptions); ``` The control object will automatically wait for the page DOM to be loaded before it initialises, so it is important to listen for the **load** event before calling methods on the control object. ```javascript theme={null} var control = new pca.Address(fields, options); control.listen("load", function() { control.setCountry("CAN"); }); ``` ## Events and listeners The address capture library implements a simple events model which will allow you to listen out for when certain things happen. To listen for an event use the **listen** method with the event name and a function to run when that event occurs. Events can sometimes pass additional details through parameters. ```javascript theme={null} control.listen("populate", function(address, variations) { document.getElementById("myCustomField").value = address.PostalCode; }); ``` The key events to listen for are: | Event | What it means | | :- | :- | | load | The control is now ready. It has finished adding elements to the page and is now listening to page events. | | show | The control is now visible on the page. | | hide | The control has been hidden. | | search | The user is searching. You can modify the **searchTerm** and **lastId** of the search object (parameter 1) at this stage. | | results | Results have been returned from the find service. You can modify the list of suggestions returned (parameter 1) and access the extended attributes object (parameter 2) including properties such as **ContainerCount**. | | noresults | No matching results were returned from the find service. | | display | The suggestions have been shown to the user. | | select | The user has selected a suggestion. The chosen suggestion can be accessed (parameter 1). | | prepopulate | The full address has been returned from the retrieve service. The address object (parameter 1) can be accessed and modified before fields are populated, as well as full list of language variations (parameter 2) for the address. | | populate | The address fields have been populated. This is the most common event to listen for, and will allow you to populate your own fields with your own logic using the address object (parameter 1) and the list of address variations (parameter 2). | | country | The country has been changed. The selected country object (parameter 1) with **iso2**, **iso3** and **name** properties is passed through. | | manual | When the **manualEntry** option is passed through and the user selects the option to enter their address manually this event will fire. | | error | An error has occured. The error message (parameter 1) is passed through. Typically errors are not shown to the user, but can be handled manually here if needed. | ## Dynamic pages When the control loads it will need to be able to find your address fields in order to bind to the page events and listen for the user typing into the field. This becomes more tricky when working with dynamic pages and asynchronous postbacks. If the control is not loading at the correct time when your address form is rendered onto the page, you can call the **load** method on the control manually. If you are loading dynamic HTML, you can include a call to reload your previously defined control object, or include your full initialisation script as part of the HTML being rendered. ```html theme={null}