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

> Break a free-text address into structured components (house number, road, city, state, postcode, country). Use this to normalise messy address data before passing it to structured search, or to understand what parts of an address were recognised.



## OpenAPI

````yaml GET /v1/geocoding/parse
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/geocoding/parse:
    get:
      tags:
        - Geocoding
      summary: Parse a free-text address into components
      description: >-
        Break a free-text address into structured components (house number,
        road, city, state, postcode, country). Use this to normalise messy
        address data before passing it to structured search, or to understand
        what parts of an address were recognised.
      operationId: geocodingParse
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
          description: Free-text address to parse
      responses:
        '200':
          description: Parsed address components
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingParseResponse'
              examples:
                uk_address:
                  summary: UK address
                  value:
                    input: 10 Downing Street, London SW1A 2AA, United Kingdom
                    components:
                      house_number: '10'
                      road: Downing Street
                      city: London
                      postcode: SW1A 2AA
                      country: United Kingdom
                us_address:
                  summary: US address
                  value:
                    input: 1600 Pennsylvania Avenue NW, Washington, DC 20500
                    components:
                      house_number: '1600'
                      road: Pennsylvania Avenue NW
                      city: Washington
                      state: DC
                      postcode: '20500'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Geocoding engine unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GeocodingParseResponse:
      type: object
      required:
        - input
        - components
      properties:
        input:
          type: string
          description: The original input text
        components:
          type: object
          description: >-
            Parsed address components. Only fields that were detected are
            included.
          properties:
            house_number:
              type: string
            road:
              type: string
            neighbourhood:
              type: string
            city:
              type: string
            county:
              type: string
            state:
              type: string
            postcode:
              type: string
            country:
              type: string
    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

````