Loqate CLI

Verify addresses, emails, and phone numbers against Loqate's APIs.
Get confidence scores, policy-aware recommendations, and full auditability — in one command.
Real-time verification decisioning for agents that need to know whether contact data is good enough for the job.
Part of GBG Reach.

lqt verify  ·  lqt parse  ·  lqt mcp

Install

macOS

# Apple Silicon (M1/M2/M3/M4)
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# Intel
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Linux

# x86_64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# ARM64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Windows

1. Download lqt_windows_amd64.zip from the latest release
2. Extract lqt.exe
3. Move it to a directory on your PATH, or run it directly

Verify Installation

lqt version

All Downloads

See Releases for all versions and platforms. Each release includes SHA-256 checksums.

Quick Start

API Keys

You need a Loqate API key for verification. Optionally, an Anthropic API key for the parse command.

macOS / Linux:

export LOQATE_API_KEY=your-key-here

# Optional — for lqt parse
export ANTHROPIC_API_KEY=your-key-here

Windows (PowerShell):

$env:LOQATE_API_KEY="your-key-here"

# Optional — for lqt parse
$env:ANTHROPIC_API_KEY="your-key-here"

Your First Verification

macOS / Linux:

# Verify an address
lqt verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
lqt verify -a "10 Downing St, London, GB" \
           -e "pm@gov.uk" \
           -p "+442071234567" \
           --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
lqt parse --address "125 summer street boston ma 02110 us"

Windows (PowerShell):

# Verify an address
.\lqt.exe verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
.\lqt.exe verify -a "10 Downing St, London, GB" -e "pm@gov.uk" -p "+442071234567" --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
.\lqt.exe parse --address "125 summer street boston ma 02110 us"

Commands

verify

Verify addresses, emails, and/or phone numbers against Loqate's APIs. Returns a confidence score and a policy-driven recommendation (accept, review, or reject).

lqt verify [flags]

Flags:

Examples:

# Simple address verification
lqt verify -a "1600 Amphitheatre Parkway, Mountain View, CA 94043, US"

# Multi-field verification with strict policy
lqt verify -a "221B Baker St, London, GB" \
           -e "sherlock@example.com" \
           -p "+442071234567" \
           --policy strict

# JSON output for piping to other tools
lqt verify -a "10 Downing St, London, GB" -o json | jq '.address.confidence'

# Extended input fields
lqt verify -a "125 Summer St" --field Organization="Acme Corp" --field Building="Suite 200"

# API options (dot notation for nesting)
lqt verify -a "125 Summer St, Boston, MA 02110, US" --option GeoCode=true

Full list of input fields and API options: Loqate International Batch Cleanse API

parse

Parse and standardize contact data using Claude (Haiku). Extracts address components, validates email syntax, and normalizes phone numbers with awareness of 250+ country-specific postal formats. No Loqate API calls — no credits spent.

lqt parse [flags]

Flags:

Examples:

# Parse a messy address into structured components
lqt parse -a "125 summer street boston ma 02110 us"

# Parse address + validate email + normalize phone
lqt parse -a "10 downing st london" -e "test@mailinator.com" -p "02071234567"

# Batch parse from CSV
lqt parse --batch messy-data.csv --output json

policy

List, inspect, and validate verification policies.

lqt policy list                  # List all built-in policies
lqt policy show <name>           # Show full JSON for a policy
lqt policy validate <file>       # Validate a custom policy JSON file

mcp

Start an MCP (Model Context Protocol) server. Exposes LQT as tools for AI agents.

lqt mcp                    # Stdio transport (launched by clients)
lqt mcp --http :8080       # HTTP transport (deployed as a service)
lqt mcp --smoke-test       # Verify the server starts correctly and exit

Flags:

Policies

Policies control what gets accepted, reviewed, or rejected. Every verification runs through a policy — there are no hardcoded thresholds.

Custom Policies

Create a JSON file:

{
  "name": "my-custom-policy",
  "description": "Tuned for my use case",
  "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
  }
}

lqt policy validate my-policy.json    # Validate first
lqt verify -a "..." --policy-file my-policy.json

Batch Processing

Process files with address, email, and phone columns. Supports comma, tab, and pipe delimited input.

# CSV (auto-detected)
lqt verify --batch addresses.csv --policy shipping -o json > results.json

# Tab-delimited
lqt verify --batch addresses.tsv -o json

# Pipe-delimited
lqt verify --batch addresses.txt --delimiter pipe -o json

# From stdin
cat addresses.csv | lqt verify --batch - --policy standard

# With summary statistics
lqt verify --batch addresses.csv --summary

Windows (PowerShell):

.\lqt.exe verify --batch addresses.csv --policy shipping -o json > results.json
Get-Content addresses.csv | .\lqt.exe verify --batch - --policy standard

Delimiters

Auto-detected from the first line. Override explicitly with --delimiter:

Supported Columns

Use a single address column or structured fields — or both. All column names are case-insensitive. Every field from the Loqate International Batch Cleanse API is supported.

Address lines:

Geography:

Street / building / premise:

Organization / postal:

Contact / person:

Non-address fields:

Example CSV

address,email,phone,country
"125 Summer St, Boston, MA 02110",user@example.com,+16175551234,US
"10 Downing St, London",pm@gov.uk,+442071234567,GB

MCP Integration

The lqt mcp command exposes LQT as tools for AI agents via the Model Context Protocol. Connecting the MCP server also provides a built-in usage guide prompt that teaches the AI how to use the tools effectively.

Claude Code / Cursor

Add to your project's .mcp.json:

{
  "mcpServers": {
    "loqate": {
      "command": "lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

Add to Claude Desktop's MCP settings:

{
  "mcpServers": {
    "lqt": {
      "command": "/usr/local/bin/lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Remote HTTP

Deploy lqt mcp --http as a service:

{
  "mcpServers": {
    "loqate": {
      "url": "https://lqt.your-company.com/mcp"
    }
  }
}

In HTTP mode, clients can pass API keys per-request via the key field in tool arguments.

Hosted deployments may disable custom verify endpoints for security. If you receive a CUSTOM_ENDPOINT_DISABLED error, use the server's default endpoint — do not pass verify_url or verify_key in your tool arguments.

Available Tools

9 tools in stdio mode, 6 in HTTP mode (tools marked stdio mode only are not available over HTTP).

Exit Codes

Designed for scripting and CI/CD:

macOS / Linux:

lqt verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
case $? in
  0) echo "Ship it" ;;
  1) echo "Queue for review" ;;
  2) echo "Bad address" ;;
  3) echo "Something broke" ;;
esac

Windows (PowerShell):

.\lqt.exe verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
switch ($LASTEXITCODE) {
  0 { Write-Host "Ship it" }
  1 { Write-Host "Queue for review" }
  2 { Write-Host "Bad address" }
  3 { Write-Host "Something broke" }
}

API Keys

Loqate API Key (for verify)

macOS / Linux:

# Environment variable
export LOQATE_API_KEY=your-key-here

# Key file (add to .gitignore)
echo "your-key-here" > .loqate-key

# Per-command flag
lqt verify -a "..." --key your-key-here

Windows (PowerShell):

# Current session
$env:LOQATE_API_KEY="your-key-here"

# Persistent (survives restarts)
[System.Environment]::SetEnvironmentVariable("LOQATE_API_KEY", "your-key-here", "User")

# Per-command flag
.\lqt.exe verify -a "..." --key your-key-here

Anthropic API Key (for parse)

macOS / Linux:

export ANTHROPIC_API_KEY=your-key-here

Windows (PowerShell):

$env:ANTHROPIC_API_KEY="your-key-here"

Resolution order: flag > environment variable > key file

Custom Verify Endpoint (optional)

If you need to route address verification through a different endpoint (e.g., an on-premises or partner-hosted Loqate instance):

macOS / Linux:

# Environment variables
export LOQATE_VERIFY_URL=https://custom-verify.example.com/v1/batch
export LOQATE_VERIFY_KEY=your-custom-key

# Or use flags (override env vars)
lqt verify -a "..." --verify-url https://custom-verify.example.com/v1/batch --verify-key your-custom-key

Windows (PowerShell):

$env:LOQATE_VERIFY_URL="https://custom-verify.example.com/v1/batch"
$env:LOQATE_VERIFY_KEY="your-custom-key"

Resolution order: flag > environment variable > default Loqate endpoint

When --verify-key is set, the standard --key / LOQATE_API_KEY is not required for address-only verification. If you also verify email (-e) or phone (-p), the standard key is still needed for those.

These flags only affect address verification. Email and phone always use the standard Loqate endpoints.

In MCP mode, clients can pass verify_url and verify_key per-request in verify_address and verify_contact tool inputs.

Support

• Bug reports & feature requests — open an issue
• Security vulnerabilities — please email labs@gbg.com instead of opening a public issue
• General questions — start a discussion or open an issue

When reporting a bug, please include:

• lqt version (lqt --version)
• OS and architecture (e.g., macOS ARM64, Linux x86_64)
• The command you ran (redact any API keys)
• Expected vs actual behavior

Built by GBG.