API docs by Redocly

HelvAddress API (1.0.0)

Download OpenAPI specification:

HelvAddress API Support: api@helvaddress.ch URL: https://www.helvaddress.ch/support License: Commercial License Terms of Service

HelvAddress is a professional Swiss address validation and search API.

Overview

This API provides comprehensive access to official Swiss address data from the Federal Register of Buildings and Dwellings (RBD/GWR). It supports address lookup, autocomplete with relevance scoring, and address normalization/validation.

Key Features

  • Address Search: Structured search by postal code, locality, cantonAbbreviation, municipality
  • Autocomplete: Real-time full-text search optimized for typeahead interfaces
  • Normalization: Parse and validate freeform addressResponses against official data
  • Complete Coverage: All Swiss addressResponses including all 26 cantons

Data Source

Data is sourced from the official Swiss Federal Statistical Office (BFS) building and dwelling register, updated regularly to ensure accuracy.

Rate Limits

API requests are rate-limited based on your subscription plan. Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Maximum requests per time window
  • X-RateLimit-Remaining: Remaining requests in current window
  • Retry-After: Seconds until reset (when rate limited)

Error Handling

All errors return a consistent JSON format with the following fields:

  • timestamp: ISO 8601 timestamp
  • status: HTTP status code
  • error: HTTP status reason
  • message: Human-readable error description
  • path: Request path that caused the error
  • validationErrors: Array of field-level validation errors (if applicable)

Authentication

OAuth 2.0 token endpoint for obtaining access tokens

Token Endpoint

Obtain an access token by presenting an authorization grant or refresh token.

Supported Grant Types

Authorization Code (authorization_code)

Exchange an authorization code for tokens. Required parameters:

  • code: The authorization code received from the authorize endpoint
  • redirect_uri: Must match the original redirect_uri
  • code_verifier: PKCE code verifier (for public clients)

Refresh Token (refresh_token)

Exchange a refresh token for a new access token. Required parameters:

  • refresh_token: A valid refresh token

Client Credentials (client_credentials)

Obtain an access token using client credentials only. Required parameters:

  • Client authentication (see below)
  • scope: Optional scope restriction

Client Authentication

Clients must authenticate using one of:

  • HTTP Basic Authentication: Authorization: Basic base64(client_id:client_secret)
  • POST body: client_id and client_secret in request body
Authorizations:
basicAuthNone
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "authorization_code" "refresh_token" "client_credentials"

The type of grant being used to obtain the token.

code
string

The authorization code received from the authorization endpoint. Required for authorization_code grant type.

redirect_uri
string <uri>

The redirect URI used in the authorization request. Required for authorization_code grant type.

code_verifier
string

PKCE code verifier. Required for public clients using authorization code flow. Must be the original random string used to generate the code_challenge.

refresh_token
string

The refresh token issued during a previous token request. Required for refresh_token grant type.

scope
string

Space-delimited list of scopes. For refresh_token grant, the requested scope must be equal to or a subset of the original scope.

client_id
string

The client identifier. Required if not using HTTP Basic authentication.

client_secret
string

The client secret. Required for confidential clients not using other authentication methods.

Responses

Response Schema: application/json
access_token
required
string

The access token issued by the authorization server. Use this token in the Authorization header when making API requests.

token_type
required
string

The type of token issued. Always "Bearer".

expires_in
integer

The lifetime in seconds of the access token. After this time, the token will no longer be accepted.

refresh_token
string

The refresh token, which can be used to obtain new access tokens without re-authentication.

scope
string

The scope of the access token. May be a subset of the requested scope.

Request samples

Content type
application/x-www-form-urlencoded
Example

Server-to-server authentication

grant_type=client_credentials&client_id=my-service-app&client_secret=service-secret&scope=address%3Aread%20address%3Aautocomplete

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "8xLOxBtZp8",
  • "scope": "address:read address:autocomplete"
}

Cantons

Swiss cantons API.

This API provides access to the 26 Swiss cantons (Kantone/Cantons). Each cantonAbbreviation has a unique two-letter abbreviation according to ISO 3166-2:CH.

Data Source: Federal Statistical Office (FSO/BFS)

List all cantons

Retrieves all 26 Swiss cantons ordered alphabetically by their abbreviation.

Available Cantons: AG, AI, AR, BE, BL, BS, FR, GE, GL, GR, JU, LU, NE, NW, OW, SG, SH, SO, SZ, TG, TI, UR, VD, VS, ZG, ZH

Authorizations:
bearerAuth
query Parameters
page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

All cantons

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 26,
  • "totalPages": 3
}

Get cantonAbbreviation by abbreviation

Retrieves a single cantonAbbreviation by its official two-letter abbreviation.

The abbreviation is case-insensitive (e.g., "zh", "ZH", and "Zh" all work).

Authorizations:
bearerAuth
path Parameters
abbreviation
required
string
Enum: "ZH" "BE" "LU" "UR" "SZ" "OW" "NW" "GL" "ZG" "FR" "SO" "BS" "BL" "SH" "AR" "AI" "SG" "GR" "AG" "TG" "TI" "VD" "VS" "NE" "GE" "JU"
Example: ZH

Two-letter cantonAbbreviation abbreviation (ISO 3166-2:CH)

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

Responses

Response Schema: application/json
cantonId
integer <int32> [ 1 .. 26 ]

Official canton number assigned by the Federal Statistical Office

abbreviation
string = 2 characters ^[A-Z]{2}$

Official two-letter canton abbreviation (ISO 3166-2:CH)

nameDe
string <= 30 characters

Canton name in German

nameFr
string <= 30 characters

Canton name in French

nameIt
string <= 30 characters

Canton name in Italian

nameRm
string <= 30 characters

Canton name in Romansh

nameEn
string <= 30 characters

Canton name in English

entryDate
string <date> <= 10 characters

Entry date of the canton in the Federal Confederation

Array of objects (DistrictResponse) <= 50 characters

Districts (Bezirke) contained in this canton. Note: Some cantons do not have districts and are directly divided into municipalities.

Response samples

Content type
application/json

Zurich cantonAbbreviation

{
  • "cantonId": 1,
  • "abbreviation": "ZH",
  • "nameDe": "Zürich",
  • "nameFr": "Zurich",
  • "nameIt": "Zurigo",
  • "nameRm": "Turitg",
  • "nameEn": "Zurich",
  • "entryDate": "1351-05-01",
  • "districts": [
    ]
}

Districts

Swiss administrative districts API.

This API provides access to Swiss districts (Bezirke/Districts/Distretti), which are administrative subdivisions of cantons. Note that some cantons (e.g. GE, BS, BL, NW, OW, UR, AI) do not have districts and are divided directly into municipalities.

Data Source: Federal Statistical Office (FSO/BFS) via eCH-0071

Get district by ID

Retrieves a single district by its official district number assigned by the Federal Statistical Office (FSO/BFS).

Authorizations:
bearerAuth
path Parameters
districtId
required
integer <int32> >= 1
Example: 101

Official FSO/BFS district number

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

Responses

Response Schema: application/json
districtId
integer <int32> [ 1 .. 9999 ]

Official district number assigned by the Federal Statistical Office

name
string <= 60 characters

Official district name

shortName
string <= 24 characters

Short official district name for compact display

object (CantonResponse_WithCanton)

Canton to which this district belongs

admissionMode
string
Enum: "CREATION" "SPLIT" "MERGER" "TERRITORIAL_CHANGE" "NAME_CHANGE" "ADMINISTRATIVE_REACTIVATION" "OTHER_MUTATION"

Type of administrative admission that created this district

integrationDate
string <date>

Date when the district was integrated into the federal register

abolitionMode
string
Enum: "MERGER" "TERRITORIAL_CHANGE" "NAME_CHANGE" "ADMINISTRATIVE_DEACTIVATION" "OTHER_MUTATION" "ATTACHMENT" "FINAL_SUPPRESSION"

Type of administrative abolition (null if district is still active)

abolitionDate
string <date>

Date when the district was abolished (null if district is still active)

dateOfChange
string <date>

Date of last modification to this district's data

Array of objects (MunicipalityResponse_WithCanton)

List of municipalities (Gemeinden) contained within this district

Response samples

Content type
application/json

Zurich district

{
  • "districtId": 101,
  • "name": "Bezirk Affoltern",
  • "shortName": "Affoltern",
  • "canton": {
    },
  • "admissionMode": "CREATION",
  • "integrationDate": "1848-09-12",
  • "abolitionMode": null,
  • "abolitionDate": null,
  • "dateOfChange": "2024-01-15",
  • "municipalities": [
    ]
}

Search districts by name

Full-text search across district names using fuzzy matching. Returns up to limit results ordered by relevance score.

The search is accent-insensitive and tolerates minor spelling variations.

Authorizations:
bearerAuth
query Parameters
q
required
string [ 2 .. 100 ] characters
Example: q=Zürich

Search term to match against district names (fuzzy, accent-insensitive)

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

Maximum number of candidates to retrieve from the index (1–50)

page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Search result

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 2,
  • "totalPages": 1
}

List all districts for a canton

Retrieves all districts belonging to the given canton, sorted alphabetically by name.

Some cantons have no districts — an empty page is returned in that case.

Authorizations:
bearerAuth
path Parameters
abbreviation
required
string
Enum: "ZH" "BE" "LU" "UR" "SZ" "OW" "NW" "GL" "ZG" "FR" "SO" "BS" "BL" "SH" "AR" "AI" "SG" "GR" "AG" "TG" "TI" "VD" "VS" "NE" "GE" "JU"
Example: ZH

Two-letter canton abbreviation (ISO 3166-2:CH)

query Parameters
page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Zurich districts

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 12,
  • "totalPages": 2
}

Municipalities

Swiss political municipalities API.

This API provides access to Swiss municipalities (Gemeinden/Communes/Comuni), the smallest political unit in Switzerland. Each municipality is identified by a unique BFS number assigned by the Federal Statistical Office.

Data Source: Federal Statistical Office (FSO/BFS) via eCH-0071

Get municipality by ID

Retrieves a single municipality by its official BFS number.

Authorizations:
bearerAuth
path Parameters
municipalityId
required
integer <int32> >= 1
Example: 261

Official FSO/BFS municipality number (BFS-Nr)

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

Responses

Response Schema: application/json
municipalityId
integer <int32> [ 1 .. 9999 ]

Official municipality number assigned by the Federal Statistical Office

longName
string <= 40 characters

Full official municipality name

shortName
string <= 40 characters

Short municipality name

admissionMode
string
Enum: "CREATION" "SPLIT" "MERGER" "TERRITORIAL_CHANGE" "NAME_CHANGE" "ADMINISTRATIVE_REACTIVATION" "OTHER_MUTATION"

Type of administrative admission that created this municipality

integrationDate
string <date>

Date when the municipality was integrated into the federal register

abolitionMode
string
Enum: "MERGER" "TERRITORIAL_CHANGE" "NAME_CHANGE" "ADMINISTRATIVE_DEACTIVATION" "OTHER_MUTATION" "ATTACHMENT" "FINAL_SUPPRESSION"

Type of administrative abolition (null if municipality is still active)

abolitionDate
string <date>

Date when the municipality was abolished (null if municipality is still active)

object (DistrictResponse)

District (Bezirk) containing this municipality

Array of objects (LocalityResponse)

List of postal localities (Ortschaften) within this municipality

Response samples

Content type
application/json

Zurich municipality

{
  • "municipalityId": 261,
  • "longName": "Zürich",
  • "shortName": "Zürich",
  • "admissionMode": "CREATION",
  • "integrationDate": "1848-09-12",
  • "abolitionMode": null,
  • "abolitionDate": null,
  • "district": {
    }
}

Search municipalities

Full-text search across municipality names, district names, canton names and locality names using fuzzy matching. Results are ordered by relevance score. The search is accent-insensitive and tolerates minor spelling variations.

Authorizations:
bearerAuth
query Parameters
q
required
string [ 2 .. 100 ] characters
Example: q=Zürich

Search term (fuzzy, accent-insensitive)

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

Maximum number of candidates from the index (1–50)

page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Search results

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 1,
  • "totalPages": 1
}

List municipalities by district

Retrieves all municipalities belonging to the given district, sorted alphabetically by name.

The district field is omitted from each municipality (redundant with the filter).

Authorizations:
bearerAuth
path Parameters
district
required
integer <int32> >= 1
Example: 101

Official FSO/BFS district number

query Parameters
page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

District municipalities

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 14,
  • "totalPages": 2
}

List municipalities by canton

Retrieves all municipalities belonging to the given canton, sorted alphabetically by name.

The canton field inside each district is omitted (redundant with the filter).

Authorizations:
bearerAuth
path Parameters
canton
required
string
Enum: "ZH" "BE" "LU" "UR" "SZ" "OW" "NW" "GL" "ZG" "FR" "SO" "BS" "BL" "SH" "AR" "AI" "SG" "GR" "AG" "TG" "TI" "VD" "VS" "NE" "GE" "JU"
Example: ZH

Two-letter canton abbreviation (ISO 3166-2:CH)

query Parameters
page
integer <int32> >= 0
Default: 0

Page number (0-based)

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

Page size (1–100)

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Zurich municipalities

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 162,
  • "totalPages": 17
}

Addresses

Swiss address search and normalization API.

This API provides access to the official Swiss federal address database (GWR/RegBL), enabling address lookup, autocomplete, and normalization services for all Swiss addresses.

Key Features:

  • Full-text address search with relevance scoring
  • Structured address search by postal code, locality, cantonAbbreviation, etc.
  • Address normalization and validation
  • Support for all Swiss cantons and postal codes

Data Source: Federal Register of Buildings and Dwellings (RBD/GWR)

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.

Ideal for:

  • Real-time address input fields with typeahead suggestions
  • User-facing address search interfaces
  • Quick address lookup in forms

Scoring:

  • Results are ranked by relevance score (0.0 to 1.0)
  • Higher scores indicate better matches
  • Threshold filters out low-quality matches

Performance:

  • Optimized for low-latency responses
  • Maximum 20 results to ensure fast response times

Note: The query can also be submitted via request body (POST /autocomplete) for confidential use-cases where the query must not appear in URL logs (e.g. banking). Both methods are mutually exclusive.

Authorizations:
bearerAuth
query Parameters
query
required
string [ 1 .. 2147483647 ] characters
Example: query=Bahnhofstrasse Zürich

Search query string for autocomplete. Supports street names, localities, postal codes, and combinations.

threshold
string [ 0 .. 1 ]
Example: threshold=0.5

Minimum relevance score threshold. Results below this score are filtered out. Range: 0.0 (all results) to 1.0 (exact matches only).

limit
string [ 1 .. 20 ]
Example: limit=10

Maximum number of results to return. Limited to 20 for performance. Lower values recommended for real-time autocomplete.

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

Filter by address status. REAL = existing addresses (default).

addressCategories
string
Enum: "UNCATEGORIZED" "TEMPORARY" "RESIDENTIAL" "OTHER_RESIDENTIAL" "PARTLY_RESIDENTIAL" "NON_RESIDENTIAL" "SPECIAL"
Example: addressCategories=RESIDENTIAL,TEMPORARY

Filter by address categories. Multiple categories can be specified.

page
string >= 0

Page number (0-based)

size
string [ 1 .. 20 ]
Example: size=10

Page size

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Autocomplete results

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 10,
  • "totalElements": 2,
  • "totalPages": 1
}

Autocomplete addresses (confidential)

Confidential variant of autocomplete for use-cases where the search query must not appear in URL logs (e.g. banking or regulated industries). The query is passed in the encrypted request body instead of as a URL parameter.

Mutually exclusive with GET /autocomplete — use one or the other, never both.

All search parameters are embedded in the request body as a JSON object.

Authorizations:
bearerAuth
query Parameters
page
string >= 0

Page number (0-based)

size
string [ 1 .. 20 ]
Example: size=10

Page size

header Parameters
X-HelvAddress-API-Version
string
Default: 1.0.0
Value: "1.0.0"
Request Body schema: application/json
required

Autocomplete search parameters including the confidential query string

query
required
string [ 1 .. 200 ] characters

Search query string. Supports street names, localities, postal codes, and combinations.

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

Minimum relevance score threshold. Results below this score are filtered out. Range: 0.0 (all results) to 1.0 (exact matches only).

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

Maximum number of results to return. Limited to 20 for performance. Lower values recommended for real-time autocomplete.

entityStatus
string
Default: "REAL"
Enum: "PLANNED" "REAL" "OUTDATED"

Filter by address status. REAL = existing addresses (default).

addressCategories
Array of strings
Items Enum: "UNCATEGORIZED" "TEMPORARY" "RESIDENTIAL" "OTHER_RESIDENTIAL" "PARTLY_RESIDENTIAL" "NON_RESIDENTIAL" "SPECIAL"

Filter by address categories. Multiple categories can be specified.

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Request samples

Content type
application/json

Confidential autocomplete

{
  • "query": "Bahnhofstrasse Zürich",
  • "threshold": 0.5,
  • "limit": 10,
  • "entityStatus": "REAL",
  • "addressCategories": [
    ]
}

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 20,
  • "totalElements": 156,
  • "totalPages": 8
}

Get address by ID

Retrieves all language variants of an address by its federal address identifier (EGAID).

The EGAID is a unique identifier assigned by the Swiss Federal Statistical Office to each building entrance in Switzerland. Since the primary key is (id, street_language), a single EGAID may return multiple entries — one per registered language.

Authorizations:
bearerAuth
path Parameters
id
required
integer <int64>
Example: 100001234

Federal address identifier (EGAID) - unique identifier for building entrances

query Parameters
page
string >= 0

Page number (0-based)

size
string [ 1 .. 100 ]
Example: size=20

Page size

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Zurich address

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 20,
  • "totalElements": 1,
  • "totalPages": 1
}

Search addresses

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

Use Cases:

  • Find all addresses in a specific postal code
  • Search by cantonAbbreviation and locality for regional filtering
  • Look up addresses by municipality for administrative purposes

Search Behavior:

  • localityName and municipalityName support partial matching
  • Multiple criteria are combined with AND logic
  • Results are ordered by relevance
  • Results are paginated
Authorizations:
bearerAuth
query Parameters
zip4
string [ 1000 .. 9999 ]
Example: zip4=8001

4-digit Swiss postal code (PLZ/NPA). Must be between 1000 and 9999.

zipId
integer <int64>
Example: zipId=4000

Postal locality identifier (ONRP) - unique identifier for postal localities

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

Locality name. Supports partial matching (case-insensitive).

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

Municipality name. Supports partial matching (case-insensitive).

cantonAbbreviation
string = 2 characters ^[A-Za-z]{2}$
Example: cantonAbbreviation=ZH

Canton abbreviation (2 letters, case-insensitive). Example: ZH, BE, VD

streetName
string
Example: streetName=Bahnhofstrasse

Street name. Supports partial matching.

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

Filter by address status. REAL = existing addresses, PLANNED = future addresses, OUTDATED = historical addresses.

addressCategories
string
Enum: "UNCATEGORIZED" "TEMPORARY" "RESIDENTIAL" "OTHER_RESIDENTIAL" "PARTLY_RESIDENTIAL" "NON_RESIDENTIAL" "SPECIAL"
Example: addressCategories=RESIDENTIAL,TEMPORARY

Filter by address categories. Multiple categories can be specified.

limit
string [ 1 .. 1000 ]
Example: limit=100

Maximum number of results to fetch before pagination. Must be between 1 and 1000.

page
string >= 0

Page number (0-based)

size
string [ 1 .. 100 ]
Example: size=20

Page size

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

Responses

Response Schema: application/json
content
Array of any

List of items in the current page

pageNumber
integer <int32> >= 0

Current page number (0-based)

pageSize
integer <int32> [ 1 .. 100 ]

Number of items per page

totalElements
integer <int64>

Total number of items across all pages

totalPages
integer <int32> >= 0

Total number of pages

Response samples

Content type
application/json

Zurich results

{
  • "content": [
    ],
  • "pageNumber": 0,
  • "pageSize": 20,
  • "totalElements": 156,
  • "totalPages": 8
}