Parse Address

curl --request POST \
  --url https://api.footstep.ai/v1/ai/parse-address \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "addresses": [
    {
      "text": "123 Main Stret, apt 4b, new york"
    },
    {
      "text": "10 downing st, london, uk"
    }
  ]
}
'

{
  "results": [
    {
      "index": 123,
      "input": "<string>",
      "corrected": "<string>",
      "components": {
        "house_number": "<string>",
        "unit": "<string>",
        "road": "<string>",
        "neighbourhood": "<string>",
        "locality": "<string>",
        "county": "<string>",
        "region": "<string>",
        "postcode": "<string>",
        "country": "<string>",
        "country_code": "<string>"
      },
      "corrections": [
        {
          "field": "<string>",
          "corrected": "<string>",
          "type": "typo",
          "original": "<string>"
        }
      ],
      "confidence": 0.5
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

parse-address

curl --request POST \
  --url https://api.footstep.ai/v1/ai/parse-address \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "addresses": [
    {
      "text": "123 Main Stret, apt 4b, new york"
    },
    {
      "text": "10 downing st, london, uk"
    }
  ]
}
'

{
  "results": [
    {
      "index": 123,
      "input": "<string>",
      "corrected": "<string>",
      "components": {
        "house_number": "<string>",
        "unit": "<string>",
        "road": "<string>",
        "neighbourhood": "<string>",
        "locality": "<string>",
        "county": "<string>",
        "region": "<string>",
        "postcode": "<string>",
        "country": "<string>",
        "country_code": "<string>"
      },
      "corrections": [
        {
          "field": "<string>",
          "corrected": "<string>",
          "type": "typo",
          "original": "<string>"
        }
      ],
      "confidence": 0.5
    }
  ]
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

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 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:

{
  "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:

{
  "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.

Authorizations

x-api-key

string

header

required

Your Footstep API key

Body

application/json

addresses

object[]

required

Addresses to parse and correct

Required array length: 1 - 100 elements

Show child attributes

Response

Corrected and structured addresses

results

object[]

required

Show child attributes

Routing

Geocoding

Natural Language

Predict

What it corrects

When to use this vs. `/parse`

Batch processing

Country hints

Confidence scores

Authorizations

Body

Response

​What it corrects

​When to use this vs. /parse

​Batch processing

​Country hints

​Confidence scores

Authorizations

Body

Response

What it corrects

When to use this vs. `/parse`

Batch processing

Country hints

Confidence scores