Quick Start¶
Getting started with using Geometry APIs involves the following steps:
- Create an account and a machine user
- Create a JSON Web Token (JWT) by using the machine user credentials
- Make API requests using the JWT
Note
In the following examples we are:
-
making use of a Linux/MacOS shell in which environmental variables are set using the
export
command. In other environments it may be different, e.g. Windows uses theset
command instead. -
using the
curl
as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java.
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 perform to retrieve the 2D geometry of a floor. As a prerequisite, it is recommended to lookup a floorId
either in the DataSetup application or using the Structure API. In the rest of this document we assume that the floorId is: 20cfac0b-d3ae-415e-af95-861d46e5fdda
Find Floorplan¶
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/geometry/partitions/$PARTITION/floorplans?filter[representsFloor.data.id]=20cfac0b-d3ae-415e-af95-861d46e5fdda"
The response contains all floorplans for the specified floor (floorId). 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 floorplans 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 FLOORPLAN_ID=8db4216d-61c5-4e79-8558-164aa179bfe9
Get Geometry¶
The next step is to list the devices available in your building. This is achieved by using the List Devices
operation. In this example also the optional include
parameter is specified, it's useful to retrieve the name and connectivity status of the devices.
curl -H "Authorization: Bearer $TOKEN" \
"https://api.bpcloud.siemens.com/geometry/partitions/$PARTITION/floorplans/$FLOORPLAN_ID/geometry"
The response contains a GeoJSON-document that can be processed by your application or rendered by multiple commercial and open source components or online tools.
Community
Connect and Collaborate with Industrial Professionals and Join the Community!