¶ Introduction
This is the Picoballoon Rest API documentation. The documentation is for mainly for developers but also for others. You can use routes to access to data. Either you get the data as json or as file(csv).
¶ Assignments for the API
The main assignment for the API is to providing data. But the API also collects the data from The Things Network. This network is the connection between the probe and the backend.
¶ Contact
If you have questions or something you want to point out, write an email to kalle.bracht@picoballoon.org (master API developer).
If you found a bug or you have a feature suggestion, please write to this email too.
¶ Main data entries
In the API there are the following three basic routes for different data.
| Measure Data | General Probe Data | General Data |
|---|---|---|
| This is the entry where the measures from probes are stored. Route in URL: measure_data |
This is the entry where all information of one probe are stored, for example, start time, weight, version and alot more. Route in URL: general_probe_data |
This is the entry, where all information of the general project are stored, for example member count, current software versions and a lot more. Route in URL: general_data |
Here an example route for the Measure Data entry(returns all measure data):
https://api.picoballoon.org/measure_data/all
¶ How to get data from the API
¶ Getting data from measure data
To get measure data, you can either get all data or only for one probe(by ID).
The format of the return looks like this:
{
"payload": [
{
"coordinates_lat": 0.6,
"coordinates_lon": 9.6,
"drsf": 234,
"frequency": 23,
"gateways": [
{
"altitude": 0,
"gateway_id": "1111",
"latitude": 50.0372,
"longitude": 20.0011
},
{
"altitude": 0,
"gateway_id": "04",
"latitude": -28.6474,
"longitude": 150.166
}
],
"measure_id": 1,
"measure_timestamp": "Sat, 13 Feb 2021 19:05:33 GMT",
"mission_id": 1,
"sensor_data": {}
}
],
"status": {
"errorcode": 0,
"message": "All measure data of all probes."
}
}
In the payload key you have an array, which contains measuring points. A measuring point contains the following keys:
- coordinates_lat: This is one(latitude) of the two coordinate points.
- coordinates_lon: This is the second(longitude) of the two coordinate points.
- drsf: The datarate of LoraWAN.
- frequency: The frequency of LoraWAN.
- gateways: The gateway information of The Things Network, is an array of the different gateways.
- altitude: The altitude of the gateway.
- gateway_id: The gateway ID of the gateway.
- latitude: The latitude of the gateway.
- longitude: The longitude of the gateway.
- measure_id: The ID of the measure point, note that every probe has own measure IDs.
- measure_timestamp: The timestamp when the measure point was measured.
- mission_id: The mission ID identifies which probe made the measure point.
- sensor_data: The sensor data is the actuall measuring, note that the sensor data could change from probe to probe.
To get all measure data you have to use:
https://api.picoballoon.org/measure_data/all
To get the measure data for only one probe use:
https://api.picoballoon.org/measure_data/by_probe_id?id=1
The ID argument is the mission/probe ID.
If you don't want the data in json format, you can also use the download engine. See here
¶ Getting data from general probe data
To get general probe data, you can either get all data or only for one probe(by ID).
The format of the return looks like this:
{
"payload": [
{
"balloon_mass": -2.1,
"balloon_version": "2.2",
"firmware_version": "0.1.7",
"launch_time": "Mon, 26 Apr 2021 21:18:50 GMT",
"mission_id": 1,
"mission_name": "Ferdinand1.0",
"mission_status": "active",
"probe_mass": 2.1,
"probe_version": "1.0"
},
{
"balloon_mass": -2.33,
"balloon_version": "3.3",
"firmware_version": "1.1",
"launch_time": "Sat, 26 Jun 2021 21:20:17 GMT",
"mission_id": 2,
"mission_name": "Ferdinand2.0",
"mission_status": "prelaunch",
"probe_mass": 1,
"probe_version": "2.0"
}
],
"status": {
"errorcode": 0,
"message": "All infos about the start and pre launch."
}
}
In the payload key you have an array, which contains the probe informations. A probe info contains the following keys:
- balloon_mass: The mass of the balloon, is negativ, so this point says how many the balloon can lift. The unit is gramm
g. - balloon_version: The version of the balloon defined by the hardware team.
- firmware_version: The version of the firmware defined by the embedded software team.
- launch_time: The time of the launch, could also be in future is the probe isn't launched yet.
- mission_id: The mission/probe ID which identifies the mission.
- mission_name: Every mission has a name, normally it also contains version information.
- mission_status: The status of the mission. See this
- probe_mass: The mass of the probe. The unit is gramm
g. - probe_version: The version of the probe. Defined by the hardware team.
To get all probe data you have to use:
https://api.picoballoon.org/general_probe_data/all
To get the probe data for only one probe use:
https://api.picoballoon.org/general_probe_data/by_probe_id?id=1
The ID argument is the mission/probe ID.
If you don't want the data in json format, you can also use the download engine. See here
¶ Getting data from general data
You can use general data, to get general data of the project. You can use the following routes:
¶ Software versions
This returns the software version of the parts of the project.
The route is:
https://api.picoballoon.org/general_data/software_versions
It returns in the following format:
{
"payload": {
"api_version": "1.1.1",
"dashboard_version": "1.1.1"
},
"status": {
"errorcode": 0,
"message": "All information about the current software Versions"
}
}
¶ Team members
This returns the data of the team members. You can also see the team members here.
The route is:
https://api.picoballoon.org/general_data/team_members
It returns in the following format:
{
"payload": {
"total_team_members": "15"
},
"status": {
"errorcode": 0,
"message": "All information about the current software Versions"
}
}
¶ Bitmap generator
The bitmap generator genarates bitmaps of the position of The Things Network gateways. This is important for the embedded team, which upload the bmp to the probe, so the probe knows when to connect to a gateway and when to save the data in the backlog system.
The route is:
https://api.picoballoon.org/general_data/bitmap_generator
There is also an argument gateway_range the default value is 300. It set the size of the gateway points.
It returns an image(bmp file) like this:
All general data is in string format also the integers and other types.
¶ Download engine
You can get the data with json, described above.
But if you want to download the data in a csv format, you have to add the parameter ?download=csv. So the route to get all measure data in csv format is:
https://api.picoballoon.org/measure_data/all?download=csv
¶ Error codes
| Code | Description |
|---|---|
| 0 | No error |
| 1 | Don't now which error, it is the last instance. |
| 2 | The URL is not correct. |
| 3 | Not all required parameters are given. |
| 4 | No data was found. |
| 5 | Read the HTTP status. |
| 6 | Access is denied. |
| 7 | The parameter is given but not the correct format. |
¶ Balloon statuses
| Name | Description |
|---|---|
| Active | Means that the probe is currently active and in the air. |
| Failed | Means that the probe failed and not data was received. |
| Prelaunch | Means that the probe has not been launched yet. |
| Ended | Means that the mission was ended and not found. |
| Found | Means that the mission was ended and found. |
| Unknown | Means that the status is unknown. |