Skip to main content
POST
/
v1
/
ai
/
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
    }
  ]
}
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 typeExample
typo”Main Stret” to “Main Street”
abbreviation”downing st” to “Downing Street”, “uk” to “United Kingdom”
inferredMissing postcode, region, or country filled in from context
reformatted”apt 4b” to “Apt 4B” (capitalization, formatting)
removedDuplicate 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:
RangeMeaning
0.9 - 1.0High confidence. Input was clean or corrections are well-supported.
0.7 - 0.9Moderate confidence. Some inference was needed. Review recommended.
0.5 - 0.7Low confidence. Significant guessing involved. Manual review suggested.
Below 0.5Very 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

Response

Corrected and structured addresses

​
results
object[]
required