Entity Canonicalization Prompt for Address Data

This prompt is designed for logistics, data quality, and ETL teams who need to convert raw, unstructured, or partially structured address strings into a canonical postal format. The primary job-to-be-done is to create a consistent, machine-readable address record that downstream systems can consume without manual intervention. Use it when your pipeline requires standardized fields for geocoding, shipping label generation, master data management, or duplicate detection. The prompt is built to handle country-specific formatting rules, PO boxes, rural routes, apartment and suite designators, and missing address components, making it suitable for global address corpora where a one-size-fits-all regex approach fails.

The ideal user is a data engineer or integration developer who is building an automated ETL pipeline and needs a reliable normalization step before data lands in a system of record. You should use this prompt when you have already extracted an address string from a source document (e.g., a PDF, email, or web form) and now need to parse and standardize it. The prompt requires you to provide the raw address string and, optionally, a target country code or formatting standard (like USPS, Royal Mail, or UPU) as context. It returns a structured JSON object with canonicalized fields (street number, street name, unit, city, state, postal code, country) and a confidence score for each field, enabling your pipeline to make an automated commit-or-review decision.

Do not use this prompt as a geocoding service; it normalizes text, it does not return coordinates. It is also not a substitute for a real-time address validation API when you need to verify deliverability against an official postal database. The prompt is best applied in batch processing or data cleaning workflows where you have a backlog of messy addresses. For high-risk applications like shipping label generation, always route records with low confidence scores to a human review queue. The next step after reading this section is to copy the prompt template, adapt the output schema to match your downstream database contract, and wire it into a validation harness that checks for schema compliance and confidence thresholds before committing any record.

This template is designed to be copied directly into your prompt management system, IDE, or orchestration layer. It accepts a raw address string and a target country code, then returns a structured, canonical address record. Every variable is enclosed in square brackets—replace them with your application's values at runtime. The prompt enforces a strict JSON output schema, handles partial addresses, and requires the model to score its confidence in each component rather than silently guessing.

textCopy
You are an address canonicalization engine. Your task is to normalize the provided address into a standard postal format for the specified country. You must handle partial addresses, PO boxes, rural routes, and ambiguous components. Do not invent missing information. For every address component you return, provide a confidence score between 0.0 and 1.0.

INPUT ADDRESS:
[RAW_ADDRESS]

TARGET COUNTRY (ISO 3166-1 alpha-2):
[COUNTRY_CODE]

OUTPUT SCHEMA (strict JSON):
{
  "canonical_address": {
    "recipient_line": string | null,
    "building_number": string | null,
    "street_name": string | null,
    "unit_type": string | null,
    "unit_number": string | null,
    "po_box": string | null,
    "rural_route": string | null,
    "locality": string | null,
    "administrative_area": string | null,
    "postal_code": string | null,
    "country_code": string
  },
  "component_confidence": {
    "recipient_line": number,
    "building_number": number,
    "street_name": number,
    "unit_type": number,
    "unit_number": number,
    "po_box": number,
    "rural_route": number,
    "locality": number,
    "administrative_area": number,
    "postal_code": number
  },
  "normalization_notes": [string],
  "is_complete_address": boolean
}

CONSTRAINTS:
[CONSTRAINTS]

EXAMPLES:
[EXAMPLES]

Adaptation guidance: Replace [RAW_ADDRESS] with the extracted or user-provided address string. [COUNTRY_CODE] should be a two-letter ISO code (e.g., US, DE, JP) to trigger country-specific formatting rules. Use [CONSTRAINTS] to inject business rules such as 'If the postal code is missing, set is_complete_address to false and add a normalization note.' The [EXAMPLES] placeholder should be populated with 2–4 few-shot examples showing correct handling of PO boxes, rural routes, and partial addresses for your target countries. If your application requires a different output schema (e.g., a single address_line_1 field), modify the JSON structure before deploying, but keep the component-level confidence scores to enable downstream routing decisions.

Next step: After copying this template, wire it into your application harness with a JSON validator that rejects malformed responses. Define a confidence threshold for each component—addresses with postal_code confidence below 0.8 should route to a human review queue rather than being ingested directly into your shipping or billing system. Test the prompt against a golden dataset of 50–100 addresses that includes edge cases like rural routes, multi-unit buildings, and addresses with missing locality fields before promoting to production.

The address canonicalization prompt is rarely a standalone call. In production, it sits inside a pipeline that feeds raw address strings from source systems—CRM records, shipping labels, OCR output, or user-submitted forms—and expects normalized, validated payloads that downstream systems can consume without crashing. The harness wraps the model call in pre-processing, post-processing, validation, and escalation logic. The goal is not just a well-formatted address but a trustworthy one: every field that enters your master data store should have a known confidence level and a clear provenance trail.

Start by defining a strict output schema and validating it before any record reaches a database. Use a JSON Schema validator or a library like Pydantic to enforce that canonical_address contains required fields (street_number, street_name, city, state_province, postal_code, country_code), that confidence_scores is present for each component, and that normalization_notes is a non-empty array when the model changed the input. If validation fails, do not silently drop the record. Log the raw input, the malformed output, and the validation error, then route to a repair queue. A common failure mode is the model returning a well-structured address that violates the postal format for the claimed country—for example, a US ZIP+4 pattern applied to a UK postcode. Add a country-specific format validator as a second pass: regex checks for postal codes, state/province abbreviation lookups, and city-postal code consistency checks against a reference dataset.

Confidence thresholds should drive routing, not just annotation. When the model's overall_confidence falls below a configurable threshold (start with 0.85 and tune based on your error tolerance), route the record to a human review queue rather than inserting it directly. For partial addresses—missing street numbers, ambiguous city names, or PO Box-only inputs—the model should still produce its best guess, but the harness must flag these for review. Implement a retry strategy for transient failures: if the model call times out or returns unparseable output, retry once with the same prompt. If the retry also fails, log the failure and escalate. Do not retry more than twice; at that point, the input is likely adversarial or fundamentally uncanonicalizable, and repeated retries waste tokens and latency budget.

Model choice matters for this workload. Address canonicalization requires geographic knowledge and pattern recognition more than creative reasoning. Smaller, faster models (Claude Haiku, GPT-4o-mini, or fine-tuned open-weight models) often perform well here and reduce cost per record. If you are processing high volumes—millions of addresses—consider batching multiple addresses into a single prompt with a JSON array output to amortize prompt overhead, but keep batches small (5–10 addresses) to avoid the model confusing records. Log every call: input address, output canonical form, confidence scores, model version, prompt version, timestamp, and latency. This audit trail is essential for debugging normalization drift when the model provider updates their serving infrastructure or when your prompt changes.

Finally, treat the canonicalization prompt as one step in a larger data quality workflow. After canonicalization, run deduplication against your existing address master to merge near-duplicates. Use the canonical_address fields as matching keys, but also fuzzy-match on the original input to catch cases where the model normalized two variants of the same address differently. If your downstream system is a shipping API, validate the canonicalized address against the carrier's address verification endpoint before accepting it as ground truth. The prompt is the engine; the harness is the steering, brakes, and dashboard. Ship neither without the other.