| Inhalt |
|---|
Allgemeine Informationen
Das PostService-Plugin von JAXForms liefert in Adressfeldern Vorschläge für PLZ, Ort und Strasse. Es führt dazu keine eigene Adressliste, sondern fragt bei jeder Eingabe live den Adress-Webservice der Schweizerischen Post ab und übernimmt die gelieferten Werte unverändert ins Formular.
Diese Seite beschreibt den verwendeten Webservice, die Struktur von Request und Answer sowie Beispiele für die drei Suchen PLZ, Ort und Strasse.
| Thema | Angabe |
|---|---|
| Anbieter | Post CH AG, Produkt «Adress Web Services» (Adressassistent) |
| Schnittstelle | REST/JSON über HTTPS |
| Methode für Vorschläge | POST /autocomplete2 (QueryAutoComplete2) |
| URL Produktion | https://webservices.post.ch:17023/IN_SYNSYN_EXT/REST/v1 |
| URL Integration | https://webservices-int.post.ch:17023/IN_SYNSYN_EXT_INT/REST/v1 |
| URL Test | https://webservices-int.post.ch:17029/IN_SYNSYN_EXT_TEST/REST/v1 |
| Datengrundlage | Referenzdaten der Post («Swiss Post reference data»). Enthalten sind nur postalisch bediente Strassen und Gebäude der Schweiz und des Fürstentums Liechtenstein. |
Quelle der Angaben
Technische Spezifikation «Address web services REST» im Entwicklerportal der Post (Kapitel 4.4, 4.6, 7, 8, 9 und 11). Stand: 12.11.2026 sind die Seiten unter developer.post.ch nicht erreichbar; gelesen wurden die archivierten Fassungen vom 21.05.2026 und 10.06.2026.
https://web.archive.org/web/20260521015423/https://developer.post.ch/en/address-web-services-rest
Schnittstelle
Request
request*: {
HouseKey*: Zahl
HouseNumber*: Text
HouseNumberAddition*: Text
Onrp*: Zahl
Streetname*: Text
StrId*: Zahl
TownName*: Text
ZipAddition*: Text
Zipcode*: Text
}
zipOrderMode*: Zahl
| Feld | Typ | Vom Plugin befüllt | Beschreibung |
|---|---|---|---|
Zipcode | Text | ✔ | PLZ oder Anfang einer PLZ. Suchbegriff der PLZ-Suche, Einschränkung bei der Strassensuche. |
TownName | Text | ✔ | Ortsname oder Wortanfang davon. Suchbegriff der Ortssuche. |
Streetname | Text | ✔ | Strassenname oder Wortanfang davon. Suchbegriff der Strassensuche. |
HouseNumber | Text | ❌ | Hausnummer. Bleibt leer. |
HouseNumberAddition | Text | ❌ | Hausnummer-Zusatz. Bleibt leer. |
ZipAddition | Text | ❌ | PLZ-Zusatzziffer. Bleibt leer. |
Onrp | Zahl | ❌ | Ordnungsnummer Post (Schlüssel von PLZ/Ort). Immer 0. |
StrId | Zahl | ❌ | Schlüssel der Strasse. Immer 0. |
HouseKey | Zahl | ❌ | Schlüssel des Gebäudes. Immer 0. |
zipOrderMode | Zahl | ✔ | Sortierung der Treffer. Das Plugin sendet immer 0. |
Anmerkung: Das Plugin sendet immer alle Felder. Nicht verwendete Textfelder sind leer, nicht verwendete Schlüssel haben den Wert 0.
Answer
QueryAutoComplete2Result*: {
AutoCompleteResult*: [ {
HouseKey*: Zahl
HouseNumber*: Text
HouseNumberAddition*: Text
Onrp*: Zahl
StrId*: Zahl
Streetname*: Text
TownName*: Text
ZipAddition*: Text
Zipcode*: Text
} ]
Status*: Zahl
}
| Feld | Typ | Max. Länge | Beschreibung |
|---|---|---|---|
Zipcode | Text | 4 | Vierstellige PLZ. |
ZipAddition | Text | 2 | PLZ-Zusatzziffer (fünfte und sechste Stelle). Unterscheidet gleichlautende vierstellige PLZ. |
TownName | Text | 27 | Ortsbezeichnung (lange Form). JAXForms schreibt sie unverändert ins Ort-Feld. |
Onrp | Zahl | – | Ordnungsnummer Post. Eindeutiger, unveränderlicher Schlüssel von PLZ/Ort. |
Streetname | Text | 60 | Strassenname in der Schreibweise der Post. Leer bei Treffern auf Ortsebene. |
StrId | Zahl | – | Schlüssel der Strasse. 0 bei Treffern auf Ortsebene. |
HouseKey | Zahl | 19 | Schlüssel des Gebäudes. 0 bei Treffern auf Orts- oder Strassenebene. |
HouseNumber | Text | 40 | Hausnummer. Leer bei Treffern auf Orts- oder Strassenebene. |
HouseNumberAddition | Text | 6 | Hausnummer-Zusatz. Leer bei Treffern auf Orts- oder Strassenebene. |
Status | Zahl | – | 0 = Abfrage erfolgreich. |
Anmerkung zu den Längen: Die Spezifikation der Post enthält für die Autocomplete-Answer keine eigene Längentabelle. Die Werte stammen aus der «Data output structure» (Kapitel 1.3.3 und 3.3.3, Spalte «Maximum field length») desselben Service, die dort für Adresspflege und Adressprüfung gilt. Die Felder heissen dort ZIPcode, ZIPAddition, TownName, Streetname, Housekey, HouseNo und HouseNoAddition. Für Onrp, StrId und Status nennt die Spezifikation keine Länge.
Verhaltensregeln
Suchebene
Die Suchebene (Ort, Strasse oder Gebäude) wird nicht über einen Parameter gewählt. Sie ergibt sich daraus, welche Felder im Request gefüllt sind.
| Suche im Plugin | Suchtyp | Gefüllte Felder | Treffer |
|---|---|---|---|
| PLZ | PLZ | Zipcode = Eingabe | Orte mit passender PLZ |
| Ort | ORT | TownName = Eingabe | Orte mit passendem Namen |
| Strasse | STRASSE | Streetname = Eingabe, Zipcode = Wert des PLZ-Felds im Formular | Strassen im Gebiet der PLZ |
Beispiel-Daten
Alle Requests gehen per POST an {BASIS_URL}/autocomplete2.
PLZ
Request: PLZ-Suche mit «1374»
Answer: ein Ort, Ortsbezeichnung mit 23 Zeichen
Request: PLZ-Suche mit «2206»
Answer: ein Ort, Ortsbezeichnung mit 25 Zeichen
Ort
Request: Ortssuche mit «Aarau»
Answer
Strasse
Request: Strassensuche mit «Frankl», eingeschränkt auf die PLZ 8050
Answer: eine Strasse, mit Schlüssel der Strasse und des Orts