Skip to main content
API docs by Redocly

OpenAPI definition (v0)

Download OpenAPI specification:Download

Addresses

Swiss address search API

Get address by ID

Retrieves a single address by its federal address identifier (EGAID)

path Parameters
id
required
integer <int64>
Example: 100001234

Federal address identifier (EGAID)

header Parameters
X-ALPAddress-API-Version
string
Default: 1.0.0
Value: "1.0.0"

Responses

Response samples

Content type
application/json
{
  • "id": 100001234,
  • "streetName": "Bahnhofstrasse",
  • "houseNumber": "1a",
  • "postalCode": 8001,
  • "locality": "Zürich",
  • "status": "PLANNED",
  • "category": "UNCATEGORIZED",
  • "municipality": {
    }
}

Search addresses

Search for addresses using structured criteria. All parameters are optional and can be combined. At least one search criterion must be provided.

Examples:

  • Search by postal code: ?zip4=8001
  • Search by canton and locality: ?canton=ZH&localityName=Zürich
  • Search by municipality: ?municipalityName=Bern
query Parameters
zip4
integer <int32> [ 1000 .. 9999 ]
Example: zip4=8001

4-digit postal code (PLZ/NPA)

zipId
integer <int64>
Example: zipId=4000

Postal locality identifier (ONRP)

localityName
string [ 0 .. 100 ] characters
Example: localityName=Zürich

Locality name (partial match)

municipalityName
string [ 0 .. 100 ] characters
Example: municipalityName=Zürich

Municipality name (partial match)

canton
string = 2 characters
Example: canton=ZH

Canton abbreviation (2 letters)

streetName
string
Example: streetName=Rue de la Gare

Street name

addressStatus
string
Default: "REAL"
Enum: "PLANNED" "REAL" "OUTDATED"
Example: addressStatus=REAL

Address status

addressCategories
Array of strings
Default: "RESIDENTIAL"
Items Enum: "UNCATEGORIZED" "TEMPORARY" "RESIDENTIAL" "OTHER_RESIDENTIAL" "PARTLY_RESIDENTIAL" "NON_RESIDENTIAL" "SPECIAL"
Example: addressCategories=RESIDENTIAL,TEMPORARY

Address categories

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of results (1-100)

header Parameters
X-ALPAddress-API-Version
string
Default: 1.0.0
Value: "1.0.0"

Responses

Response samples

Content type
application/json
{
  • "id": 100001234,
  • "streetName": "Bahnhofstrasse",
  • "houseNumber": "1a",
  • "postalCode": 8001,
  • "locality": "Zürich",
  • "status": "PLANNED",
  • "category": "UNCATEGORIZED",
  • "municipality": {
    }
}

Autocomplete addresses

Search for addresses using full-text search with relevance scoring. Returns addresses that match the query with a relevance score above the threshold.

Examples:

  • ?query=Bahnhofstrasse Zürich
  • ?query=Bundesplatz 10&threshold=0.5
  • ?query=8001 Zürich&limit=5
query Parameters
query
required
string [ 1 .. 2147483647 ] characters
Example: query=Bahnhofstrasse Zürich

Search query for autocomplete

threshold
number <double> [ 0 .. 1 ]
Default: 0.5
Example: threshold=0.5

Minimum relevance score threshold (0.0 to 1.0)

limit
integer <int32> [ 1 .. 20 ]
Default: 10
Example: limit=10

Maximum number of results (1-20)

addressStatus
string
Default: "REAL"
Enum: "PLANNED" "REAL" "OUTDATED"
Example: addressStatus=REAL

Address status

addressCategories
Array of strings
Default: "RESIDENTIAL"
Items Enum: "UNCATEGORIZED" "TEMPORARY" "RESIDENTIAL" "OTHER_RESIDENTIAL" "PARTLY_RESIDENTIAL" "NON_RESIDENTIAL" "SPECIAL"
Example: addressCategories=RESIDENTIAL,TEMPORARY

Address categories

header Parameters
X-ALPAddress-API-Version
string
Default: 1.0.0
Value: "1.0.0"

Responses

Response samples

Content type
application/json
{
  • "id": 100001234,
  • "streetName": "Bahnhofstrasse",
  • "houseNumber": "1a",
  • "buildingName": "1a",
  • "zip4": 8001,
  • "zipa": 25,
  • "locality": "Zürich",
  • "municipality": "Zürich",
  • "canton": "VD",
  • "score": 0.85
}