> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse Address

> Parse, correct, and standardize addresses using AI. Fixes typos, expands abbreviations, infers missing components (postcode, region, country), and returns structured address components with a confidence score. Each correction is itemised so you can see exactly what changed.

Send messy, incomplete, or malformed addresses and get back clean, structured, corrected results. Every correction is itemised so you can see exactly what changed and why.

## What it corrects

| Correction type | Example                                                     |
| --------------- | ----------------------------------------------------------- |
| `typo`          | "Main Stret" to "Main Street"                               |
| `abbreviation`  | "downing st" to "Downing Street", "uk" to "United Kingdom"  |
| `inferred`      | Missing postcode, region, or country filled in from context |
| `reformatted`   | "apt 4b" to "Apt 4B" (capitalization, formatting)           |
| `removed`       | Duplicate or irrelevant fragments stripped out              |

## When to use this vs. `/parse`

The standard [/parse](/api/endpoint/parse) endpoint is a deterministic parser. It breaks an address into components but doesn't correct errors or fill gaps.

`/ai/parse-address` uses AI to understand what the address *should* be. Use it when:

* Your input has typos or misspellings
* Address fields are missing (no postcode, no country)
* You're processing user-submitted data that hasn't been validated
* You need confidence scores for data quality assessment
* You want to standardize formatting across a dataset

## Batch processing

Send up to 100 addresses per request. Each result includes the original index so you can match results back to your input:

```json theme={null}
{
  "addresses": [
    { "text": "123 Main Stret, new york" },
    { "text": "10 downing st, london, uk" },
    { "text": "buckingham palace" }
  ]
}
```

For more than 100 addresses, split into multiple requests.

## Country hints

Pass `country` on individual addresses to improve accuracy, especially for ambiguous inputs:

```json theme={null}
{
  "addresses": [
    { "text": "123 Main Street", "country": "USA" },
    { "text": "123 Main Street", "country": "GBR" }
  ]
}
```

The same input with different country hints can produce different results (different postcodes, regions, formatting conventions).

## Confidence scores

Each result has a `confidence` score from 0 to 1:

| Range     | Meaning                                                                 |
| --------- | ----------------------------------------------------------------------- |
| 0.9 - 1.0 | High confidence. Input was clean or corrections are well-supported.     |
| 0.7 - 0.9 | Moderate confidence. Some inference was needed. Review recommended.     |
| 0.5 - 0.7 | Low confidence. Significant guessing involved. Manual review suggested. |
| Below 0.5 | Very low confidence. Input may be too ambiguous to correct reliably.    |


## OpenAPI

````yaml POST /v1/ai/parse-address
openapi: 3.1.0
info:
  title: Footstep API
  description: >-
    Terrain-intelligent routing, geocoding, elevation, and spatial analysis.
    Every routing response includes terrain analytics by default. Routing
    endpoints support two response formats: footstep (default, compact) and
    geojson (standard GeoJSON).
  version: 1.0.0
servers:
  - url: https://api.footstep.ai
    description: Production
security:
  - apiKey: []
paths:
  /v1/ai/parse-address:
    post:
      tags:
        - AI
      summary: Correct and structure messy addresses
      description: >-
        Parse, correct, and standardize addresses using AI. Fixes typos, expands
        abbreviations, infers missing components (postcode, region, country),
        and returns structured address components with a confidence score. Each
        correction is itemised so you can see exactly what changed.
      operationId: aiParseAddress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIParseAddressRequest'
            examples:
              messy:
                summary: Typos and missing fields
                value:
                  addresses:
                    - text: 123 Main Stret, apt 4b, new york
                    - text: 10 downing st, london, uk
              with_country:
                summary: With country hint
                value:
                  addresses:
                    - text: buckingham palace
                      country: GBR
      responses:
        '200':
          description: Corrected and structured addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIParseAddressResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: AI engine unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AIParseAddressRequest:
      type: object
      required:
        - addresses
      properties:
        addresses:
          type: array
          minItems: 1
          maxItems: 100
          description: Addresses to parse and correct
          items:
            type: object
            required:
              - text
            properties:
              text:
                type: string
                description: Free-text address (can be messy, incomplete, or contain typos)
              country:
                type: string
                description: >-
                  ISO 3166-1 alpha-3 country code hint to improve parsing
                  accuracy
    AIParseAddressResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            type: object
            required:
              - index
              - input
              - corrected
              - components
              - corrections
              - confidence
            properties:
              index:
                type: integer
                description: Position in the input array
              input:
                type: string
                description: Original input text
              corrected:
                type: string
                description: Standardized, corrected full address
              components:
                type: object
                description: Structured address components
                properties:
                  house_number:
                    type: string
                  unit:
                    type: string
                    description: Apartment, suite, floor, etc.
                  road:
                    type: string
                  neighbourhood:
                    type: string
                  locality:
                    type: string
                    description: City or town
                  county:
                    type: string
                  region:
                    type: string
                    description: State, province, or region
                  postcode:
                    type: string
                  country:
                    type: string
                  country_code:
                    type: string
                    description: ISO 3166-1 alpha-3
              corrections:
                type: array
                description: List of corrections applied. Empty array if input was clean.
                items:
                  type: object
                  required:
                    - field
                    - type
                    - corrected
                  properties:
                    field:
                      type: string
                      description: Which component was corrected
                    original:
                      type: string
                      nullable: true
                      description: Original value (null if inferred from nothing)
                    corrected:
                      type: string
                      description: Corrected or inferred value
                    type:
                      type: string
                      enum:
                        - typo
                        - abbreviation
                        - inferred
                        - reformatted
                        - removed
                      description: What kind of correction was applied
              confidence:
                type: number
                minimum: 0
                maximum: 1
                description: Confidence in the corrected result (0-1)
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Footstep API key

````