Address API

Autofill completes a postal address while the user types. Validation checks an address against the official register.

Base URL: https://api.mapx.at · Rate-limit zone: search (10/s) · Guide: Search

Address Autofill: suggestions

GET /v1/autofill/suggest

Official address register only (BEV). Completes street, house number, postcode and place; fields separated in suggestions[].

Parameters

Name	In	Type	Required	Default	Description
`q`	query	string	yes	–	Partial input, e.g. `Hauptpl 3 Mel`
`session_token`	query	string		–	Session id (1 to 64 characters), echoed back
`proximity`	query	string		–	lon,lat, prefers near addresses
`limit`	query	string		`5`	1 to 10, default 5

Example

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://api.mapx.at/v1/autofill/suggest?q=Herrengasse%2013%20Wien&limit=3" | jq

Example response

{
  "session_token": "abc-1",
  "suggestions": [
    {
      "id": "address-1234567",
      "address_line1": "Hauptplatz 3",
      "street": "Hauptplatz",
      "housenumber": "3",
      "postcode": "3390",
      "place": "Melk",
      "full_address": "Hauptplatz 3, 3390 Melk",
      "coordinates": [
        15.3298,
        48.2273
      ]
    }
  ]
}

Errors (details: error catalog)

Status	Meaning
`400`	A parameter is missing or invalid
`401`	Token missing or invalid (`missing-token`, `invalid-token`, `token-expired`)
`403`	Token not allowed here (`origin-not-allowed`, `origin-missing`, `pk-not-allowed`, `app-not-allowed`, `token-blocked`, `ip-not-allowed`)
`429`	Rate limit exceeded, wait `Retry-After` seconds
`502`	Upstream service unavailable

Address Autofill: retrieve the chosen address

GET /v1/autofill/retrieve/{id}

id from suggestions[].id (address-<AdrCD>). FeatureCollection with one point feature, properties as in suggest.

Parameters

Name	In	Type	Required	Default	Description
`id`	path	string	yes	–	Address id from suggest
`session_token`	query	string		–	As in suggest

Example

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://api.mapx.at/v1/autofill/retrieve/address-7065749" | jq

Example response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          15.3298,
          48.2273
        ]
      },
      "properties": {
        "name": "Hauptplatz 3"
      }
    }
  ]
}

Errors (details: error catalog)

Status	Meaning
`400`	A parameter is missing or invalid
`401`	Token missing or invalid (`missing-token`, `invalid-token`, `token-expired`)
`403`	Token not allowed here (`origin-not-allowed`, `origin-missing`, `pk-not-allowed`, `app-not-allowed`, `token-blocked`, `ip-not-allowed`)
`404`	Not found (name, path or position)
`429`	Rate limit exceeded, wait `Retry-After` seconds

Address Validation (free text or structured)

GET /v1/address/validate

Checks an address against the official register. status: match | corrected | ambiguous | not_found. Returns the normalized address, confidence (0 to 1), deviations[] per field (kind: spelling | wrong | added), coordinate, id and adrcd. Understands Str./Straße, abbreviations, umlauts and ß.

ambiguous returns candidates[] (up to 5) instead of address.

Parameters

Name	In	Type	Default	Description
`q`	query	string	–	Free text, e.g. `Hauptstr. 12a, 3390 Melk` (or structured fields)
`street`	query	string	–	Street
`housenumber`	query	string	–	House number
`postcode`	query	string	–	Postcode
`place`	query	string	–	Place

Example

curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://api.mapx.at/v1/address/validate?q=Herrengasse%2013,%201010%20Wien" | jq

Example response

{
  "status": "corrected",
  "confidence": 0.93,
  "address": {
    "street": "Hauptstraße",
    "housenumber": "12a",
    "postcode": "3390",
    "place": "Melk"
  },
  "deviations": [
    {
      "field": "street",
      "kind": "spelling"
    }
  ],
  "id": "address-1234567",
  "coordinates": [
    15.33,
    48.23
  ]
}

Errors (details: error catalog)

Status	Meaning
`400`	A parameter is missing or invalid
`401`	Token missing or invalid (`missing-token`, `invalid-token`, `token-expired`)
`403`	Token not allowed here (`origin-not-allowed`, `origin-missing`, `pk-not-allowed`, `app-not-allowed`, `token-blocked`, `ip-not-allowed`)
`429`	Rate limit exceeded, wait `Retry-After` seconds
`502`	Upstream service unavailable

Address Validation (JSON body)

POST /v1/address/validate

Same as GET with the fields in a JSON object (q or street, housenumber, postcode, place). At most 16 KB.

Request body (JSON)

{
  "street": "Hauptstr.",
  "housenumber": "12a",
  "postcode": "3390"
}

Example

curl -s -X POST "https://api.mapx.at/v1/address/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"street":"Hauptstr.","housenumber":"12a","postcode":"3390"}' | jq

const res = await fetch("https://api.mapx.at/v1/address/validate", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({
    "street": "Hauptstr.",
    "housenumber": "12a",
    "postcode": "3390"
  }),
});
const data = await res.json();

import requests

res = requests.post("https://api.mapx.at/v1/address/validate", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={
    "street": "Hauptstr.",
    "housenumber": "12a",
    "postcode": "3390"
  })
data = res.json()

Example response

{
  "status": "corrected",
  "confidence": 0.93,
  "address": {
    "street": "Hauptstraße",
    "housenumber": "12a",
    "postcode": "3390",
    "place": "Melk"
  },
  "deviations": [
    {
      "field": "street",
      "kind": "spelling"
    }
  ],
  "id": "address-1234567",
  "coordinates": [
    15.33,
    48.23
  ]
}

Errors (details: error catalog)

Status	Meaning
`400`	A parameter is missing or invalid
`401`	Token missing or invalid (`missing-token`, `invalid-token`, `token-expired`)
`403`	Token not allowed here (`origin-not-allowed`, `origin-missing`, `pk-not-allowed`, `app-not-allowed`, `token-blocked`, `ip-not-allowed`)
`429`	Rate limit exceeded, wait `Retry-After` seconds
`502`	Upstream service unavailable

Playground

curl

The response appears here.

Search Box API Directions API