Webservice Dokumentation

Vorbereitung

Damit Sie den Web-Service nutzen können muss zunächst ein Suchprofil eingerichtet werden. Beim Speichern des Suchprofils muss darauf geachtet werden, dass dieses mit der Option "Web-Service" angelegt wird:

image

Die ID des Suchprofils kann seiner URL entnommen werden, z.B

https://xplorer.ch/projects/21425/0

Wichtig:
  • Nach der Einrichtung des Suchprofils kann dieses per Webservice erst ab dem nächsten Tag abgerufen werden!
  • Neue Ergebnisse können nur an den beim Speichern des Suchprofils aktivierten Tagen abgerufen werden!

Umgebungen

url prd

https://api.xplorer.ch

Login

Um sich mit dem Web-Service zu verbinden, muss zunächst ein Login erfolgen. Dieser kann unter dem Endpunkt POST /login_check erreicht werden. Hier wird eine Anfrage mithilfe des Benutzernamens und Passwortes des zur Verfügung gestellten Benutzers gestellt.

Beispiel Login Abfrage:
Beispiel Login Ergebnis:

Ein erfolgreicher Login liefert einen JWT-Token und einen entsprechenden Refresh-Token. Ersteres wird für jeden weiteren Kontakt mit der Schnittstelle benötigt. Letzteres wird benötigt, um sich nach Ablauf des Tokens einen neuen Token ausstellen zu lassen.

Wichtig:

Wenn Sie einen normalen Benutzer haben, welcher sich nicht mehrfach gleichzeitig einloggen kann, bekommen Sie auch einen Security-Cookie. Diesen müssen Sie ebenfalls bei jedem Aufruf mit sich führen.

Beispiel:

Der JWT ist standardmässig eine Stunde lang gültig. Benötigt man eine längere Session, kann man den Token mithilfe des Refresh-Tokens unter POST /token/refresh wie folgt erneuern:

Beispiel Refresh Abfrage:

Das Ergebnis dieser Abfrage ist identisch mit der Login-Abfrage. Der Refresh-Token ist 8 Stunden lang gültig und wird ebenfalls erneuert bei jedem Aufruf.

Abholen der Daten

Mögliche Endpunkte

Name

all_pn_headers

projects

Brand

Ausschreibungen / Tenders

Projekte

Das Abholen der Daten findet über einen der o.g. Endpunkte per GET statt, z.B. /web_service/all_pn_headers/. Hierzu wird der bereits erhaltene JWT-Token und die ID von dem zuvor angelegten Suchprofil benötigt. Der Token wird mittels Authorization-Header mitgegeben. Die Suchprofil-ID mithilfe eines GET-Parameters wie folgt:

Beispiel Daten Abholen:

Diese Abfrage liefert nun, sofern vorhanden, die neuen Daten Ihres Suchprofils. Das Format der Daten kann mittels des Accept-Headers entschieden werden. Die folgenden Optionen stehen standardmässig zur Verfügung:

  • Accept: application/xml
  • Accept: application/json
  • Accept: application/ld+json

Bestätigung der Abholung

Der Web-Service liefert Ihnen die Daten Ihres Suchprofils und merkt sich dabei, was Sie bereits abgeholt haben. Standardmässig bekommen Sie 10 bzw. 20 Datensätze (Projekte bzw. Tenders) pro Aufruf der oben genannten Endpunkte. Damit eventuelle Fehler behandelt werden können, müssen Sie das Abholen jedoch bestätigen um an die nächsten 20 Datensätze zu kommen. Hierzu bieten wir Ihnen zwei Wege:

Bestätigung per Header

Wenn Sie keinen weiteren Endpunkt aufrufen wollen, können Sie direkt beim Abholen der Daten bestätigten, dass Sie die Daten erhalten haben. So bekommen Sie bei jedem Aufruf des o.g. Endpunktes neue Daten. Dies geschieht mithilfe des Headers X-AUTO-ACK. Dazu das passende Beispiel:

Beispiel Abholen Mit Auto-Ack:
Bestätigung per Endpunkt

Der sicherste Weg keine Daten zu verlieren ist es, uns nach dem Abholen separat mitzuteilen, dass Sie die Daten sauber bekommen haben. Dies geschieht mithilfe des Endpunktes POST /web_service/acknowledge/. Hierzu wird ein JSON-Objekt erwartet, welches sowohl die Suchprofil-ID von Ihnen enthält als auch die IDs der Datensätze, welche Sie uns Bestätigen wollen. Hierzu ein Beispiel:

Beispiel Ack-Endpunkt:
Field Type Description Example
id int Eindeutige Projekt-ID 312885
title string Projekt-Titel Neubau Reservoir mit Leitungsersatz
postcode int Postleitzahl 9053
country string Land CHE
town string Stadt Teufen AR
area string Gebietsbezeichnung Les Planches
street string Strassenname und Hausnummer Reservoir Häuslersegg
projectValue double Bausumme (in ganzen Währungseinheiten) 1340000
valueDescription string Bausummen Text 1.34 Mio CHF
startDate datetime Baustart 2023-05-21T22:00:00+00:00
startDateAccuracy int Wert zur Berechnung des Baustarts 12
startDescription string Baustart Text Mai 2023
endDate datetime Bauende 2024-06-29T22:00:00+00:00
endDescription string Bauende Text Juni 2024
firstPublished datetime Erstveröffentlichung 2023-01-20T10:49:16+00:00
lastPublished datetime Letzte Veröffentlichung 2023-05-23T09:13:44+00:00
lastUpdate datetime Nach Regeln definiertes letztes Update Datum eines Projektes 2023-05-23T09:13:44+00:00
topProject int ID des übergeordneten Projektes 1115
externalID int Referenz-ID zu Infopro Digital Projekten 3197834
projectRolePersons
Field Type Description Example
projectRolePersonType
Field Type Description Example
id int Eindeutige ID der Personenrolle 9
code string Eindeutiger Code der Personenrolle CH_ARCHITECT
name string Name der Personenrolle Architekt
sortOrder int Sortierung 130
deprecated boolean Zeigt an, ob der Typ noch gängig ist 0
person
Field Type Description Example
id int Eindeutige ID der Person 1548945
salutationType
Field Type Description Example
id int Eindeutige ID der Anrede 33
code string Anredecode 1
name string Name der Anrede Herr
contactSpecifications
Field Type Description Example
content string Telefon, Fax, E-Mail, oder URL, je nach Type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Telefon PHONE
name string Telefon Phone
projectType
Field Type Description Example
id int Eindeutige ID der Hauptkategorie 33
code string Eindeutiger Code der Hauptkategorie 11
name string Name der Hauptkategorie Technische Anlagen
sortOrder int Sortierreihenfolge der Hauptkategorie 50
projectResearchType
Field Type Description Example
id int Eindeutige ID des Recherchetyps 8
code string Recherchetyp-Code 1
infoText string Recherchetyp Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
sortOrder int Sortierreihenfolge des Recherchetyps 0
purpose
Field Type Description Example
id int Eindeutige ID des Verwendungszwecks 14
code string Verwendungszweckcode CH_OWN_USE
name string Name des Verwendungszwecks Eigenbedarf
planningStage
Field Type Description Example
id int Eindeutige ID des Baustadiums 19
code string Eindeutiger Code des Baustadiums CH_PASSED_IN
name string Name des Baustadiums Baugesuch eingereicht
sortOrder int Sortierreihenfolge des Baustadiums 4
projectTexts
Field Type Description Example
content string Text Neubau Reservoir mit Leitungsersatz und Forststrasse/Zugangsweg Reservoir
projectTextType
Field Type Description Example
code string Eindeutiger Code des Texttyps 1
name string Name der Textart Beschreibung
sortOrder int Sortierreihenfolge der Textart 1
projectDetails
Field Type Description Example
value string Wert des Details 15
negated boolean Zeigt an, ob der Wert negiert wird true
projectDetailType
Field Type Description Example
id int ID des Gebäudeausbaus 763
code string Code des Gebäudeausbaus CH_STRUCTURES
name string Name des Gebäudeausbaus Fenster
projectAttributes
Field Type Description Example
id int Eindeutige ID des Attributs 7911848
value string Wert des Attributs Gst. 1243, 2200, 848
projectAttributeType
Field Type Description Example
id int Eindeutige ID des Attributs 120
code string Eindeutiger Code des Attributs 1
name string Name des Attributs Einsprache
planningStageDates
Field Type Description Example
id int Eindeutige ID des Datensatzes 27447
project string URI zum Projekt /projects/312885
planningStageDate datetime Datum des Baustadiums 2023-05-23T09:13:44+00:00
planningStage
Field Type Description Example
id int Eindeutige ID des Baustadiums 19
code string Eindeutiger Code des Baustadiums CH_PASSED_IN
name string Name des Baustadiums Baugesuch eingereicht
sortOrder int Sortierreihenfolge des Baustadiums 4
projectCategories
Field Type Description Example
projectCategoryType
Field Type Description Example
id int Eindeutige ID der Unterkategorie 738
parentId int Eltern-Unterkategorie ID 679
code string Eindeutiger Code der Unterkategorie 520
name string Name der Unterkategorie Wasseraufbereitungsanlagen
projectDevelopmentType
Field Type Description Example
id int Eindeutige ID der Bauart
code string Bauartcode CH_NEW_CONSTRUCTION
name string Bauartname Neubau
sortOrder int Sortierreihenfolge der Bauart 1
deprecated boolean Zeigt an, ob der Typ noch gängig ist 0
filterable boolean Zeigt an, ob der Typ gefiltert werden kann 1
projectRoles
Field Type Description Example
active boolean Zeigt an, ob die Firma noch aktiv ist 0
mainContact boolean Zeigt an, ob es sich um den Hauptkontakt handelt 1
projectRoleType
Field Type Description Example
id int Eindeutige Rollen ID 162
code string Rollencode 1010
name string Name der Rollenbezeichnung Bauherr
teaserCompany
Field Type Description Example
id int Eindeutige Firmen ID 198123
name1 string Firmenname Max
name2 string Firmenname, Zeile 2 Mustermann GmbH
postcode string Postleitzahl 6850
town string Ort Mendrisio
company
Field Type Description Example
id int Eindeutige Firmen ID 215266
name1 string Firmenname Gemeinde Teufen
name2 string Firmenname, Zeile 2 Wasserversorgung
parishPostcode int Gemeindecode 15643
street string Strassenname und Hausnummer Krankenhausstrasse 1
town string Stadt Teufen AR
postcode int Postleitzahl 9053
country string Ländercode CHE
externalID int XOIS-Firmen-ID 1312979
salutationType
Field Type Description Example
id int Eindeutige ID der Anrede 33
code string Anredecode 1
name string Name der Anrede Herr
contactSpecifications
Field Type Description Example
content string Telefon, Fax, E-Mail, oder URL, je nach Type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Telefon PHONE
name string Telefon Phone
projectRolePersons
Field Type Description Example
projectRolePersonType
Field Type Description Example
id int Eindeutige ID der Personenrolle 9
code string Eindeutiger Code der Personenrolle CH_ARCHITECT
name string Name der Personenrolle Architekt
sortOrder int Sortierung 130
deprecated boolean Zeigt an, ob der Typ noch gängig ist 0
projectRolePersons
Field Type Description Example
id int Eindeutige ID der Person 1548945
salutationType
Field Type Description Example
id int Eindeutige ID der Anrede 33
code string Anredecode 1
name string Name der Anrede Herr
contactSpecifications
Field Type Description Example
content string Telefon, Fax, E-Mail, oder URL, je nach Type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Telefon PHONE
name string Telefon Phone
Field id
Type int
Description Eindeutige Projekt-ID
Example 312885
Field title
Type string
Description Projekt-Titel
Example Neubau Reservoir mit Leitungsersatz
Field postcode
Type int
Description Postleitzahl
Example 9053
Field country
Type string
Description Land
Example CHE
Field town
Type string
Description Stadt
Example Teufen AR
Field area
Type string
Description Gebietsbezeichnung
Example Les Planches
Field street
Type string
Description Strassenname und Hausnummer
Example Reservoir Häuslersegg
Field projectValue
Type double
Description Bausumme (in ganzen Währungseinheiten)
Example 1340000
Field valueDescription
Type string
Description Bausummen Text
Example 1.34 Mio CHF
Field startDate
Type datetime
Description Baustart
Example 2023-05-21T22:00:00+00:00
Field startDateAccuracy
Type int
Description Wert zur Berechnung des Baustarts
Example 12
Field startDescription
Type string
Description Baustart Text
Example Mai 2023
Field endDate
Type datetime
Description Bauende
Example 2024-06-29T22:00:00+00:00
Field endDescription
Type string
Description Bauende Text
Example Juni 2024
Field firstPublished
Type datetime
Description Erstveröffentlichung
Example 2023-01-20T10:49:16+00:00
Field lastPublished
Type datetime
Description Letzte Veröffentlichung
Example 2023-05-23T09:13:44+00:00
Field lastUpdate
Type datetime
Description Nach Regeln definiertes letztes Update Datum eines Projektes
Example 2023-05-23T09:13:44+00:00
Field topProject
Type int
Description ID des übergeordneten Projektes
Example 1115
Field externalID
Type int
Description Referenz-ID zu Infopro Digital Projekten
Example 3197834
Field projectRolePersons
Field projectRolePersonType
Field id
Type int
Description Eindeutige ID der Personenrolle
Example 9
Field code
Type string
Description Eindeutiger Code der Personenrolle
Example CH_ARCHITECT
Field name
Type string
Description Name der Personenrolle
Example Architekt
Field sortOrder
Type int
Description Sortierung
Example 130
Field deprecated
Type boolean
Description Zeigt an, ob der Typ noch gängig ist
Example 0
Field person
Field id
Type int
Description Eindeutige ID der Person
Example 1548945
Field salutationType
Field id
Type int
Description Eindeutige ID der Anrede
Example 33
Field code
Type string
Description Anredecode
Example 1
Field name
Type string
Description Name der Anrede
Example Herr
Field contactSpecifications
Field content
Type string
Description Telefon, Fax, E-Mail, oder URL, je nach Type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Telefon
Example PHONE
Field name
Type string
Description Telefon
Example Phone
Field projectType
Field id
Type int
Description Eindeutige ID der Hauptkategorie
Example 33
Field code
Type string
Description Eindeutiger Code der Hauptkategorie
Example 11
Field name
Type string
Description Name der Hauptkategorie
Example Technische Anlagen
Field sortOrder
Type int
Description Sortierreihenfolge der Hauptkategorie
Example 50
Field projectResearchType
Field id
Type int
Description Eindeutige ID des Recherchetyps
Example 8
Field code
Type string
Description Recherchetyp-Code
Example 1
Field infoText
Type string
Description Recherchetyp
Example Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
Field sortOrder
Type int
Description Sortierreihenfolge des Recherchetyps
Example 0
Field purpose
Field id
Type int
Description Eindeutige ID des Verwendungszwecks
Example 14
Field code
Type string
Description Verwendungszweckcode
Example CH_OWN_USE
Field name
Type string
Description Name des Verwendungszwecks
Example Eigenbedarf
Field planningStage
Field id
Type int
Description Eindeutige ID des Baustadiums
Example 19
Field code
Type string
Description Eindeutiger Code des Baustadiums
Example CH_PASSED_IN
Field name
Type string
Description Name des Baustadiums
Example Baugesuch eingereicht
Field sortOrder
Type int
Description Sortierreihenfolge des Baustadiums
Example 4
Field projectTexts
Field content
Type string
Description Text
Example Neubau Reservoir mit Leitungsersatz und Forststrasse/Zugangsweg Reservoir
Field projectTextType
Field code
Type string
Description Eindeutiger Code des Texttyps
Example 1
Field name
Type string
Description Name der Textart
Example Beschreibung
Field sortOrder
Type int
Description Sortierreihenfolge der Textart
Example 1
Field projectDetails
Field value
Type string
Description Wert des Details
Example 15
Field negated
Type boolean
Description Zeigt an, ob der Wert negiert wird
Example true
Field projectDetailType
Field id
Type int
Description ID des Gebäudeausbaus
Example 763
Field Code
Type string
Description Code des Gebäudeausbaus
Example CH_STRUCTURES
Field name
Type string
Description Name des Gebäudeausbaus
Example Fenster
Field projectAttributes
Field id
Type int
Description Eindeutige ID des Attributs
Example 7911848
Field value
Type string
Description Wert des Attributs
Example Gst. 1243, 2200, 848
Field projectAttributeType
Field id
Type int
Description Eindeutige ID des Attributs
Example 120
Field code
Type string
Description Eindeutiger Code des Attributs
Example 1
Field name
Type string
Description Name des Attributs
Example Einsprache
Field planningStageDates
Field id
Type int
Description Eindeutige ID des Datensatzes
Example 27447
Field project
Type string
Description URI zum Projekt
Example /projects/312885
Field planningStageDate
Type datetime
Description Datum des Baustadiums
Example 2023-05-23T09:13:44+00:00
Field planningStage
Field id
Type int
Description Eindeutige ID des Baustadiums
Example 19
Field code
Type string
Description Eindeutiger Code des Baustadiums
Example CH_PASSED_IN
Field name
Type string
Description Name des Baustadiums
Example Baugesuch eingereicht
Field sortOrder
Type int
Description Sortierreihenfolge des Baustadiums
Example 4
Field projectCategories
Field projectCategoryType
Field id
Type int
Description Eindeutige ID der Unterkategorie
Example 738
Field parentID
Type int
Description Eltern-Unterkategorie ID
Example 679
Field code
Type string
Description Eindeutiger Code der Unterkategorie
Example 520
Field name
Type string
Description Name der Unterkategorie
Example Wasseraufbereitungsanlagen
Field projectDevelopmentType
Field id
Type int
Description Eindeutige ID der Bauart
Example
Field code
Type string
Description Bauartcode
Example CH_NEW_CONSTRUCTION
Field name
Type string
Description Bauartname
Example Neubau
Field sortOrder
Type int
Description Sortierreihenfolge der Bauart
Example 1
Field deprecated
Type boolean
Description Zeigt an, ob der Typ noch gängig ist
Example 0
Field filterable
Type boolean
Description Zeigt an, ob der Typ gefiltert werden kann
Example 1
Field projectRoles
Field active
Type boolean
Description Zeigt an, ob die Firma noch aktiv ist
Example 0
Field mainContact
Type boolean
Description Zeigt an, ob es sich um den Hauptkontakt handelt
Example 1
Field projectRoleType
Field id
Type int
Description Eindeutige Rollen ID
Example 162
Field code
Type string
Description Rollencode
Example 1010
Field name
Type string
Description Name der Rollenbezeichnung
Example Bauherr
Field teaserCompany
Field id
Type int
Description Eindeutige Firmen ID
Example 198123
Field name1
Type string
Description Firmenname
Example Max
Field name2
Type string
Description Firmenname, Zeile 2
Example Mustermann GmbH
Field postcode
Type string
Description Postleitzahl
Example 6850
Field town
Type string
Description Ort
Example Mendrisio
Field company
Field id
Type int
Description Eindeutige Firmen ID
Example 215266
Field name1
Type string
Description Firmenname
Example Gemeinde Teufen
Field name2
Type string
Description Firmenname, Zeile 2
Example Wasserversorgung
Field parishPostcode
Type int
Description Gemeindecode
Example 15643
Field street
Type string
Description Strassenname und Hausnummer
Example Krankenhausstrasse 1
Field town
Type string
Description Stadt
Example Teufen AR
Field postcode
Type int
Description Postleitzahl
Example 9053
Field country
Type string
Description Ländercode
Example CHE
Field externalID
Type int
Description XOIS-Firmen-ID
Example 1312979
Field salutationType
Field id
Type int
Description Eindeutige ID der Anrede
Example 33
Field code
Type string
Description Anredecode
Example 1
Field name
Type string
Description Name der Anrede
Example Herr
Field contactSpecifications
Field content
Type string
Description Telefon, Fax, E-Mail, oder URL, je nach Type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Telefon
Example PHONE
Field name
Type string
Description Telefon
Example Phone
Field projectRolePersons
Field projectRolePersonType
Field id
Type int
Description Eindeutige ID der Personenrolle
Example 9
Field code
Type string
Description Eindeutiger Code der Personenrolle
Example CH_ARCHITECT
Field name
Type string
Description Name der Personenrolle
Example Architekt
Field sortOrder
Type int
Description Sortierung
Example 130
Field deprecated
Type boolean
Description Zeigt an, ob der Typ noch gängig ist
Example 0
Field person
Field id
Type int
Description Eindeutige ID der Person
Example 1548945
Field salutationType
Field id
Type int
Description Eindeutige ID der Anrede
Example 33
Field code
Type string
Description Anredecode
Example 1
Field name
Type string
Description Name der Anrede
Example Herr
Field contactSpecifications
Field content
Type string
Description Telefon, Fax, E-Mail, oder URL, je nach Type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Telefon
Example PHONE
Field name
Type string
Description Telefon
Example Phone