Hierarchical Project
This section contains a step by step description on how to create a hierarchical project, integrate it with your sensors and validate their data.
Creating the Project
We can create a new Hierarchical project by making use of the following endpoint, a name, as well as a photo is required.
The status field must be set to "active" for the project to be able to host transaction-making sensors. This field can be changed later.
Creates a new project
POST https://api.airtrace.io/v1/projects
Request Body
name*
String
Name of the new project
photo*
String
Project picture url
status*
String
Status of the current project
In case you forgot the id of your project after creating it, you can get information about all of your projects by querying the endpoint https://api.airtrace.io/v1/projects via a GET request.
Populating your Project with Deployments
Now it is time to start creating Deployments, remember, Deployments are just groups of Spots which will all host sensors with the same commit interval. If you want to have a set of sensors being traced once a week, and another set of sensors being traced once every five minutes, you must create one Deployment for each set of sensors.
The new Deployment will not only group sensors by the same commit interval, but also holds information about the general geographical location of the sensors, thus a Deployment might be a good way of grouping sensors by general location (even if they have the same commit interval).
Creates a new Deployment
POST https://api.airtrace.io/v1/projects/{id_project}/deployments
Path Parameters
id_project*
String
The id of the project in which the new deployment will be created
Request Body
name*
String
Name of the new deployment
type
String
The deployment type (default is "map")
status*
String
Is set to "active" for the deployment to work
data*
[Double, Double, Double]
Map coordinates of the deployment
commit_interval*
Integer
A valid commit interval at which the data will be uploaded to the Blockchain
In case you forgot the id of your deployment after creating it, you can get information about all of the deployments inside this project by querying the endpoint https://api.airtrace.io/v1/projects/{id_project}/deployments via a GET request, replacing {id_project} by the id of the project containing the deployments you want to query.
Finding the id of the sensors you want to add
Before adding sensors to Spots on our Deployment, we need to find their ids. We will look for the sensors in the list of supported sensors that the following endpoint returns:
Get a list of all the sensors available
GET https://api.airtrace.io/v1/sensors
For each sensor that we want to add to our deployment, we will take note of it's id as shown in the response from the endpoint.
Creating Spots in our Deployments
After we have found the ids of all the sensors we want to add to register in our project, we can input them inside the optional field "sensors_spots" when calling the Spot creation Endpoint.
For example, we have 3 copies of the sensors with id 41 in our Deployment "Northern Deployment" and 2 sensors with ids 42 and 43 in our Deployment "Southern Deployment"
Creates a new Spot associated with a specific Deployment
POST /projects/{id}/deployments/{id_deployment}/spots
Path Parameters
id_project*
String
The id of the project that will contain the Spot
id_deployment*
String
The id of the Deployment that will contain the Spot
Request Body
name*
String
The name of the Spot the user wants to create
status*
String
Is set to "active" for the project to work
location*
[Double, Double, Double]
The map coordinates of the Spot
sensors_spots
[Integer...]
List of the ids of the Sensors associated with this Spot, the field is optional as the Sensors can be associated after Spot creation
categories_spots
[Integer...]
List of the ids of the Categories associated with this Spot, the field is optional as the Categories can be associated after Spot creation
The response from this endpoint will contain the id of the newly created Spot inside the field "id". We will need this value in order to make almost any request related to the Spot.
After we have set up all of the sensors inside all of the spots, we are ready to assign Identities to them, a necessary step for them to be able to upload data to Airtrace.
Creating Identities for our sensors
We need to create an identity for each sensor that we want uploading data to Airtrace, as there can be many of the same kind of sensor in the same Spot.
In order to solve this problem, we create an Identity for each of the sensors, providing a primary identifier for each one. This primary identifier needs to be unique, so in our case we will user the MAC address of each sensor as it's identifier.
Lastly we need to provide the id of the sensor for each Identity we create.
Assigning Identities to our sensors
Once we have all the ids of the identities and sensors ready in our recently created Spots, we can assign each identity to each sensor, after assigning the Identities, the sensors will be ready to upload data to Airtrace.
For that we will need the id of our project, the id of each deployment, spot and sensor inside the project, and the id of the identity we are assigning to each sensor.
If we have a project with 2 Deployments, each with 3 Spot and each Spot with 4 Sensors that means we need to call this endpoint a total of 12 times, once for each sensor, and always keeping the fields "id", "id_deployment" and "id_spot" as the values that correspond to the project, deployment and spot containing that specific sensor.
Generating the infrastructure
Only after all of the sensors have been assigned an identity, we can create an infrastructure for each of our Deployments, an infrastructure is the set of links through which the sensors will communicate with Airtrace.
Airtrace supports either the restful interface or the mqtt interface, for this example we are choosing to generate a restful infrastructure for both of our Deployments.
Creates a new infrastructure for a Deployment
POST https://api.airtrace.io/v1/projects/{id}/deployments/{id_deployment}/infrastructure/{interface}
Path Parameters
*
String
The id of the project containing the Deployment
id_deployment*
String
The id of the Deployment for which the user wants to create a new infrastructure
interface*
String
One of the Airtrace supported clients
This endpoint will provide us with the links for each sensor, each link being a string that begins with "/infrastructure/" and is followed by another string of characters.
We can now turn on our sensors and begin uploading each sensor's data to their corresponding link, for that we point the sensors to the URL that begins with http://api.airtrace.io and is directly followed by the link itself, each time a sensor uploads data, it needs to make an authenticated POST request to the previously mentioned URL.
The data uploaded by the sensors will begin to accumulate until the commit interval for each of our Deployments is triggered.
Checking data status
Before the commit interval for each Deployment triggers a Blockchain transaction, it is stored and can be checked via the following endpoint, which will show all of the data sent that has not been traced (included in a transaction) yet:
Returns all data that will be traced in the next commit interval
GET https://api.airtrace.io/v1/infrastructure/transactions/pending
Whenever the commit interval is triggered, it will generate a transaction and the data previously shown by the "pending" endpoint for that Deployment will no longer be shown.
On the other hand, we can check the newly made transaction to check the data that was traced.
Checking the transaction
We can query the following endpoint to find the transaction that was triggered by the last commit interval in our Deployment.
Returns all transactions
GET https://api.airtrace.io/v1/infrastructure/transactions
If there are too many transactions to manually find the one that we are looking for, we can query the following endpoint and get just the transactions that were made today:
Returns all traces between two dates and times
GET https://api.airtrace.io/v1/infrastructure/transactions/{date_start}/{date_end}
Path Parameters
date_start*
dd:mm:yyyy_HH:MM:SS
The start of the date range where transactions will be returned
date_start*
dd:mm:yyyy_HH:MM:SS
The start of the date range where transactions will be returned
Last updated