Quick Start¶

Getting started with using Building Structure APIs involves the following steps:

1. Create an account and a machine user.
2. Create a JSON Web Token (JWT) by using the machine user credentials.
3. Make API requests using the JWT.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization- section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://siemens-bt-015.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token-property in the response. You can now use it by passing it in the Authorization-header of any subsequent API requests. The expires_in-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to:

1. Consume an existing Building, including all parts, possibly created using the Data Setup App
2. Creating a Building hierarchy

List Buildings¶

The first step to perform is to list the buildings in your partition. This you can do by performing the List Locations operation. Below we specify the include -parameter to include the address of each building in the included section of the response.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/structure/partitions/$PARTITION/locations?filter[type]=Building&include=hasPostalAddress"

The response contains all buildings in your partition. If you have a large number of buildings you may need to retrieve multiple pages, see Pagination.

Select the id property of one of the locations in the response and set it in an environmental variable. E.g. if the id is 8db4216d-61c5-4e79-8558-164aa179bfe9 then set it using the following command:

export LOCATION=8db4216d-61c5-4e79-8558-164aa179bfe9

List Parts of a Building¶

The next step is to list the parts of the building. This is achieved by using the List Location Parts operation.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/structure/partitions/$PARTITION/locations/$LOCATION/relationships/has-parts"

The response contains a list of direct and transitive parts of the specified location with their location defined as the building you specified. I.e. if your building has Floors and those Floors have Rooms the response will contain all those Floors and Rooms.

If you wish to perform some logic on the Building hierarchy or visualize a tree you need to assemble the tree yourself. It is straightforward and done by using the hierarchical relationships e.g. isFloorOf and isRoomOf.

Creating a Location Hierarchy¶

All locations have a parent, or in other words, they have an isPartOf-relationship to a higher level Location, except Campus and Building. Buildings are optionally related to Campuses or CampusParts. This means to create a hierarchy we must start with the top-level Location.

To create a Building we also must provide a reference to and Address-resource. Optionally in can be provided using the include-feature of the API, we will use this in our example.

Create a file named newbuilding.json. Paste in the following content below but please change the id of the Address to something unique, e.g. by creating a new UUID using uuidgenerator.net. Note that 'data/relationships/data/id' must match the 'included[0]/id'

{
  "data": {
    "type": "Building",
    "attributes": {
      "label": "My Place",
      "timeZone": "Europe/Zurich"
    },
    "relationships": {
      "hasPostalAddress": {
        "data": {
          "id": "05085306-9c1d-4cee-b92a-04c07e4b1945",
          "type": "Address"
        }
      }
    }
  },
  "included": [
    {
      "id": "05085306-9c1d-4cee-b92a-04c07e4b1945",
      "type": "Address",
      "attributes": {
        "locality": "Springfield",
        "countryCode": "USA",
        "region": "Indiana",
        "postalCode": "10101",
        "street": "33 Park Way"
      }
    }
  ]
}

You are now ready to create the Building by performing the Create Location operation:

curl -H "Authorization: Bearer $TOKEN" \
-X POST -d @newbuilding.json -H "Content-Type: application/vnd.api+json" \
    "https://api.bpcloud.siemens.com/structure/partitions/$PARTITION/locations"

In the response, you will find the generated id for your Building. Now you can continue by creating floors and using the Building-ID. If the BuildingID was 79d8fd89-6c82-40b6-aa5a-9a570d3ae88a the request body to create a floor would look like this:

{
  "data": {
    "type": "Floor",
    "attributes": {
      "label": "My Floor",
      "floorNumber": 1
    },
    "relationships": {
      "isFloorOf": {
        "data": {
          "id": "79d8fd89-6c82-40b6-aa5a-9a570d3ae88a",
          "type": "Building"
        }
      }
    }
  }
}

Add points to point-groups¶

To add points to point-groups, the Post /point-groups/{point-groupId}/points operation can be used.

curl -X 'POST' \
  "https://api.bpcloud.siemens.com/structure/partitions/$PARTITION/point-groups/$POINTGROUPID/points" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
  \"data\": {
    \"type\": \"Point\",
    \"attributes\": {
      \"name\": \"hvac 2134444\",
      \"description\": \"HVAC controller\",
      \"dataType\": \"number\",
      \"maximum\": 100,
      \"minimum\": 100,
      \"precision\": 0.1,
      \"commandingSemantic\": \"writeable\",
      \"function\": \"sensor\"
    }
  }
}"

In the response, it will add points to the point-groups.