Address web services REST

Technical specifications of the Address web service for REST

Version November 2023

(for SOAP click here)

Ensure that only correct addresses are recorded in your database – irrespective of whether you obtain these via a call center, online shop or handwritten order. Typing errors, misheard words, illegible information – it’s easy to make a mistake when recording new addresses. However, to ensure you can reach your customers, an up-to-date and error-free address database is an absolute necessity. It is therefore important that you begin by comparing your newly acquired addresses with the Swiss Post reference data.

1. Address maintenance

Swiss Post offers you the best possible preconditions to support you professionally in your address management. Current and valid addresses are the key to staying in contact with customers.

With the “Address maintenance via web service”, you can check and update your address database directly in your systems. This helps avoid losing addresses and customers due to a change of address. Furthermore, it reduces both the number of undeliverable items and the corresponding costs.
This web service use a REST web interface provide by Swiss Post for the purposes of data exchange. This interface is available 24/7.

There are two ways to access the service:

1.1 Batch processing

In a batch alignment, an entire file can be processed asynchronously. The key “Eirene_maintenance_v1” can be used to do this.

You can find details on the batch alignment under «4.2».

1.2 Individual address queries

If only individual addresses are to be checked using the service, the individual address query can be used. In this case, an address is sent to the service and the result is received as an answer.

The key “Eirene_maintenance_v1” can be used for the query.

You can find a detailed guide on retrieval under «4.3».

1.3 Data structure

1.3.1 Inputfields in query requests

To clean up addresses, the following minimum information is required:

Name or company
First name
Street or P.O. Box
House number
Postcode
Town

The following fields are also an option:

Additional house number information
PoBoxTerm
PoBoxNo
PoBoxZIP
PoBoxZIPAddition
PoBoxTownName

1.3.2 Inputstructure in batch requests

In a batch alignment, the input and output structure for processing must be created in advance with the Address Competence Center.

To clean up addresses, the following minimum information is required:

Name
First name
Street
House number
Postcode
Town

To transfer the results delivered, we recommend including your own record identification (e.g. unique customer number). Additional information may be provided. This information is “passed through” when processed by Swiss Post and returned unchanged with the results delivered (see section “Data output structure”).

The following file formats are permitted: .txt (fixed/variable with user-defined separator), .csv. and .xlsx.

1.3.3 Data output structure

The output is structured as follows:

Field	Description	Maximum field length
Customer fields 1-x	Throughput fields, customer number, etc.	450
QSTAT*	Primary status	02
ShortReport*	Secondary status	24
CorrectionType	0 = no correction required; 1 = correction required	01
TotalScore	Match probability of the check against the reference data	06
ValidFrom	Valid from date for the address information	08
ValidTo	Date of death/date expired	08
Birthdate	Date of birth	08
Housekey	Unique building identification key	19
Double_DoubleGroupNo	Duplicate group number	10
Double_DSTAT	Duplicate status	02
Company	Company name	105
Prename	First name	75
Prename2	Additional first names	75
Name	Last name	75
MaidenName	Maiden name	75
AddressAddition	Additional address information	65
CoAddress	c/o address	65
Streetname	Street name	60
HouseNo	House number	40
HouseNoAddition	Additional house number information	06
Floor	Floor designation	10
ZIPcode	Four-digit postcode home	04
ZIPAddition	Postcode addition home	02
TownName	Town name long home	27
Canton	Canton abbreviation home	02
CountryCode	Country code ISO home	02
PoBoxTerm	P.O. Box term	20
PoBoxNo	P.O. Box number	10
PoBoxZIP	Four-digit postcode P.O. Box	04
PoBoxZIPAddition	Postcode addition P.O. Box	02
PoBoxTownName	Town name long P.O. Box	27

* You can find a detailed explanation on QSTAT and QSTAT ShortReport under «6».

2. Address assistant

Checking of non-personalized address elements such as street, house number, postcode and town
Support for autocomplete functions
Individual queries only
No contract necessary

The address to be recorded is subject to a hard comparison with the Swiss Post reference data. This means that the address cannot contain any typing errors or spelling mistakes for it to be deemed correct (100% match). Betty or Tina instead of Bettina will not be found – nor will Weberngasse instead of Webergasse.

2.1 BuildingVerification

You can using BuildingVerification to check whether a non-personalized address exists. This is only possible in the form of a single request. You can find the exact retrieval under «4.5».

2.2 AutoComplete

With AutoComplete, you can use parts of the non-personalized domicile address to return autofill suggestions. The exact procedure is set out under «4.4».

3. Address verification

Search for personalized and non-personalized address elements
Person verification using last name and first name (fuzzy comparison)
Individual or batch queries
Contract necessary

The comparison is soft, or error-tolerant: Betty or Tina will be recognized as variants of Bettina, and Weberngasse will be found for Webergasse.

3.1 Batch

In a batch alignment, an entire file can be processed asynchronously.

The alignment can be activated through the Address Competence Center.

You can find details on the batch alignment process under «4.2».

3.2 Query

If only individual addresses are to be checked using the service, the individual address query can be used. In this case, an address is sent to the service and the result is received as an answer.

The alignment can be activated through the Address Competence Center.

To retrieve the query, you must use the key “Eirene_validation_v1”.

You can find a detailed guide on single requests under «4.3».

3.3 Data structure

3.3.1 Inputfields in query requests

To clean up addresses, the following minimum information is required:

Name
First name
Street
House number
Postcode
Town

The following fields are also an option:

Additional house number information
PoBoxTerm
PoBoxNo
PoBoxZIP
PoBoxZIPAddition
PoBoxTownName

3.3.2 Inputstructure in batch requests

In a batch alignment, the input and output structure for processing must be created in advance with the Address Competence Center.

To clean up addresses, the following minimum information is required:

Name
First name
Street
House number
Postcode
Town

The following file formats are permitted: .txt (fixed/variable with user-defined separator), .csv. and .xlsx.

3.3.3 Data output structure

The output is structured as follows:

Field	Description	Maximum field length
Customer fields 1-x	Throughput fields, customer number, etc.	450
QSTAT*	Primary status	02
ShortReport*	Secondary status	24
CorrectionType	0 = no correction required; 1 = correction required	01
TotalScore	Match probability of the check against the reference data	06
ValidFrom	Valid from date for the address information	08
ValidTo	Date of death/date expired	08
Birthdate	Date of birth	08
Housekey	Unique building identification key	19
Double_DoubleGroupNo	Duplicate group number	10
Double_DSTAT	Duplicate status	02
Company	Company name	105
Prename	First name	75
Prename2	Additional first names	75
Name	Last name	75
MaidenName	Maiden name	75
AddressAddition	Additional address information	65
CoAddress	c/o address	65
Streetname	Street name	60
HouseNo	House number	40
HouseNoAddition	Additional house number information	06
Floor	Floor designation	10
ZIPcode	Four-digit postcode home	04
ZIPAddition	Postcode addition home	02
TownName	Town name long home	27
Canton	Canton abbreviation home	02
CountryCode	Country code ISO home	02
PoBoxTerm	P.O. Box term	20
PoBoxNo	P.O. Box number	10
PoBoxZIP	Four-digit postcode P.O. Box	04
PoBoxZIPAddition	Postcode addition P.O. Box	02
PoBoxTownName	Town name long P.O. Box	27

* Only QSTAT 1 and 3 are returned with address verification. You can find a detailed explanation on QSTAT and QSTAT ShortReport under «6».

3.3.4. Obtaining a notification of move with address maintenance

Two files are issued per address maintenance comparison via the customer’s web service. The notifications of move intended for the company are assigned to the delivered customer addresses and marked as notifications of move via a short report (item H).

In addition, there are notifications of move that cannot be assigned to delivered customer addresses, as these are mainly new customers that could not be found in the comparison. These notifications of move can be obtained via a separate file.

Data structures

The first file will display the structure according to section 3.3.3, and the notifications of move will be displayed in the short report (item H).
The second file is displayed in the structure according to section 3.3.5 with the private customer’s old and new address.

3.3.5 Obtaining a notification of move without address maintenance (matching only)

Here only the notifications of move are matched to the customer addresses without carrying out any address maintenance. Messages are also matched in this process, and messages that cannot be compared are issued in a separate file. Obtaining the notification of move via a web service without address maintenance will display the following data structure – see table below.

Data structures

The business customer will receive both the old and new address.
Column 4 provides the private customer’s date of birth as an additional attribute.

4. Technical connection

4.1 Checking Availability And Connection

The easiest method for checking whether the service is available is the ping method.

Request

The request URL is: “GET /ping”

Parameters

This operation has no parameters.

Response

The HTTP status 200 OK is returned in response

4.2 Batch processing of several addresses in a file

To align multiple addresses in a file with each other, an alignment must first be structured together with the Address Competence Center. This is then stored with the web service. To start the alignment, several steps are required:

4.2.1 Upload data

One or more files must be transferred to the service. These can be text files with a fixed structure, text files with a variable structure with field separators and, in certain circumstances, field delimiters or Excel files in xlsx format. The files are always uploaded as a binary data stream and are stored by the service in encrypted format.

Request

The “POST /uploadfile” method can be used to upload an “application/octet-stream” file.

Parameters

An “application/octet-stream” file.

Reponse

The response returned is the status of the request and, if successful, a token which defines the uploaded file in the service.

{
   "UploadFileResult": {
      "FileToken": "70abdcab-3054-49f7-a3c2-4211d9239731",
      "Status": 0
   }
}

4.2.2 Define output files

For each output file from the alignment, a file must be created in the service.

Request

The following method is called up to create a file on the Service: “GET /createfile”

Parameters

This operation has no parameters.

Response

As with the upload, the response returned is a status and a file token, which can then be used to download the data.

{
   "CreateFileResult": {
      "FileToken": "12082bae-a51b-4c2e-84b4-9245a8c9abfb",
      "Status": 0
   }
}

4.2.3 Start processing

To start the batch alignment, the “POST/ runbatch” request must be executed. With this request, the file tokens generated when uploading and creating the files are assigned to the corresponding placeholders in the configuration. The key is used to specify the alignment.

Request

{
  "key": "customkey",
  "replaceItems": [
    {
      "Search": "{###INPUTFILE###}",
      "Replacement": "70abdcab-3054-49f7-a3c2-4211d9239731"
    },
    {
      "Search": "{###OUTPUTFILE###}",
      "Replacement": "12082bae-a51b-4c2e-84b4-9245a8c9abfb"
    }
  ]
}

Parameters

Element	Data type	Description
key	string	The key of the batch processing to be run
replaceItems	ReplaceItem[]	The replacement elements that adapt dynamic elements in the configuration.

ReplaceItem

A ReplaceItem contains the elements search and replace. In the search element, you enter a placeholder, and the replacement is returned in the replace element. Normally, the search elements "{###INPUTFILE###}" and {###OUTPUTFILE###} are defined. For these elements, the batch token that was returned by the service during the upload/creation of the output file is displayed as a replace element.

Response

This returns the following response with the batch token that can be used to query the status of the alignment:

{
   "RunBatchResult": {
      "BatchToken": "63aa6978-2a6e-4c34-a57a-046310d364e0",
      "SettlementId": 21888,
      "Status": 0
   }
}

The following elements are returned in the response:

Property	Definition
BatchToken	The batch token identifies the service operation. This is used for the status query.
SettlementID	Invoicing ID.
Status	Query status You can find the exact definition in the table under «8».

4.2.3.1 Start processing for clients

To start an alignment for a client, the “POST /runbatchwithclient” method can be used. The client’s invoice reference number will be provided in addition to the replacements and the alignment key. The user submitting the query must be authorized for this purpose.

{
    "key": "customkey",
    "replaceItems": [
      {
        "Search": "{###INPUTFILE###}",
        "Replacement": "70abdcab-3054-49f7-a3c2-4211d9239731"
      },
      {
        "Search": "{###OUTPUTFILE###}",
        "Replacement": "12082bae-a51b-4c2e-84b4-9245a8c9abfb"
      }
    ],
    "billingReferenceNumber" : "11223344"
  }

Parameters

Element	Data type	Description
key	string	The key of the batch processing to be run
replaceItems	ReplaceItem[]	The replacement elements that adapt dynamic elements in the configuration.
billingReferenceNumber	string	The invoice reference number for the client for whom the alignment is to be performed.

Response

Identical to the “POST /runbatch” method.

4.2.4 Query the processing status

To query the progress of the alignment, the CheckBatchStatus request is activated in the service. In this case, the batch token returned at the start of batch run is given as a parameter.

Request

“GET / checkbatchstatus/{token}”

Parameters

Element	Data type	Description
token	string	Batch token for the processing, the status of which is to be determined.

Response

The response contains the status of the current processing.

{
   "CheckBatchStatusResult": {
      "BatchStatus":    {
         "LastUpdateDateTime": "/Date(1491482100937+0200)/",
         "Message": "Module 'Basiskonfiguration' is Running",
         "Progress": 18,
         "RemainingTimeSeconds": 888,
         "StartDateTime": "/Date(1491482100770+0200)/",
         "TokenStatus": 3
      },
      "Status": 0
   }
}

The individual properties have the following meanings:

Property	Meaning
LastUpdateDateTime	Time of the last update in Microsoft date format
Message	The last message returned from the processing
Progress	The progress of the processing as a percentage
RemainingTimeSeconds	The approximate number of seconds the alignment still has to run
StartDateTime	The processing start time
TokenStatus	The processing status: 0 = New 1 = Error 2 = Waiting 3 = Running 4 = Finished 5 = Failed 6 = Canceled 7 = Unknown

4.2.5 Download files

When the token status for the alignment is “Finished”, the data can be downloaded. To download the result of an alignment, a download request is sent with the file token returned when the output file was created.

Request

The request is as follows: “GET /downloadfile/{token}”

Parameters

Element	Data type	Description
token	string	The file token for the file to be downloaded

Response

The response returned is a binary-coded stream of the “application/octet-stream” type, which can then be stored locally.

4.2.6 Delete File

All uploaded files are automatically deleted after 3 months. However you can delete a file

Request

The request is as follows: “GET /deletefile/{token}”

Parameters

Element	Data type	Description
token	string	The file token for the file to be deleted

Response

The response is structured as defined below.

{ 
"Status": 0 
}

4.3 Individual address queries

In the case of an individual address query, a query can be conducted using an individual address. The query key is used to define the query to be run. Both the expected structure of the input fields and the structure of the response depend on the operation queried.

Request

The request is as follows: “POST /runquery2”

A sample query of first name, last name, street, house number, postcode and town is shown below. The alignment is defined using the “querykey”. If no response is returned after 10 seconds (10,000 milliseconds), the query is interrupted.

{  
   "address": {
    "Id": 123,
    "Data": [
      {
        "FieldName": "Prename_in",
        "Value": "Hans"
      },
      {
        "FieldName": "Name_in",
        "Value": "Muster"
      },
      { 
        "FieldName": "StreetName_in",
        "Value": "Sternmatt"
      },
      {
        "FieldName": "HouseNo_in",
        "Value": "6"
      },      
      {
        "FieldName": "ZIPCode_in",
        "Value": "6010"
      },
      { 
        "FieldName": "TownName_in",
        "Value": "Kriens"
      }
    ]
  },
  "key": "querykey",
  "timeout": 10000
}

Parameters

Element	Data type	Description
FieldName	String	Field name. A list of authorized field names and their meanings is set out in the tablet “Supported field names”.
Value	String	The field value.
Id	Int	Numerical, customer-specific ID that can be used to recognize the input.
Key	String	Query definition key
Timeout	Int	Number of milliseconds before the request is aborted.

Response

The response is structured as defined below. The fields may differ depending on the type of query.

{
  "RunQuery2Result": {
      "Result": {
          "Data": [              
              {
                  "FieldName": "Prename",
                  "Value": "Hans"
              },
              {
                  "FieldName": "Name",
                  "Value": "Muster"
              },
              {
                  "FieldName": "StreetName",
                  "Value": "Sternmatt"
              },
              {
                  "FieldName": "HouseNo",
                  "Value": "6"
              },
              {
                  "FieldName": "ZIPCode",
                  "Value": "6010"
              },
              {
                  "FieldName": "TownName",
                  "Value": "Kriens"
              }
          ],
          "Id": 42
      },
      "SettlementId": 284058911,
      "Status": 0
  }
}

4.3.1 Individual address queries for clients

To start an individual address query for a client, the “POST /runquery2withclient” method can be used. The client’s invoice reference number will be provided in addition to the field values and the alignment key. The user submitting the query must be authorized for this purpose.

Request

{
    "address": {
        "Id": 123,
        "Data": [
            {
                "FieldName": "Prename_in",
                "Value": "Hans"
            },
            {
                "FieldName": "Name_in",
                "Value": "Muster"
            },
            {
                "FieldName": "StreetName_in",
                "Value": "Sternmatt"
            },
            {
                "FieldName": "HouseNo_in",
                "Value": "6"
            },
            {
                "FieldName": "ZIPCode_in",
                "Value": "6010"
            },
            {
                "FieldName": "TownName_in",
                "Value": "Kriens"
            }
        ]
    },
    "key": "querykey",
    "timeout": 10000,
    "billingReferenceNumber": "11223344"
}

Parameters

Element	Data type	Description
FieldName	String	Field name. A list of authorized field names and their meanings is set out in the tablet “Supported field names”.
Value	String	The field value.
Id	Int	Numerical, customer-specific ID that can be used to recognize the input.
Key	String	Query definition key
Timeout	Int	Number of milliseconds before the request is aborted.
billingReferenceNumber String	String	The invoice reference number for the client for whom the alignment is to be performed.

Response

Identical to the “POST /runquery2” method.

4.4 AutoComplete

AutoComplete is used to support users when entering non-personal addresses. The autocomplete request returns all address components found for an input when the user enters partial input. The address components that can be searched are towns, streets or buildings. The level of the query (towns, streets or buildings) is determined by the search request.

A term is considered a match if the search term occurs at the beginning of a word in a reference term (not case sensitive). If multiple search parameters are passed at the same time, all search criteria must be fulfilled.

Match type	Search parameters		Reference
	Field	Value
Full match	StreetName	Lindenstrasse	Lindenstrasse (Not: Lindenweg)
Match at beginning of word	StreetName	Linden	Lindenstrasse Lindenweg (Not: Dorflindenstrasse)
Match at beginning of a word in a substring	StreetName	Linden	Ausser-Lindenegg In der Linden (Not: Unter-Blindenbach)
Multiple search parameters at the same level	ZipCode	60	6010 Kriens 6047 Kastanienbaum (Not: 6048 Horw) (Not: 3098 Köniz)
	TownName	K
Multiple search parameters at different levels	ZipCode	60	Wiesenau, 6018 Buttisholz Obere Wiese, 6020 Emmenbrücke
	StreetName	wies	(Not: Wiesenstrasse, 5012 Schönenwerd) (Not: Haldenring, 6020 Emmenbrücke)

4.4.1 Search for towns

The following request for the “POST /autocomplete4” method searches for towns:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "817",
    "ZipAddition": "",
    "TownName": "n",
    "STRID": 0,
    "StreetName": "",
    "HouseKey": 0,
    "HouseNo": "",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds:

{
  "QueryAutoComplete4Result": {
    "AutoCompleteResult": [
      {
        "Canton": "ZH",
        "CountryCode": "CH",
        "HouseKey": "0",
        "HouseNo": "",
        "HouseNoAddition": "",
        "ONRP": "4542",
        "STRID": "0",
        "StreetName": "",
        "TownName": "Niederglatt ZH",
        "ZipAddition": "00",
        "ZipCode": "8172"
      },
      {
        "Canton": "ZH",
        "CountryCode": "CH",
        "HouseKey": "0",
        "HouseNo": "",
        "HouseNoAddition": "",
        "ONRP": "4543",
        "STRID": "0",
        "StreetName": "",
        "TownName": "Neerach",
        "ZipAddition": "00",
        "ZipCode": "8173"
      },
            {
         "Canton": "ZH",
         "CountryCode": "CH",
         "HouseKey": "0",
         "HouseNo": "",
         "HouseNoAddition": "",
         "ONRP": "4544",
         "STRID": "0",
         "StreetName": "",
         "TownName": "Stadel b. Niederglatt",
         "ZipAddition": "00",
         "ZipCode": "8174"
      }
    ],
    "Status": 0
  }
}

4.4.2 Search for streets

Multiple variants can be selected to search for streets.

4.4.2.1 Search for streets without restriction to town

This search variant searches all streets regardless of the town.

Building	HouseKey	-
	HouseNo	O
	HouseNoAdditon	O
Street	STRID	„0“
Street	StreetName	X
Town	ONRP	„0“
	ZipCode	O
	ZipAddition	-
	TownName	O

“0” = static value ‘0’ / O = empty / X = filled / - = no influence on search

The following request for the “POST /autocomplete4” method searches for streets with no town restriction:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "",
    "STRID": 0,
    "StreetName": "Alte Stationsstrasse",
    "HouseKey": 0,
    "HouseNo": "",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "0",
                "HouseNo": "",
                "HouseNoAddition": "",
                "ONRP": "4530",
                "STRID": "24583",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Oberglatt ZH",
                "ZipAddition": "00",
                "ZipCode": "8154"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "0",
                "HouseNo": "",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "0",
                "HouseNo": "",
                "HouseNoAddition": "",
                "ONRP": "4540",
                "STRID": "58009546",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Niederweningen",
                "ZipAddition": "00",
                "ZipCode": "8166"
            }
        ],
        "Status": 0
    }
}

4.4.2.2 Search for streets with restriction to town using search terms

This search variant searches all streets within matching towns.

Building	HouseKey	-
	HouseNo	O
	HouseNoAdditon	O
Street	STRID	„0“
Street	Streetname	X
Town	ONRP	„0“
	ZipCode	X*
	ZipAddition	-
	TownName	X*

“0” = static value ‘0’ / O = empty / X = filled / - = no influence on search
* Postcode can be empty if town entered, or town can be empty if postcode entered

The following request for the “POST /autocomplete4” method searches for streets in matching towns:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "Oberglatt",
    "STRID": 0,
    "StreetName": "Alte Stationsstrasse",
    "HouseKey": 0,
    "HouseNo": "",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
  "QueryAutoComplete4Result": {
      "AutoCompleteResult": [
          {
              "Canton": "ZH",
              "CountryCode": "CH",
              "HouseKey": "0",
              "HouseNo": "",
              "HouseNoAddition": "",
              "ONRP": "4530",
              "STRID": "24583",
              "StreetName": "Alte Stationsstrasse",
              "TownName": "Oberglatt ZH",
              "ZipAddition": "00",
              "ZipCode": "8154"
          }
      ],
      "Status": 0
  }
}

4.4.2.3 Search for streets with restriction to a town

This search variant searches all streets within a single town. The town is defined using the ONRP.

Building	HouseKey	-
	HouseNo	O
	HouseNoAdditon	O
Street	STRID	„0“
Street	StreetName	X
Town	ONRP	X
	ZipCode	-*
	ZipAddition	▬
	TownName	-*

“0” = static value ‘0’ / O = empty / X = filled / - = no influence on search
* When an ONRP number is specified, these search parameters are ignored, even if a value is entered

The following request for the “POST /autocomplete4” method searches for streets in matching towns:

{
  "request": {
    "ONRP": 5137,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "Oberglatt",
    "STRID": 0,
    "StreetName": "stat",
    "HouseKey": 0,
    "HouseNo": "",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "0",
                "HouseNo": "",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "30002",
                "StreetName": "Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "0",
                "HouseNo": "",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            }
        ],
        "Status": 0
    }
}

4.4.3 Search for buildings

Multiple variants can be selected to search for buildings

4.4.3.1 Search for buildings without restriction to street or town

This search variant searches all buildings regardless of town or street.

Building	HouseKey	-
	HouseNo	X*
	HouseNoAdditon	X*
Street	STRID	„0“
Street	StreetName	O
Town	ONRP	„0“
	ZipCode	O
	ZipAddition	-
	TownName	O

The following request for the “POST /autocomplete4” method searches for buildings with no town or street restriction:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "",
    "STRID": 0,
    "StreetName": "",
    "HouseKey": 0,
    "HouseNo": "105",
    "HouseNoAddition": "N"
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "JU",
                "CountryCode": "CH",
                "HouseKey": "30039869",
                "HouseNo": "105",
                "HouseNoAddition": "N",
                "ONRP": "1634",
                "STRID": "30022575",
                "StreetName": "Le Chênois",
                "TownName": "Charmoille",
                "ZipAddition": "00",
                "ZipCode": "2947"
            },
            {
                "Canton": "JU",
                "CountryCode": "CH",
                "HouseKey": "76243990",
                "HouseNo": "105",
                "HouseNoAddition": "N",
                "ONRP": "1632",
                "STRID": "30001307",
                "StreetName": "Sur le Creux de Loups",
                "TownName": "Bonfol",
                "ZipAddition": "00",
                "ZipCode": "2944"
            },
            {
                "Canton": "NE",
                "CountryCode": "CH",
                "HouseKey": "76488519",
                "HouseNo": "105",
                "HouseNoAddition": "N",
                "ONRP": "1440",
                "STRID": "30021239",
                "StreetName": "La Praye",
                "TownName": "Lignières",
                "ZipAddition": "00",
                "ZipCode": "2523"
            }
        ],
        "Status": 0
    }
}

4.4.3.2 Search for buildings with restriction to street using search terms

This search variant searches all buildings within matching streets.

Building	HouseKey	-
	HouseNo	X*
	HouseNoAdditon	X*
Street	STRID	„0“
Street	StreetName	X
Town	ONRP	„0“
	ZipCode	O
	ZipAddition	-
	TownName	O

The following request for the “POST /autocomplete4” method searches for buildings with restriction to street:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "",
    "STRID": 0,
    "StreetName": "le",
    "HouseKey": 0,
    "HouseNo": "105",
    "HouseNoAddition": "N"
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "JU",
                "CountryCode": "CH",
                "HouseKey": "76243990",
                "HouseNo": "105",
                "HouseNoAddition": "N",
                "ONRP": "1632",
                "STRID": "30001307",
                "StreetName": "Sur le Creux de Loups",
                "TownName": "Bonfol",
                "ZipAddition": "00",
                "ZipCode": "2944"
            },
            {
                "Canton": "JU",
                "CountryCode": "CH",
                "HouseKey": "30039869",
                "HouseNo": "105",
                "HouseNoAddition": "N",
                "ONRP": "1634",
                "STRID": "30022575",
                "StreetName": "Le Chênois",
                "TownName": "Charmoille",
                "ZipAddition": "00",
                "ZipCode": "2947"
            }
        ],
        "Status": 0
    }
}

4.4.3.3 Search for buildings with restriction to town using search terms

This search variant searches all buildings within matching towns.

Building	HouseKey	-
	HouseNo	X*
	HouseNoAdditon	X*
Street	STRID	„0“
Street	StreetName	O
Town	ONRP	„0“
	ZipCode	X**
	ZipAddition	▬
	TownName	X**

“0” = static value ‘0’ / O = empty / X = filled / - = no influence on search
* House number can be empty if house number addition entered or house number addition can be empty if house number entered
** Postcode can be empty if town entered, or town can be empty if postcode entered

The following request for the “POST /autocomplete4” method searches for buildings with restriction to towns:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "zh",
    "STRID": 0,
    "StreetName": "",
    "HouseKey": 0,
    "HouseNo": "105",
    "HouseNoAddition": "b"
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57524080",
                "HouseNo": "105",
                "HouseNoAddition": "B",
                "ONRP": "4659",
                "STRID": "26183",
                "StreetName": "Russikerstrasse",
                "TownName": "Pfäffikon ZH",
                "ZipAddition": "00",
                "ZipCode": "8330"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76428690",
                "HouseNo": "105",
                "HouseNoAddition": "B",
                "ONRP": "4990",
                "STRID": "28408",
                "StreetName": "Lerchenbergstrasse",
                "TownName": "Erlenbach ZH",
                "ZipAddition": "00",
                "ZipCode": "8703"
            }
        ],
        "Status": 0
    }
}

4.4.3.4 Search for buildings with restriction to exactly one street

This search variant searches all buildings within a single street. The street is defined using the STRID.

Building	HouseKey	-
	HouseNo	X*
	HouseNoAdditon	X*
Street	STRID	X
Street	StreetName	-**
Town	ONRP	-
	ZipCode	-**
	ZipAddition	-**
	TownName	-**

“0” = static value ‘0’ / O = empty / X = filled / - = no influence on search
* House number can be empty if house number addition entered or house number addition can be empty if house number entered
** When an StrId number is specified, these search parameters are ignored, even if a value is entered

The following request for the “POST /autocomplete4” method searches for buildings with restriction to street:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "",
    "ZipAddition": "",
    "TownName": "zh",
    "STRID": 75022,
    "StreetName": "",
    "HouseKey": 0,
    "HouseNo": "1",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57513045",
                "HouseNo": "10",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57513049",
                "HouseNo": "14",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57513051",
                "HouseNo": "16",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "58051422",
                "HouseNo": "1",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76129508",
                "HouseNo": "11",
                "HouseNoAddition": "",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76200318",
                "HouseNo": "12",
                "HouseNoAddition": "A",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76200319",
                "HouseNo": "12",
                "HouseNoAddition": "B",
                "ONRP": "5137",
                "STRID": "75022",
                "StreetName": "Alte Stationsstrasse",
                "TownName": "Bonstetten",
                "ZipAddition": "00",
                "ZipCode": "8906"
            }
        ],
        "Status": 0
    }
}

4.4.3.5 Search for buildings with restriction to street and town using search terms

This search variant searches all buildings within matching streets and towns.

Building	HouseKey	-
	HouseNo	X*
	HouseNoAdditon	X*
Street	STRID	„0“
Street	StreetName	X
Town	ONRP	„0“
	ZipCode	X**
	ZipAddition	▬
	TownName	X**

The following request for the “POST /autocomplete4” method searches for buildings with restriction to street and town:

{
  "request": {
    "ONRP": 0,
    "ZipCode": "8",
    "ZipAddition": "",
    "TownName": "w",
    "STRID": 0,
    "StreetName": "weg",
    "HouseKey": 0,
    "HouseNo": "15",
    "HouseNoAddition": ""
  },
"zipOrderMode":0,
"zipFilterMode":0
}

The service responds

{
    "QueryAutoComplete4Result": {
        "AutoCompleteResult": [
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57231933",
                "HouseNo": "15",
                "HouseNoAddition": "",
                "ONRP": "4690",
                "STRID": "67626",
                "StreetName": "Salomon-Bleuler-Weg",
                "TownName": "Winterthur",
                "ZipAddition": "00",
                "ZipCode": "8400"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76503064",
                "HouseNo": "15",
                "HouseNoAddition": "",
                "ONRP": "4708",
                "STRID": "76141453",
                "StreetName": "Wegackerstrasse",
                "TownName": "Winterthur",
                "ZipAddition": "00",
                "ZipCode": "8405"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "76267671",
                "HouseNo": "15",
                "HouseNoAddition": "",
                "ONRP": "4710",
                "STRID": "76118558",
                "StreetName": "Maria-Kübler-Weg",
                "TownName": "Winterthur",
                "ZipAddition": "00",
                "ZipCode": "8406"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "58139878",
                "HouseNo": "15",
                "HouseNoAddition": "",
                "ONRP": "5064",
                "STRID": "29691",
                "StreetName": "Julius-Hauser-Weg",
                "TownName": "Wädenswil",
                "ZipAddition": "00",
                "ZipCode": "8820"
            },
            {
                "Canton": "ZH",
                "CountryCode": "CH",
                "HouseKey": "57002169",
                "HouseNo": "15",
                "HouseNoAddition": "",
                "ONRP": "5064",
                "STRID": "29692",
                "StreetName": "Karl-Stamm-Weg",
                "TownName": "Wädenswil",
                "ZipAddition": "00",
                "ZipCode": "8820"
            }
        ],
        "Status": 0
    }
}

4.4.4 zipOrderMode

The zipOrderMode element can be used to define how the output is sorted. There are three different modes:

Mode	Value in JSON request	Effect
NumericAscending	0	The output is sorted in ascending order according to postcode. All hits are displayed (default).
ZipTypeNotPoBox	1	The output is sorted based on the postcode type. The P.O. Box postcodes are displayed at the end.
ZipPoBox	2	The output is sorted based on the postcode type. The P.O. Box postcodes are displayed at the start.

4.4.5 zipFilterMode

The zipFilterMode element can be used to search explicitly for addresses of domicile, P.O. Box or company postcodes only.

Mode	Value in JSON request	Effect
All	0	All postcode types (default).
Only domicile postcodes	1	Only postcodes that are domicile postcodes appear / are verified in the selection.
Only P.O. Box postcodes	2	Only postcodes that are P.O. Box postcodes appear / are verified. NOTE: street names / house numbers are no longer verified with this option.
Only company postcodes	3	Only postcodes that are company postcodes appear / are verified. NOTE: street names / house numbers are no longer verified with this option.

4.5 BuildingVerification

With BuildingVerification, a non-personalized domicile address can be checked for accuracy. If the address is accurate, the house key and the address are entered with the Swiss Post spelling.

Request

GET\

buildingverification4?streetname={streetname}&houseno={houseNo}&housenoaddition={houseNoAddition}&zipcode={zipcode}&townName={townname}

Parameters

The following parameters can also be entered:

Element	Data type	Description
streetname	String	Street name
houseNo	String	House number
houseNoAddition	String	Additional house number information
zipcode	String	Postcode
townname	String	Town name

Response

{
    "QueryBuildingVerification4Result": {
        "BuildingVerificationData": {
            "Canton": "LU",
            "CountryCode": "CH",
            "HouseKey": 165890,
            "HouseNo": "2",
            "HouseNoAddition": "",
            "ONRP": "3290",
            "PSTAT": "2",
            "STRID": "908074",
            "StreetName": "Höchweid",
            "TownName": "Werthenstein",
            "ZipAddition": "00",
            "ZipCode": "6106"
        },
        "Status": 0
    }
}

Property	Meaning
Canton	Canton
CountryCode	Country code, such as CH or LI
HouseKey	Unique building key
HouseNo	House number
HouseNoAddition	House number supplement
ONRP	Swiss Post classification number
PSTAT	Postal validation status
STRID	Street ID
StreetName	Street name
TownName	Town name
ZipAddition	Postcode addition (fifth and sixth digit)
ZipCode	Four-digit postcode

4.5.1 PSTAT

PSTAT has the following definition:

1	ok	The address is correct for 'Street name', 'House number', 'Postcode' and 'Location'.
2	standardised	The address could be normalised according to Post CH Ltd.'s guidelines for addresses. Example: 'Rosenstr.' to 'Rosenstrasse', 'Av. de la Gare' to 'Avenue de la Gare'
3	changed	Spelling mistakes in the address could be corrected. Example: 'Tulppenstrasse' to 'Tulpenstrasse', '6084' to '6048', 'Hergiswil LU' to 'Hergiswil bei Willisau'
4	supplemented	Information missing from the address can be supplemented: e.g.: missing postcodes or place names, missing house numbers (only house number on this street).
5	archive input	The entry contained addresses with alternative terms. Example: 'Oberbüel' to 'Oberbühl'
6	Partial supplement	The address could not be standardized/corrected according to Swiss Post guidelines in sub-areas (street designation, postcode, town name). The postal address is not yet correct, however.
7	invalid	Most common reasons: Capture errors: The address does not exist in this form, as several of the elements "street", "postcode" or "Location" does not match the other elements. Street is not included in the reference data: The Swiss Post leads only those buildings/street names, which are postally operated. The input address is written identical to the output fields.
8	ambiguous	As a result several addresses will come into question. The input dataset will be applied to the output file.
9	unchecked	The requested entered country is not listed in «postal validation» and therefore cannot be checked. Not checked if the address can be identified by a prefix (not equal to "CH", "LI", "FL") and/or the length of the postcode as a foreign address. The input address is written 1:1 into the output fields.
10	Error	Due to an error (e.g. postcode in name of city, empty input fields, house-number only given for street, house-number comprises alphabetical characters only, greater than 5 characters, therefore it was not possible to produce a result. The input address is written 1:1 into the output fields.

4.6 Outdated or internal methods

The methods listed below are outdated or are used for internal purposes. However, the obsolete methods are still supported due to backward compatibility.

Method	Description
RunQuery	Has been replaced by the simplified "RunQuery2" call.
RunQueryParalell	Is used for internal purposes.
RunQuery2Parallel	Is used for internal purposes.
QueryAutoComplete	Has been replaced by the extended method "QueryAutoComplete4".
QueryAutoComplete2	Has been replaced by the extended method "QueryAutoComplete4".
QueryAutoComplete3	Has been replaced by the extended method “QueryAutoComplete4”.
QueryGeoLocation	Is used for internal purposes.
BuildingVerification	Has been replaced by the extended method “BuildingVerification4”.
BuildingVerification2	Has been replaced by the extended method “BuildingVerification4”.

5. Supported field names

You can use the following field names in a query request:

Field	Description
Prename_in	First name
Prename2_in	First name 2
Name_in	Last name
MaidenName_in	Maiden name
StreetName_in	Street name
HouseNo_in	House number
HouseNoAddition_in	House number addition
ZIPCode_in	Postcode
ZIPAddition_in	Position 5 and 6: postcode
TownName_in	Town name
CountryCode_in	Country code
Company_in	Company name
HouseKey_in	House key
POBoxNo_in	P.O. Box number
POBoxZIP_in	P.O. Box postcode
POBoxZIPAddition_in	Position 5 and 6: P.O. Box postcode
POBoxTownName_in	P.O. Box location
AddressAddition_in	Additional address information
Canton_in	Canton
POBoxTerm_in	P.O. Box term such as “P.O. Box”, “Postfach”, “Case Postale”, “Casella Postale”
YearOfBirth_in	Year of birth
SexCode_in	Gender code or salutation
PassThrough_01 PassThrough_02 PassThrough_03 PassThrough_04 PassThrough_05 PassThrough_06 PassThrough_07 PassThrough_08 PassThrough_09 PassThrough_10 PassThrough_11 PassThrough_12 PassThrough_13 PassThrough_14 PassThrough_15 PassThrough_16 PassThrough_17 PassThrough_18 PassThrough_19 PassThrough_20	Fields for entering personal data. To use these, this must be arranged in advance with the Address Competence Center.
CoAddress_in	c/o address
Floor_in	Floor

6. QSTAT / QSTAT_ShortReport

The status “QSTAT” is used to make a statement about the quality of an address.

A distinction is made between the primary and secondary status:

For the primary status (= QSTAT), the quality of each address is clear at a glance.

The secondary status (= ShortReport) shows in detail which part of an address has been corrected or standardized and which address parts are correct.

6.1 QSTAT

After processing by Swiss Post, the quality and topicality of each individual address is reported with one of the following “QSTAT” primary statuses:

Status QSTAT	Designation	Description
1	Person hit	This person (first names and last name) is known at this address and items can be delivered.
2	Household hit	This household or last name (regardless of the first name) is known at this address and items can be delivered.
3	Company hit	This company is known at this address and items can be delivered.
4	Relocation hit	A movers’ address is available for this person or company.
25	Deceased / Company no longer in business	This person is deceased or this company is no longer in business.
26	International relocation hit	An unverified international address is available for this person or company.
27	Relocated, unknown	This person or company is no longer located at this address. The new address is unknown or is not permitted to be disclosed.
50	Person unknown at this address	The person, company or household is unknown at this address.
51	Address unknown	This address is incorrect or incomplete.

If applicable, these duplicate results will also be reported electronically for every address in addition to the address maintenance status messages:

Status QSTAT	Designation	Description	Return delivery
K	Original	This address is contained in the address database several times and corresponds to a high degree with the other data records of the duplicate group.	Address maintenance status message Status message K Duplicate group number Any standardization, correction, supplementary and/or update data Match probability
F	Duplicate	This address is contained in the address database several times and does not correspond as much with the other data records of the duplicate group.	Address maintenance status message Status message F Duplicate group number Any standardization, correction, supplementary and/or update data Match probability

6.2 QSTAT_ShortReport

With the help of the QSTAT ShortReport, the type of result can be evaluated and the reason for an unsuccessful request can be ascertained in greater detail. The 24-digit ShortReport is constructed as follows:

Position	Definition	Desription
1	Company (Company_in)	Company name
2	Prename (Prename_in)	First name
3	Prename2 (Prename2_in)	First name 2
4	Name (Name_in)	Last name
5	MaidenName (MaidenName_in)	Maiden name
6	AddressAddition (Addressaddition_in)	Additional address information
7	coAddress (coAddress_in)	c/o address
8	StreetName (Streetname_in)	Street
9	HouseNo (HouseNo_in)	House number
10	HouseNoAddition (HouseNoAddition_in)	House number additional information
11	Floor (Floor_in)	Floor number
12	ZIPCode (ZipCode_in)	Postcode
13	ZIPAddition (ZIPAddition_in)	Postcode additional information
14	TownName (TownName_in)	Town
15	Canton (Canton_in)	Canton abbreviation
16	CountryCode (CountryCode_in)	Country code
17	PoBoxTerm (PoBoxTerm_in)	P.O. Box designation
18	PoBoxNo (PoBoxNo_in)	P.O. Box number
19	PoBoxZIP (PoBoxZIP_in)	P.O. Box postcode
20	PoBoxZIPAddition (PoBoxZIPAddition_in)	P.O. Box postcode additional information
21	PoBoxTownName (PoBoxTownName_in)	P.O. Box town
22	Address type	Address type
23	Source type	Source of the information
24	Address status	Additional address information

Characters	Description	Detailed description
-	No statement	Input content not analysed.
1	Compliance	Input content checked: OK, complete compliance.
2	Hit with discrepancy	Input content checked: spelling standardized, discrepancies compared to the official spelling detected (concerns abbreviations, spelling mistakes, accents, etc.), hit with discrepancy – information has not been corrected.
3	Changed	Input content checked: correction of address elements or address elements identified as archive input and replaced by official designation in output (concerns alternative/foreign-language designations).
4	Supplemented	Input content checked: missing information could be completed (additional house number information, canton abbreviation, etc.).
5	New information	Input content checked: information concerning a move has been found for the address checked.
6	Blocked forwarding information	Input content checked: blocked information concerning a move exists for the address checked. Post CH Ltd is not authorized to forward the new address.
9	Deleted	Input content checked: the information concerning the address checked is no longer valid and has been deleted.
0	No hit	Input content checked: no suitable information has been found in the Post CH Ltd reference data concerning the address checked.
A-Z	Special	Definition according to the field (e.g. address type) or special case for a specific product.

Exemples of ShortReport:

Example: Active correct consumer address

Position of the string	Concerns address element	Input	Reference	ShortReport
1	Company	-	-	-
2	Prename	Max	Max	1
3	Prename2	-	-	-
4	Name	Muster	Muster	1
5	MaidenName	-	-	-
6	AddressAddition	-	-	-
7	coAddress	-	-	-
8	StreetName	Dorfstrasse	Dorfstrasse	1
9	HouseNo	4	4	1
10	HouseNoAddition	-	-	-
11	Floor	-	-	-
12	ZipCode	6010	6010	1
13	ZipAddition	0	0	1
14	TownName	Kriens	Kriens	1
15	Canton	LU	LU	1
16	CountryCode	CH	CH	1
17	PoBoxTerm	-	-	-
18	PoBoxNumber	-	-	-
19	PoBoxZip	-	-	-
20	PoBoxAddition	-	-	-
21	PoBoxTownName	-	-	-
22	Address type	-	-	-
23	Source type	-	-	-
24	Address status	-	-	A
QSTAT	-	-	-	1

Example: Consumer address with active forwarding order

Position of the string	Concerns address element	Input	Reference	ShortReport
1	Company	-	-	-
2	Prename	Hans	Hans	-
3	Prename2	-	-	-
4	Name	Müller	Müller	-
5	MaidenName	-	-	-
6	AddressAddition	-	-	5
7	coAddress	-	-	5
8	StreetName	Bahnhofstasse	Dorfstrasse	5
9	HouseNo	16	235	5
10	HouseNoAddition	-	-	5
11	Floor	-	-	5
12	ZipCode	6004	3933	5
13	ZipAddition	0	0	5
14	TownName	Luzern	Staldenried	5
15	Canton	-	VS	5
16	CountryCode	-	CH	5
17	PoBoxTerm	-	-	5

Position of the string	Concerns address element	Input	Reference	ShortReport
18	PoBoxNumber	-	-	5
19	PoBoxZip	-	-	5
20	PoBoxAddition	-	-	5
21	PoBoxTownName	-	-	5
22	Address type	-	-	A
23	Source type	-	-	-
24	Address status	-	-	A
QSTAT	-	-	-	4

7. Authentication

Authentication is conducted via an HTML basic authentication. The authentication should be “pre-emptive”.

A technical user is required for authentication. To create this user, a customer login is required on www.swisspost.ch for business customers with a billing relationship. If a customer has such a login, they can log in to the www.swisspost.ch website and create a new technical user via the Customer Center.

8. Query status messages

For every query, the service provides a status message.

8.1 Standard

NoError

The query was successful.

8.2 Authentication

101	AuthenticationFailed	Authentication failed.
102	AuthenticationUserUnknown	Unknown user.
103	AuthenticationUserMissingRole	The key entered is unknown.
104	AuthenticationUserNotOwner	The request fidoes not belong to the user indicated during the query.
105	AuthenticationUserNoRrnPermissions	The user is not authorized to call up methods with automatic settlement
106	AuthenticationUserMaxRequestsReached	The maximum number of queries per minute has been reached.

8.3 Service bridge error

201	InternalServerCallFailed	An internal error has occurred in the service.
202	InternalServerCall	An internal error has occurred in the service.
203	InternalServerCall	The query lasted longer than the defined timeout.

8.4 Database error

301	DatabaseOperationFailed	An error occurred when accessing the database.
302	DatabaseItemNotFound	An error occurred when accessing the database.

8.5 Calculation error

401	SettlementCreateFailed	An error occurred when recording the number for calculation purposes.
402	RrnInvalidFormat	The specified invoice reference number has an invalid format
403	RrnNotActiv	The specified invoice reference number is not active
404	RrnUnknown	The specified invoice reference number is invalid

8.6 Parameter error

501

UploadFileLimitReached

The maximum number of files to be uploaded per minute has been reached.

8.7 Unknown error

999

UnknownError

Unknown error.

9. Test environment

Swiss Post provides its business customers with a test environment for developing and testing their software free of charge. It contains approximately 130,000 pieces of outdated reference data from the following postcode areas:

2502	4325	5070	5078	5277
2503	4332	5072	5082	6614
2504	4333	5073	5083	8154
2505	4334	5074	5085	8165
3333	5026	5075	5225
4322	5027	5076	5237
4324	5028	5077	5272

The login for a test account, consisting of the name of a technical user and password, can be ordered free of charge from the Address Competence Center in Kriens.

There are no test or integration environments required for the Address assistant. You can access the production environment directly.

9.1 Connection via REST

Communication with the web service is performed via a REST/JSON-interface:

Test

https://webservices-int.post.ch:17029/IN_SYNSYN_EXT_TEST/REST/v1

Integration

https://webservices-int.post.ch:17023/IN_SYNSYN_EXT_INT/REST/v1

Production

https://webservices.post.ch:17023/IN_SYNSYN_EXT/REST/v1/

The transfer is solely performed via HTTPS (encrypted communication).

10. Error-tolerant alignment

Alignment of the Swiss Post reference database with the business customer address data to be cleaned up is carried out with error-tolerant software developed internally by Swiss Post. The following table lists the most important alignment elements:

Element	Description
General comparison operations
Absolute consistency	Determines the absolute consistency of two character strings with no tolerance
Relative consistency	Standardizes the character strings before the comparison by adjusting upper and lower case, removing special characters and adapting umlauts
Distance comparison	Determines the distance between two character strings, checking how many operations are required to match the strings
Token comparison	Splits the character strings into individual components before separation and compares the individual elements with each other
Phonetic comparison	Determines the consistency of two character strings on the basis of phonetic similarity (George v Georgie, Pignatelli v Biniatelli)
Alias comparison	Determines the consistency of two character strings that are matched with alias terms (Elizabeth, Beth, Ella, Eliza, Betty, Liz, Lizzy)
Field type-specific comparison operations
House number comparison	Compares two house numbers and checks house number-specific elements such as numeric part, additional house number information, exchanged digits, etc.
Postcode comparison	Compares two postcodes and checks postcode-specific elements such as four-digit or six-digit postcodes, exchanged digits, etc.
Street comparison	Compares two street names, ignoring typical identifiers such as “road”, “street”, “avenue”, etc. if they occur in both character strings
Company comparison	Compares two company names, ignoring typical identifiers such as “Ltd.”, “Inc.”, “PLC”, etc. if they occur in both character strings
First name comparison	Compares first names, distinguishing between male and female spellings
Date comparison	Compares date values, recognizing different formats and partial matches

The basis for evaluating a search result is the match probability, which defines how exactly the input data record matches the search result. The match probability is assigned collectively. By default, no search results with a match probability of less than 94% are returned.

11. Description of obsolete methods

12. Technical description / Web service information

Components

Application servers and database servers; the application servers are also used as database servers.

Data storage / backup / archiving

Data is stored on the central Post CH Ltd systems on servers in Switzerland. Data is secured using redundant Post CH Ltd systems.

Environments

A production, integration and test environment are available for this service.

Service levels

Support hours: Mon-Fri, 8 a.m. to 12 noon, 1.30 p.m. to 5 p.m.
Languages: German, French, English

Contact

Tel. +41 58 386 67 67
address-maintenance@swisspost.ch

Footer

Additional links

Facebook Twitter [SocialMedia | instagram] Youtube LinkedIn Xing