Querying data¶

Use the GET method to query information from Lifecycle Twin.

A GET request without an {id} parameter returns all resources of the requested type. In the example below, the request returns all sites from the specified portfolio.

The clientname and authorization HTTP headers are mandatory for all API requests. Refer to the Quick Start guide to generate an authorization token.

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

In addition to the headers above, the projectid HTTP header is mandatory when interacting with site-specific resources.

GET /documents

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token>
projectid: <ProjectId>
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Examples¶

Query all sites¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

A GET request with an {id} parameter returns the specific resource matching that ID.

Get information of a specific site by id¶

GET /clientprojects/2f4978fe-ab1c-4d66-be94-2086d0887a86

Request¶

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Response¶

[
    {
        "Name": "Building1",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zug",
            "ChildrenCount": 0,
            "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    }
]

When querying data, you can control field selection, filtering, sorting, and pagination through HTTP headers.

Selecting¶

Use the select HTTP header to specify which fields to include in the response. This improves performance by reducing the amount of data transferred.

Some fields are always returned regardless of whether you include them in the select header.

As a best practice, exclude fields you do not need, especially referenced fields and collections. These generate JOIN queries on the backend and can significantly affect performance.

The select header also supports nested properties.

The syntax of the select header is similar to JSON.

{"Field1", "Field2", "Field3": {"Field1OfField3", "Field2OfField3"}}

Include the select header in all GET queries.

You can find the list of available fields for each entity in the API Reference.

If you specify an incorrect field name, the API returns an error.

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Response¶

[
    {
        "Name": "Building1",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zug",
            "ChildrenCount": 0,
            "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    },
    {
        "Name": "Building2",
        "IsEnabled": false,
        "CreatedOn": "2022-10-18T14:32:17.023Z",
        "Location": {
            "Name": "Zurich",
            "ChildrenCount": 0,
            "Id": "4dc758d7-xy1c-4f4b-bd42-fd95c3cd8236"
        },
        "Id": "2f4978fe-xy1c-4d66-be94-2086d0887a86",
        "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00"
    }
]

Filtering¶

Use the filter HTTP header to restrict query results and find specific resources.

You can use filters not only to search for objects, but also to retrieve related entities. For example, to get the list of components that belong to a room, use the /assets endpoint with a filter by room (location).

The following filter clauses are supported:

Choosing the right clause can significantly affect performance. For example, using equals instead of contains can improve performance by up to 10 times. Select the most specific clause for your use case.

Simple filter by one property¶

{"clause":{"member":"value"}}

{"equals":{"Name":"ISB-020-000--000_1000319"}}

Simple filter by one property of the referenced field¶

{"clause":{"Property.Field":"value"}}

{"Equals":{"Systems.Id":"b7da56c7-f498-40f7-9104-80ba51cd62ba"}}

Filter by field of the collection property¶

{"clause":{"CollectionProperty[].Field":"value"}}

{"equals":{"ModelObjects[].ObjectId":"41958798-cb80-4c0b-bfaf-63e53192c615-0007b076"}}

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Sorting¶

Use the sort HTTP header to order the data in the response.

Syntax¶

{"Property": "OrderType"}

OrderType must be descending or ascending

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
sort: {"Name": "descending"}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}

Pagination¶

Use the pagination HTTP header to specify the page number and page size.

Syntax¶

{"page" : pageNumber, "size" : pageSize}

Example of the request¶

GET /clientprojects

GET /api/clientprojects HTTP/1.1
clientname: <Client Name>
authorization: <Token> 
filter: {"Contains" : {"Name" : "Building1"}}
sort: {"Name": "ascending"}
select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}}
Pagination: {"page" : 0, "size" : 20}

This request returns the first 20 records.