Address web services SOAP
Technical specifications of the Address web service for SOAP
Version November 2023
(for REST 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 SOAP 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. For the customer-specific settings and to enable the alignment, you must create a configuration with the Address Competence Center first.
You can find details on the batch alignment process 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.
Using the individual address query, the output structure can be defined individually together with the Address Competence Center.
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
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.
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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:Ping/> </soapenv:Body></soapenv:Envelope>Parameters
This operation has no parameters.
Response
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<PingResponse xmlns="http://tempuri.org/"/>
</s:Body>
</s:Envelope>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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:UploadFile> <tem:data>cid:input.txt</tem:data> </tem:UploadFile> </soapenv:Body></soapenv:Envelope>Parameters
| Element | Data type
| Content type | MIME type |
|---|---|---|---|
| data
| Binary data stream
| binary
| application/octet-stream
|
Note
The web service only processes binary data streams which have been defined with the content transfer encoding “binary”.
The SOAP Message Transmission Optimization Mechanism (MTOM) must be activated in order to use this method. You can find further information about MTOM at https://www.w3.org/TR/soap12-mtom/Target not accessible
Depending on the implementation of the library used for SOAP access, the data type must also be specified explicitly for the request. A request would then look like this:
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:UploadFile> <tem:data> <inc:Include href=" cid:input.txt" xmlns:inc="https://www.w3.org/2004/08/xop/include"/> </tem:data> </tem:UploadFile> </soapenv:Body></soapenv:Envelope>Response
The response returned is the status of the request and, if successful, a token which defines the uploaded file in the service.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <UploadFileResponse xmlns="https://tempuri.org/"> <UploadFileResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataCon-tracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:FileToken>f67e73ff-361a-451d-aec4-5e6832bfc4ce</a:FileToken> <a:Status>0</a:Status> </UploadFileResult> </UploadFileResponse> </s:Body></s:Envelope>4.2.2 Define output files
For each output file from the alignment, a file must be created in the service.
Request
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:CreateFile/> </soapenv:Body></soapenv:Envelope>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.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <CreateFileResponse xmlns="https://tempuri.org/"> <CreateFileResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataCon-tracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:FileToken>b098f5e3-1d17-43a6-948c-4ff7bb3b67c3</a:FileToken> <a:Status>0</a:Status> </CreateFileResult> </CreateFileResponse> </s:Body></s:Envelope>4.2.3 Start processing
To start the batch alignment, the “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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:RunBatch> <tem:key>kca</tem:key> <tem:replaceItems> <syn:ReplaceItem> <syn:Search>{###INPUTFILE###}</syn:Search> <syn:Replacement>f67e73ff-361a-451d-aec4-5e6832bfc4ce</syn:Replacement> </syn:ReplaceItem> <syn:ReplaceItem> <syn:Search>{###OUTPUTFILE###}</syn:Search> <syn:Replacement>b098f5e3-1d17-43a6-948c-4ff7bb3b67c3</syn:Replacement> </syn:ReplaceItem> </tem:replaceItems> </tem:RunBatch> </soapenv:Body></soapenv:Envelope>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:
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <RunBatchResponse xmlns="https://tempuri.org/"> <RunBatchResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:BatchToken>3f1b255c-3fc8-49b5-9f19-d8e9d1dc1600</a:BatchToken> <a:SettlementId>57</a:SettlementId> <a:Status>0</a:Status> </RunBatchResult> </RunBatchResponse> </s:Body></s:Envelope>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 “RunBatchWithClient” method can be used. The client’s invoice reference number, the clientname or the clientidentfier will be provided in addition to the replacements and the alignment key. The user submitting the query must be authorized for this purpose.
Request
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts">
<soapenv:Header/>
<soap-env:Body>
<tem:RunBatchWithClient>
<tem:key>kca</tem:key>
<tem:replaceItems>
<syn:ReplaceItem>
<syn:Search>{###INPUTFILE###}</syn:Search>
<syn:Replacement>f67e73ff-361a-451d-aec4-5e6832bfc4ce</syn:Replacement>
</syn:ReplaceItem>
<syn:ReplaceItem>
<syn:Search>{###OUTPUTFILE###}</syn:Search>
<syn:Replacement>b098f5e3-1d17-43a6-948c-4ff7bb3b67c3</syn:Replacement>
</syn:ReplaceItem>
</tem:replaceItems>
<tem:billingReferenceNumber>11223344</tem:billingReferenceNumber>
<tem:clientIdentifier>1999</tem:clientIdentifier>
<tem:clientName>Example Ltd.</tem:clientName>
</tem:RunBatchWithClient>
</soap-env:Body>
</soapenv:Envelope>
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. |
| clientIdentifier | string | A uniquely assignable identifier for third-party customers, which the service provider can use to distinguish for which third-party customer the reconciliation was carried out. |
| clientName | string | Name of third-party customer |
Response
Identical to the “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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:CheckBatchStatus> <tem:token>a09572ab-a864-43d7-ad17-305727b8d462</tem:token> </tem:CheckBatchStatus> </soapenv:Body></soapenv:Envelope>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.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <CheckBatchStatusResponse xmlns="https://tempuri.org/"> <CheckBatchStatusResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:BatchStatus> <a:LastUpdateDateTime>2016-03-03T13:34:24.85</a:LastUpdateDateTime> <a:Message>Module 'Datenimport' is Running</a:Message> <a:Progress>25</a:Progress> <a:RemainingTimeSeconds>120</a:RemainingTimeSeconds> <a:StartDateTime>2016-03-03T13:33:56.427</a:StartDateTime> <a:TokenStatus>Running</a:TokenStatus> </a:BatchStatus> <a:Status>0</a:Status> </CheckBatchStatusResult> </CheckBatchStatusResponse> </s:Body></s:Envelope>The individual properties have the following meanings:
| Property
|
Meaning |
|---|---|
| LastUpdateDateTime
|
Time of the last update in UTC 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:DownloadFile> <tem:token>f67e73ff-361a-451d-aec4-5e6832bfc4ce</tem:token> </tem:DownloadFile> </soapenv:Body></soapenv:Envelope>Parameters
| Element | Data type
| Description
|
|---|---|---|
| token
| string
| The file token for the file to be downloaded
|
Note
The SOAP Message Transmission Optimization Mechanism (MTOM) must be activated in order to use this method. You can find further information about MTOM at https://www.w3.org/TR/soap12-mtom/Target not accessible
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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:DeleteFile> <tem:fileToken>1bbeea87-8132-4c1f-afa3-ebb61a346c16</tem:fileToken> </tem:DeleteFile> </soapenv:Body></soapenv:Envelope>Parameters
| Element | Data type | Description |
|---|---|---|
| fileToken | string | The file token for the file to be deleted |
Response
The response is structured as defined below.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <DeleteFileResponse xmlns="https://tempuri.org/"> <DeleteFileResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:Status>0</a:Status> </DeleteFileResult> </DeleteFileResponse> </s:Body></s:Envelope>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.
The method to use is "RunQuery2".
Request
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.
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:RunQuery2> <tem:address> <syn:Data> <syn:DataField2> <syn:FieldName>Prename_in</syn:FieldName> <syn:Value>Hans</syn:Value> </syn:DataField2> <syn:DataField2> <syn:FieldName>Name_in</syn:FieldName> <syn:Value>Muster</syn:Value> </syn:DataField2> <syn:DataField2> <syn:FieldName>StreetName_in</syn:FieldName> <syn:Value>Sternmatt</syn:Value> </syn:DataField2> <syn:DataField2> <syn:FieldName>HouseNo_in</syn:FieldName> <syn:Value>6</syn:Value> </syn:DataField2> <syn:DataField2> <syn:FieldName>ZIPCode_in</syn:FieldName> <syn:Value>6010</syn:Value> </syn:DataField2> <syn:DataField2> <syn:FieldName>TownName_in</syn:FieldName> <syn:Value>Kriens</syn:Value> </syn:DataField2> </syn:Data> <syn:Id>1</syn:Id> </tem:address> <tem:key>kca</tem:key> <tem:timeout>10000</tem:timeout> </tem:RunQuery2> </soapenv:Body></soapenv:Envelope>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.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <RunQueryResponse xmlns="https://tempuri.org/"> <RunQueryResult xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:MatchResult> <a:FieldScore xmlns:b="https://schemas.microsoft.com/2003/10/Serialization/Arrays"/> <a:Results> <a:Data> <a:DataField> <a:EmptyMatch>false</a:EmptyMatch> <a:FieldName>Trefferwahrscheinlichkeit</a:FieldName> <a:FieldType>Undefined</a:FieldType> <a:Value>100</a:Value> </a:DataField> </a:Data> <a:Id>0</a:Id> </a:Results> <a:Score>0</a:Score> </a:MatchResult> <a:SettlementId>59</a:SettlementId> <a:Status>0</a:Status> </RunQueryResult> </RunQueryResponse> </s:Body></s:Envelope>The individual properties have the following meanings:
| Property
|
Meaning |
|---|---|
| DataField
|
An address component
|
| FieldName
|
Field name that can be used to assign the address element value
|
| Value
|
Address element value |
| Settlement
|
Invoicing ID
|
| Status
|
Query status. See “Query status messages”
|
4.3.1 Individual address queries for clients
To start an individual address query for a client, the “RunQuery2WithClient” method can be used. The client’s invoice reference number, the clientname or the clientidentfier 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
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.
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts">
<soapenv:Header/>
<soapenv:Body>
<tem:RunQuery2WithClient>
<tem:address>
<syn:Data>
<syn:DataField2>
<syn:FieldName>Prename_in</syn:FieldName>
<syn:Value>Hans</syn:Value>
</syn:DataField2>
<syn:DataField2>
<syn:FieldName>Name_in</syn:FieldName>
<syn:Value>Muster</syn:Value>
</syn:DataField2>
<syn:DataField2>
<syn:FieldName>StreetName_in</syn:FieldName>
<syn:Value>Sternmatt</syn:Value>
</syn:DataField2>
<syn:DataField2>
<syn:FieldName>HouseNo_in</syn:FieldName>
<syn:Value>6</syn:Value>
</syn:DataField2>
<syn:DataField2>
<syn:FieldName>ZIPCode_in</syn:FieldName>
<syn:Value>6010</syn:Value>
</syn:DataField2>
<syn:DataField2>
<syn:FieldName>TownName_in</syn:FieldName>
<syn:Value>Kriens</syn:Value>
</syn:DataField2>
</syn:Data>
<syn:Id>1</syn:Id>
</tem:address>
<tem:key>kca</tem:key>
<tem:timeout>10000</tem:timeout>
<tem:billingReferenceNumber>11223344</tem:billingReferenceNumber>
<tem:clientIdentifier>1999</tem:clientIdentifier>
<tem:clientName>Example Ltd.</tem:clientName>
</tem:RunQuery2WithClient>
</soapenv:Body>
</soapenv:Envelope>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. |
| clientIdentifier | string | A uniquely assignable identifier for third-party customers, which the service provider can use to distinguish for which third-party customer the reconciliation was carried out. |
| clientName | string | Name of third-party customer |
Response
Identical to the “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 (Not: Wiesenstrasse, 5012 Schönenwerd) (Not: Haldenring, 6020 Emmenbrücke) |
| Streetname
| wies
|
4.4.1 Search for towns
The following request for the “QueryAutoComplete4” method searches for towns:
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo></syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName></syn:StreetName> <syn:TownName>n</syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode>817</syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4542</a:ONRP> <a:STRID>0</a:STRID> <a:StreetName/> <a:TownName>Niederglatt ZH</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8172</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4543</a:ONRP> <a:STRID>0</a:STRID> <a:StreetName/> <a:TownName>Neerach</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8173</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4544</a:ONRP> <a:STRID>0</a:STRID> <a:StreetName/> <a:TownName>Stadel b. Niederglatt</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8174</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope> 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“ |
| StreetName | O | |
| 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 “QueryAutoComplete4” method searches for streets with no town restriction:
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo></syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName>Alte Stationsstrasse</syn:StreetName> <syn:TownName></syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4530</a:ONRP> <a:STRID>24583</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Oberglatt ZH</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8154</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4540</a:ONRP> <a:STRID>58009546</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Niederweningen</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8166</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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“ |
| 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 “QueryAutoComplete4” method searches for streets in matching towns:
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo></syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName>Alte Stationsstrasse</syn:StreetName> <syn:TownName>Oberglatt</syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>4530</a:ONRP> <a:STRID>24583</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Oberglatt ZH</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8154</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope> 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“ |
| 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo></syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>5137</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName>stat</syn:StreetName> <syn:TownName></syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>30002</a:STRID> <a:StreetName>Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>0</a:HouseKey> <a:HouseNo/> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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“ |
| StreetName | O | |
| Town | ONRP | „0“ |
| ZipCode | O | |
| ZipAddition | - | |
| TownName | O |
“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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo>105</syn:HouseNo> <syn:HouseNoAddition>N</syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName></syn:StreetName> <syn:TownName></syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope> The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>JU</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>30039869</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>1634</a:ONRP> <a:STRID>30022575</a:STRID> <a:StreetName>Le Chênois</a:StreetName> <a:TownName>Charmoille</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>2947</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>GR</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76190424</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>3589</a:ONRP> <a:STRID>72028859</a:STRID> <a:StreetName>Quartiere Nef</a:StreetName> <a:TownName>Lostallo</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>6558</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>JU</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76243990</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>1632</a:ONRP> <a:STRID>30001307</a:STRID> <a:StreetName>Sur le Creux de Loups</a:StreetName> <a:TownName>Bonfol</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>2944</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>NE</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76488519</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>1440</a:ONRP> <a:STRID>30021239</a:STRID> <a:StreetName>La Praye</a:StreetName> <a:TownName>Lignières</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>2523</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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“ |
| StreetName | X | |
| Town | ONRP | „0“ |
| ZipCode | O | |
| ZipAddition | - | |
| TownName | O |
“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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo>105</syn:HouseNo> <syn:HouseNoAddition>N</syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName>le</syn:StreetName> <syn:TownName></syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope> The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>JU</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76243990</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>1632</a:ONRP> <a:STRID>30001307</a:STRID> <a:StreetName>Sur le Creux de Loups</a:StreetName> <a:TownName>Bonfol</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>2944</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>JU</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>30039869</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>N</a:HouseNoAddition> <a:ONRP>1634</a:ONRP> <a:STRID>30022575</a:STRID> <a:StreetName>Le Chênois</a:StreetName> <a:TownName>Charmoille</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>2947</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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“ |
| 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo>105</syn:HouseNo> <syn:HouseNoAddition>b</syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName></syn:StreetName> <syn:TownName>zh</syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57524080</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>B</a:HouseNoAddition> <a:ONRP>4659</a:ONRP> <a:STRID>26183</a:STRID> <a:StreetName>Russikerstrasse</a:StreetName> <a:TownName>Pfäffikon ZH</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8330</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76428690</a:HouseKey> <a:HouseNo>105</a:HouseNo> <a:HouseNoAddition>B</a:HouseNoAddition> <a:ONRP>4990</a:ONRP> <a:STRID>28408</a:STRID> <a:StreetName>Lerchenbergstrasse</a:StreetName> <a:TownName>Erlenbach ZH</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8703</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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 |
| 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo>1</syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>75022</syn:STRID> <syn:StreetName></syn:StreetName> <syn:TownName></syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode></syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57513045</a:HouseKey> <a:HouseNo>10</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57513049</a:HouseKey> <a:HouseNo>14</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57513051</a:HouseKey> <a:HouseNo>16</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>58051422</a:HouseKey> <a:HouseNo>1</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76129508</a:HouseKey> <a:HouseNo>11</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76200318</a:HouseKey> <a:HouseNo>12</a:HouseNo> <a:HouseNoAddition>A</a:HouseNoAddition> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76200319</a:HouseKey> <a:HouseNo>12</a:HouseNo> <a:HouseNoAddition>B</a:HouseNoAddition> <a:ONRP>5137</a:ONRP> <a:STRID>75022</a:STRID> <a:StreetName>Alte Stationsstrasse</a:StreetName> <a:TownName>Bonstetten</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8906</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>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“ |
| StreetName | X | |
| 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/" xmlns:syn="https://schemas.datacontract.org/2004/07/SynSrvDataContracts"> <soapenv:Header/> <soapenv:Body> <tem:QueryAutoComplete4> <tem:request> <syn:HouseKey>0</syn:HouseKey> <syn:HouseNo>15</syn:HouseNo> <syn:HouseNoAddition></syn:HouseNoAddition> <syn:ONRP>0</syn:ONRP> <syn:STRID>0</syn:STRID> <syn:StreetName>weg</syn:StreetName> <syn:TownName>w</syn:TownName> <syn:ZipAddition></syn:ZipAddition> <syn:ZipCode>8</syn:ZipCode> </tem:request> <tem:zipOrderMode>NumericAscending</tem:zipOrderMode> <tem:zipFilterMode>AllZip</tem:zipFilterMode> </tem:QueryAutoComplete4> </soapenv:Body></soapenv:Envelope>The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryAutoComplete4Response xmlns="https://tempuri.org/"> <QueryAutoComplete4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:AutoCompleteResult> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57231933</a:HouseKey> <a:HouseNo>15</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>4690</a:ONRP> <a:STRID>67626</a:STRID> <a:StreetName>Salomon-Bleuler-Weg</a:StreetName> <a:TownName>Winterthur</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8400</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76503064</a:HouseKey> <a:HouseNo>15</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>4708</a:ONRP> <a:STRID>76141453</a:STRID> <a:StreetName>Wegackerstrasse</a:StreetName> <a:TownName>Winterthur</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8405</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>76267671</a:HouseKey> <a:HouseNo>15</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>4710</a:ONRP> <a:STRID>76118558</a:STRID> <a:StreetName>Maria-Kübler-Weg</a:StreetName> <a:TownName>Winterthur</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8406</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>58139878</a:HouseKey> <a:HouseNo>15</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5064</a:ONRP> <a:STRID>29691</a:STRID> <a:StreetName>Julius-Hauser-Weg</a:StreetName> <a:TownName>Wädenswil</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8820</a:ZipCode> </a:AutoCompleteData3> <a:AutoCompleteData3> <a:Canton>ZH</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>57002169</a:HouseKey> <a:HouseNo>15</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>5064</a:ONRP> <a:STRID>29692</a:STRID> <a:StreetName>Karl-Stamm-Weg</a:StreetName> <a:TownName>Wädenswil</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>8820</a:ZipCode> </a:AutoCompleteData3> </a:AutoCompleteResult> <a:Status>0</a:Status> </QueryAutoComplete4Result> </QueryAutoComplete4Response> </s:Body></s:Envelope>4.4.4 zipOrderMode
The zipOrderMode element can be used to define how the output is sorted. There are three different modes:
| Mode
| Effect |
|---|---|
| NumericAscending | The output is sorted in ascending order according to postcode. All hits are displayed (default).
|
| ZipTypeNotPoBox
| The output is sorted based on the postcode type. The P.O. Box postcodes are displayed at the end.
|
| ZipPoBox
| 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
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="https://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:QueryBuildingVerification4> <!--Optional:--> <tem:streetname>Brandgässli</tem:streetname> <!--Optional:--> <tem:houseNo>10</tem:houseNo> <!--Optional:--> <tem:houseNoAddition>?</tem:houseNoAddition> <!--Optional:--> <tem:zipcode>6004</tem:zipcode> <!--Optional:--> <tem:townname>Luzern</tem:townname> </tem:QueryBuildingVerification4> </soapenv:Body></soapenv:Envelope>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 |
The service responds
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <QueryBuildingVerification4Response xmlns="https://tempuri.org/"> <QueryBuildingVerification4Result xmlns:a="https://schemas.datacontract.org/2004/07/SynSrvDataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance"> <a:BuildingVerificationData> <a:Canton>LU</a:Canton> <a:CountryCode>CH</a:CountryCode> <a:HouseKey>4065</a:HouseKey> <a:HouseNo>10</a:HouseNo> <a:HouseNoAddition/> <a:ONRP>3218</a:ONRP> <a:PSTAT>4</a:PSTAT> <a:STRID>15429</a:STRID> <a:StreetName>Brandgässli</a:StreetName> <a:TownName>Luzern</a:TownName> <a:ZipAddition>00</a:ZipAddition> <a:ZipCode>6004</a:ZipCode> </a:BuildingVerificationData> <a:Status>0</a:Status> </QueryBuildingVerification4Result> </QueryBuildingVerification4Response> </s:Body></s:Envelope>| 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:
|
| 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.
|
| Status QSTAT | Designation | Description |
|---|---|---|
| 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.
|
|
| 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.
|
|
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
|
| Position | Definition | Desription
|
|---|---|---|
| 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
|
- | - | - |
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 |
| 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
| 0 | 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 Limitations
| 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.
9.1 Connection via SOAP
Communication with the web service is performed via a SOAP/XML-interface:
Test
https://webservices-int.post.ch/IN_SYNSYN_EXT_TEST/v1
Integration
https://webservices-int.post.ch/IN_SYNSYN_EXT_INT/v1
Production
https://webservices.post.ch/IN_SYNSYN_EXT/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