Webservice Documentation

Preparation

To be able to use the web service, you first need to set up a search profile. When saving the search profile, make sure that it is created with the "Web Service" option:

image

The ID of the search profile can be obtained from its URL, as shown in below example:

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

Important:
  • After setting up the search profile, values can be retrieved if the web service option is selected. The retrieval process will start the next day.
  • New results can only be retrieved from selected days.

Environments

Product

Baublatt Xplorer

Webservice-URL

https://api.xplorer.ch

Login

To connect to the web service, you must first log in. This can be achieved under the endpoint POST /login_check. Refer to below example:

Example login query:
Example Login Result:

A successful access provides a JWT token and a refresh token. The former is required for any further contact with the interface. The latter is required to obtain a new token after the expiration of the current token.

Important:

A security cookie is required for concurrent access, as shown in below example.

Example:

The JWT is valid for one hour by default. If a longer session is needed, then the token can be renewed using the refresh token under POST /token/refresh as follows:

Example Refresh Query:

This query result is identical to the login query. Also, the refresh token is valid for 8 hours and is renewed with each call.

Fetching the data

There are two possible endpoints corresponding to the products available in Xplorer:

Endpoint name

all_pn_headers

projects

Objects

Calls for Tenders / Tenders

Projects

Note: The objects available to you depend on your Baublatt framework agreement.

The data retrieval process takes place via one of the above-mentioned endpoints using the GET method, for example /web_service/all_pn_headers/. Bearing this in mind, the previously obtained JWT token and the ID of the previously created search profile are required. The token is passed using the Authorization header, and the search profile ID is provided using a GET parameter as follows:

Example Data Retrieval:

If available, this query now provides the new information of your search profile. The record format can be selected by using the “Accept header” as shown below:

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

Confirmation of Pickup

The web service provides records of your search profile and remembers previous record retrieves. By default, 10 or 20 records (Projects or Tenders) per call are provided from the above-mentioned endpoints. Two ways are available to retrieve the next 20 records as explained below:

Confirmation via Header

If you do not want to call another endpoint, data retrieval can be confirmed by using the X-AUTO-ACK header as shown below:

Example Pickup with Auto-Ack:
Confirmation via endpoint

The next 20 records can be retrieved by using the endpoint POST /web_service/acknowledge/. Search profile ID and the IDs of confirmed records are required in the JSON object as shown below. This method minimizes the risk of losing records in the retrieval process.

Example endpoint:

Data Structure for Projects

When you retrieve the endpoint /web_service/projects/, you will receive the Projects in the data structure described below.

Whenever you see a data field labeled "Code" in the data structure, you can download a corresponding list of all available codes along with their associated names as a CSV file using the download icon

Here is the complete data structure:

Field Type Description Example
id int Unique Project ID 312885
title string Project title Neubau Reservoir mit Leitungsersatz
postcode int Postal code 9053
country string Country CHE
town string City Teufen AR
area string Area designation Les Planches
street string Street name and house number Reservoir Häuslersegg
projectValue double Project value (in full currency units) 1340000
valueDescription string Project value text 1.34 Mio CHF
startDate datetime Start date 2023-05-21T22:00:00+00:00
startDateAccuracy int Value for calculating start date 12
startDescription string Value for calculating start date Mai 2023
endDate datetime End date 2024-06-29T22:00:00+00:00
endDescription string End date text Juni 2024
firstPublished datetime First published 2023-01-20T10:49:16+00:00
lastPublished datetime Last published 2023-05-23T09:13:44+00:00
lastUpdate datetime Last update date defined by Project rules 2023-05-23T09:13:44+00:00
topProject int ID of the parent Project 1115
externalID int Reference ID for Infopro Digital Projects 3197834
projectRolePersons
Field Type Description Example
projectRolePersonType
Field Type Description Example
id int Unique ID of the person role 9
code string Unique code of the person role CH_ARCHITECT
name string Name of the person role Architekt
sortOrder int Sorting 130
deprecated boolean Indicates whether the type is still valid 0
person
Field Type Description Example
id int Unique ID of the person 1548945
salutationType
Field Type Description Example
id int Unique ID of the salutation 33
code string Salutation code 1
name string Name of the salutation Herr
contactSpecifications
Field Type Description Example
content string Phone, fax, email, or URL, depending on the type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Phone PHONE
name string Phone Phone
projectType
Field Type Description Example
id int Unique ID of the main category 33
code string Unique code of the main category 11
name string Name of the main category Technische Anlagen
sortOrder int Sorting of the main category 50
projectResearchType
Field Type Description Example
id int Unique ID of the research type 8
code string Research type code 1
infoText string Research type Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
sortOrder int Sorting of the research type 0
purpose
Field Type Description Example
id int Unique ID of the purpose of use 14
code string Purpose of use code CH_OWN_USE
name string Name of the purpose of use Eigenbedarf
planningStage
Field Type Description Example
id int Unique ID of the construction stage 19
code string Unique code of the construction stage CH_PASSED_IN
name string Name of the construction stage Baugesuch eingereicht
sortOrder int Sorting of the construction stage 4
projectTexts
Field Type Description Example
content string Text Neubau Reservoir mit Leitungsersatz und Forststrasse/Zugangsweg Reservoir
projectTextType
Field Type Description Example
code string Unique code of the text type 1
name string Name of the text type Beschreibung
sortOrder int Sorting of the text type 1
projectDetails
Field Type Description Example
value string Value of the detail 15
negated boolean Indicates whether the value is negated true
projectDetailType
Field Type Description Example
id int ID of the building expansion 763
code string Code of the building expansion CH_STRUCTURES
name string Name of the building expansion Fenster
projectAttributes
Field Type Description Example
id int Unique ID of the attribute 7911848
value string Value of the attribute Gst. 1243, 2200, 848
projectAttributeType
Field Type Description Example
id int Unique ID of the attribute 120
code string Unique code of the attribute 1
name string Name of the attribute Einsprache
planningStageDates
Field Type Description Example
id int Unique ID of the record 27447
project string URI to the Project /projects/312885
planningStageDate datetime Date of the construction stage 2023-05-23T09:13:44+00:00
planningStage
Field Type Description Example
id int Unique ID of the construction stage 19
code string Unique code of the construction stage CH_PASSED_IN
name string Name of the construction stage Baugesuch eingereicht
sortOrder int Sorting of the construction stage 4
projectCategories
Field Type Description Example
projectCategoryType
Field Type Description Example
id int Unique ID of the subcategory 738
parentId int Parent-subcategory ID 679
code string Unique code of the subcategory 520
name string Name of the subcategory Wasseraufbereitungsanlagen
projectDevelopmentType
Field Type Description Example
id int Unique ID of the construction type
code string Construction type code CH_NEW_CONSTRUCTION
name string Construction type name Neubau
sortOrder int Sorting of the construction type 1
deprecated boolean Indicates whether the type is still in use 0
filterable boolean Indicates whether the type can be filtered 1
projectRoles
Field Type Description Example
active boolean Indicates whether the company is still active 0
mainContact boolean Indicates whether this is the primary contact 1
projectRoleType
Field Type Description Example
id int Unique role ID 162
code string Role code 1010
name string Name of the role designation Bauherr
teaserCompany
Field Type Description Example
id int Unique company ID 198123
name1 string Company name Max
name2 string Company name, Line 2 Mustermann GmbH
postcode string Postal code 6850
town string Location Mendrisio
company
Field Type Description Example
id int Unique company ID 215266
name1 string Company name Gemeinde Teufen
name2 string Company name, Line 2 Wasserversorgung
parishPostcode int Municipality code 15643
street string Street name and house number Krankenhausstrasse 1
town string City Teufen AR
postcode int Postal code 9053
country string Country code CHE
externalID int XOIS company ID 1312979
salutationType
Field Type Description Example
id int Unique ID of the salutation 33
code string Salutation code 1
name string Name of the salutation Herr
contactSpecifications
Field Type Description Example
content string Phone, fax, email, or URL, depending on the type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Phone PHONE
name string Phone Phone
projectRolePersons
Field Type Description Example
projectRolePersonType
Field Type Description Example
id int Unique ID of the person role 9
code string Unique code of the person role CH_ARCHITECT
name string Name of the person role Architekt
sortOrder int Sorting 130
deprecated boolean Indicates whether the type is still valid 0
projectRolePersons
Field Type Description Example
id int Unique ID of the person 1548945
salutationType
Field Type Description Example
id int Unique ID of the salutation 33
code string Salutation code 1
name string Name of the salutation Herr
contactSpecifications
Field Type Description Example
content string Phone, fax, email, or URL, depending on the type 071 335 00 15
contactSpecificationType
Field Type Description Example
code string Phone PHONE
name string Phone Phone
Field id
Type int
Description Unique Project ID
Example 312885
Field title
Type string
Description Project title
Example Neubau Reservoir mit Leitungsersatz
Field postcode
Type int
Description Postal code
Example 9053
Field country
Type string
Description Country
Example CHE
Field town
Type string
Description City
Example Teufen AR
Field area
Type string
Description Area designation
Example Les Planches
Field street
Type string
Description Street name and house number
Example Reservoir Häuslersegg
Field projectValue
Type double
Description Project value (in full currency units)
Example 1340000
Field valueDescription
Type string
Description Project value text
Example 1.34 Mio CHF
Field startDate
Type datetime
Description Start date
Example 2023-05-21T22:00:00+00:00
Field startDateAccuracy
Type int
Description Value for calculating start date
Example 12
Field startDescription
Type string
Description Value for calculating start date
Example Mai 2023
Field endDate
Type datetime
Description End date
Example 2024-06-29T22:00:00+00:00
Field endDescription
Type string
Description End date text
Example Juni 2024
Field firstPublished
Type datetime
Description First published
Example 2023-01-20T10:49:16+00:00
Field lastPublished
Type datetime
Description Last published
Example 2023-05-23T09:13:44+00:00
Field lastUpdate
Type datetime
Description Last update date defined by Project rules
Example 2023-05-23T09:13:44+00:00
Field topProject
Type int
Description ID of the parent Project
Example 1115
Field externalID
Type int
Description Reference ID for Infopro Digital Projects
Example 3197834
Field projectRolePersons
Field projectRolePersonType
Field id
Type int
Description Unique ID of the person role
Example 9
Field code
Type string
Description Unique code of the person role
Example CH_ARCHITECT
Field name
Type string
Description Name of the person role
Example Architekt
Field sortOrder
Type int
Description Sorting
Example 130
Field deprecated
Type boolean
Description Indicates whether the type is still valid
Example 0
Field person
Field id
Type int
Description Unique ID of the person
Example 1548945
Field salutationType
Field id
Type int
Description Unique ID of the salutation
Example 33
Field code
Type string
Description Salutation code
Example 1
Field name
Type string
Description Name of the salutation
Example Herr
Field contactSpecifications
Field content
Type string
Description Phone, fax, email, or URL, depending on the type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Phone
Example PHONE
Field name
Type string
Description Phone
Example Phone
Field projectType
Field id
Type int
Description Unique ID of the main category
Example 33
Field code
Type string
Description Unique code of the main category
Example 11
Field name
Type string
Description Name of the main category
Example Technische Anlagen
Field sortOrder
Type int
Description Sorting of the main category
Example 50
Field projectResearchType
Field id
Type int
Description Unique ID of the research type
Example 8
Field code
Type string
Description Research type code
Example 1
Field infoText
Type string
Description Research type
Example Achtung: Dieses Projekt wird aufgrund des schnellen Baufortschritts nicht aktualisiert.
Field sortOrder
Type int
Description Sorting of the research type
Example 0
Field purpose
Field id
Type int
Description Unique ID of the purpose of use
Example 14
Field code
Type string
Description Purpose of use code
Example CH_OWN_USE
Field name
Type string
Description Name of the purpose of use
Example Eigenbedarf
Field planningStage
Field id
Type int
Description Unique ID of the construction stage
Example 19
Field code
Type string
Description Unique code of the construction stage
Example CH_PASSED_IN
Field name
Type string
Description Name of the construction stage
Example Baugesuch eingereicht
Field sortOrder
Type int
Description Sorting of the construction stage
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 Unique code of the text type
Example 1
Field name
Type string
Description Name of the text type
Example Beschreibung
Field sortOrder
Type int
Description Sorting of the text type
Example 1
Field projectDetails
Field value
Type string
Description Value of the detail
Example 15
Field negated
Type boolean
Description Indicates whether the value is negated
Example true
Field projectDetailType
Field id
Type int
Description ID of the building expansion
Example 763
Field Code
Type string
Description Code of the building expansion
Example CH_STRUCTURES
Field name
Type string
Description Name of the building expansion
Example Fenster
Field projectAttributes
Field id
Type int
Description Unique ID of the attribute
Example 7911848
Field value
Type string
Description Value of the attribute
Example Gst. 1243, 2200, 848
Field projectAttributeType
Field id
Type int
Description Unique ID of the attribute
Example 120
Field code
Type string
Description Unique code of the attribute
Example 1
Field name
Type string
Description Name of the attribute
Example Einsprache
Field planningStageDates
Field id
Type int
Description Unique ID of the record
Example 27447
Field project
Type string
Description URI to the Project
Example /projects/312885
Field planningStageDate
Type datetime
Description Date of the construction stage
Example 2023-05-23T09:13:44+00:00
Field planningStage
Field id
Type int
Description Unique ID of the construction stage
Example 19
Field code
Type string
Description Unique code of the construction stage
Example CH_PASSED_IN
Field name
Type string
Description Name of the construction stage
Example Baugesuch eingereicht
Field sortOrder
Type int
Description Sorting of the construction stage
Example 4
Field projectCategories
Field projectCategoryType
Field id
Type int
Description Unique ID of the subcategory
Example 738
Field parentID
Type int
Description Parent-subcategory ID
Example 679
Field code
Type string
Description Unique code of the subcategory
Example 520
Field name
Type string
Description Name of the subcategory
Example Wasseraufbereitungsanlagen
Field projectDevelopmentType
Field id
Type int
Description Unique ID of the construction type
Example
Field code
Type string
Description Construction type code
Example CH_NEW_CONSTRUCTION
Field name
Type string
Description Construction type name
Example Neubau
Field sortOrder
Type int
Description Sorting of the construction type
Example 1
Field deprecated
Type boolean
Description Indicates whether the type is still in use
Example 0
Field filterable
Type boolean
Description Indicates whether the type can be filtered
Example 1
Field projectRoles
Field active
Type boolean
Description Indicates whether the company is still active
Example 0
Field mainContact
Type boolean
Description Indicates whether this is the primary contact
Example 1
Field projectRoleType
Field id
Type int
Description Unique role ID
Example 162
Field code
Type string
Description Role code
Example 1010
Field name
Type string
Description Name of the role designation
Example Bauherr
Field teaserCompany
Field id
Type int
Description Unique company ID
Example 198123
Field name1
Type string
Description Company name
Example Max
Field name2
Type string
Description Company name, Line 2
Example Mustermann GmbH
Field postcode
Type string
Description Postal code
Example 6850
Field town
Type string
Description Location
Example Mendrisio
Field company
Field id
Type int
Description Unique company ID
Example 215266
Field name1
Type string
Description Company name
Example Gemeinde Teufen
Field name2
Type string
Description Company name, Line 2
Example Wasserversorgung
Field parishPostcode
Type int
Description Municipality code
Example 15643
Field street
Type string
Description Street name and house number
Example Krankenhausstrasse 1
Field town
Type string
Description City
Example Teufen AR
Field postcode
Type int
Description Postal code
Example 9053
Field country
Type string
Description Country code
Example CHE
Field externalID
Type int
Description XOIS company ID
Example 1312979
Field salutationType
Field id
Type int
Description Unique ID of the salutation
Example 33
Field code
Type string
Description Salutation code
Example 1
Field name
Type string
Description Name of the salutation
Example Herr
Field contactSpecifications
Field content
Type string
Description Phone, fax, email, or URL, depending on the type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Phone
Example PHONE
Field name
Type string
Description Phone
Example Phone
Field projectRolePersons
Field projectRolePersonType
Field id
Type int
Description Unique ID of the person role
Example 9
Field code
Type string
Description Unique code of the person role
Example CH_ARCHITECT
Field name
Type string
Description Name of the person role
Example Architekt
Field sortOrder
Type int
Description Sorting
Example 130
Field deprecated
Type boolean
Description Indicates whether the type is still valid
Example 0
Field person
Field id
Type int
Description Unique ID of the person
Example 1548945
Field salutationType
Field id
Type int
Description Unique ID of the salutation
Example 33
Field code
Type string
Description Salutation code
Example 1
Field name
Type string
Description Name of the salutation
Example Herr
Field contactSpecifications
Field content
Type string
Description Phone, fax, email, or URL, depending on the type
Example 071 335 00 15
Field contactSpecificationType
Field code
Type string
Description Phone
Example PHONE
Field name
Type string
Description Phone
Example Phone