Address Parsing and Standardization Prompt Template

This prompt is designed for logistics, CRM, and data engineering teams that need to convert free-text address strings—often generated by upstream models or extracted from unstructured documents—into a clean, structured object with predictable fields. The primary job-to-be-done is post-generation repair and normalization: taking a messy, inconsistent address string and producing a valid, standardized record with components like street, city, region, postal code, and country. The ideal user is a developer or data pipeline operator who already has an address string but cannot trust its format, completeness, or field ordering. You should use this prompt when the address content is present but structurally unreliable, not when the address is entirely missing or must be verified against a ground-truth database.

This prompt is not a replacement for a dedicated address validation API (such as Google Maps, Smarty, or Lob). It does not verify that an address physically exists, correct wrong house numbers, or append missing postal codes from a reference dataset. It operates purely on the string provided. Use it when you need fast, schema-conformant structuring before ingestion into a CRM, shipping label generator, or customer record. Do not use it for legal proof of address, geocoding, or any workflow where an incorrect but well-formatted address could cause a material failure (e.g., mailing compliance, emergency services). In those cases, this prompt should feed into a human review step or a downstream verification API.

Before wiring this into production, define your canonical address schema and decide which fields are required versus optional. International addresses vary widely: some regions lack postal codes, others use provinces instead of states, and many place the building number after the street name. The prompt includes a [CONSTRAINTS] placeholder where you can inject locale-specific rules, field requirements, and formatting standards (e.g., ISO 3166 country codes, uppercase postal codes). If your pipeline handles multiple countries, consider routing to locale-specific prompt variants or including few-shot examples for each target format. Start with a small eval set of 50–100 real addresses from your system, including edge cases like PO boxes, rural routes, apartment designators, and non-Latin scripts, and measure field-level accuracy before scaling.

The prompt below takes a raw address string—often generated by an upstream model that produced free text instead of structured JSON—and parses it into a consistent, validated address object. It is designed for logistics and CRM repair loops where the upstream output is semantically correct but structurally unusable. The template uses square-bracket placeholders so you can inject your own input, output schema, constraints, and examples without rewriting the core instruction.

textCopy
You are an address normalization engine. Your job is to parse a free-text address into a structured JSON object. You must not invent, infer, or hallucinate any field that is not present in the input. If a component is missing, set its value to null. If the input is ambiguous, flag it in the `warnings` array rather than guessing.

INPUT:
[INPUT]

OUTPUT_SCHEMA:
[OUTPUT_SCHEMA]

CONSTRAINTS:
[CONSTRAINTS]

EXAMPLES:
[EXAMPLES]

Return ONLY valid JSON. Do not include markdown fences, explanations, or any text outside the JSON object.

To adapt this template, replace [INPUT] with the raw address string from your upstream model. Set [OUTPUT_SCHEMA] to your target JSON structure—at minimum include street, city, region, postal_code, and country fields, plus a warnings array for ambiguity flags. Use [CONSTRAINTS] to specify locale-specific rules such as 'postal_code must match the format for [COUNTRY]' or 'PO Box addresses must populate the po_box field instead of street'. Provide 3–5 [EXAMPLES] that cover common cases, edge cases like rural routes and international formats, and failure cases where the model should return null fields with warnings. After copying the template, run it through your validation harness before deploying—address repair is high-stakes when downstream systems depend on correct routing, compliance checks, or customer communications.

Integrating the address parsing prompt into an application requires more than a single API call. The harness must handle malformed inputs, validate the model's output against a strict schema, and decide when to retry, repair, or escalate. For address standardization, the most common failure modes are missing required fields (like postal code or country), hallucinated components not present in the input, and format violations that break downstream geocoding or label printing systems. A robust harness treats the prompt as one step in a pipeline that includes pre-processing, post-validation, and a retry loop with escalating interventions.

Start by defining a strict output schema. The prompt should return a JSON object with fields such as street_number, street_name, unit_type, unit_number, city, state_province, postal_code, country, and a confidence score per field. In your application code, validate this output immediately: check that country is a valid ISO 3166-1 alpha-2 code, that postal_code matches a regex for the claimed country, and that required fields like city and street_name are non-empty strings. If validation fails, do not discard the output. Instead, construct a repair prompt that includes the original input, the failed output, and the specific validation errors. This repair prompt should instruct the model to fix only the invalid fields while preserving the valid ones. Limit repair attempts to two retries. If the output still fails validation after two repair passes, log the record for human review and return a partial result with an unresolved_fields array so the downstream system can decide whether to proceed with incomplete data.

For high-throughput pipelines processing thousands of addresses, batch the inputs and run validation in parallel. Use a model with low latency for the initial parse (such as a smaller fine-tuned model or a fast API endpoint) and reserve a more capable model for the repair step on the small fraction of records that fail validation. Log every parse attempt—including the raw model response, validation errors, and repair outcomes—so you can measure field-level accuracy, hallucination rates, and repair success over time. This log becomes your evaluation dataset for testing prompt changes. Before deploying any prompt update, replay a sample of production failures through the new prompt and compare repair rates and accuracy against the current baseline. If the new prompt introduces regressions on international addresses or PO box handling, revert and iterate before releasing.