Beekeeping.io API v1.0 Documentation

The following outlines the calls the Beekeeping.io API v1.0.

Code condition: Beta. This document was last updated on Feb 13, 2016

API Conventions

No matter what part of the API you are calling, there are certain conventions that must be followed.

INPUT FORMAT
All API calls obey standard REST formatting on the URL with a JSON output. Calls to the API look like https://api.beekeeping.io/api_v1/action/parameter where an action might be data_upload, and the parameter is data about that action, such as temperature=62. There may be multiple parameter values in a single API call. If you have a parameter that contains textual, it can be URL ecoded.
OUTPUT FORMAT
All output is in JSON format, and includes the fields status_code and status_string.
REQUIRED INPUT
When calling the API, all URLs are prefixed with /api_v1. Example: https://api.beekeeping.io/api_v1/data_upload
The API requires a license key. This is an alphanumeric string that needs to be sent as part of the GET (REST) HTTP command. License keys have the name license_key and a value of the alphanumeric string.
REQUEST LIMITS
API requests are rate limited to no more than 5 per second from any single IP address. Please contact help@beekeeping.io if you need to exceed this rate, and accomodations can be made.
LINUX CURL EXAMPLE
curl -s api.beekeeping.io/api_v1/data_upload?license_key=1234567890device_id=abcdef&temperature=62&humidity=55
Tips
The JSON output will always have two items in it; status_code and status_string. By knowing these are always in the JSON string, you can parse them and make decisions on how to handle the API's output. True is returned as 1 and False is returned as 0 (zero).

Data Upload

GET  http://api.beekeeping.io/api_v1/data_upload?license_key=1234567890&device_id=AA:BB:CC&vendor_id=my_company&product_id=abc-1&temperature=34&humidity=65

This call is used for uploading data in REST format by putting all data on the URL. To use it, replace the items in red with valid ones from your data.

Supported Fields
license_key (required) Assigned by beekeeping.io staff.
device_id (required) is the unique code assigned to each device type. Valid value is any unique value that beekeeping.io has assigned to your unique device.
vendor_id (optional) is the code assigned to each device vendor. Valid values are broodmonder or other.
model_id (optional) is the code assigned to each device version. Valid values are whatever the vendors assigns, such as 42 or 42v1.
firmware_id (optional) is the code assigned to each device firmware version. Valid values are whatever the vendor assigns.
timestamp (optional) is the timestamp of this reading expressed in Unix EPOC format. Omitting this field will default the field to the current timestamp.
temperature (optional) is the current temperature reading of the device.
temperature_high (optional) is the highest temperature reading for this period expressed in the timestamp.
temperature_average (optional) is the average temperature reading for this period expressed in the timestamp.
temperature_low (optional) is the lowest temperature reading for this period expressed in the timestamp.
humidity (optional) is the current humidity reading of the device.
humidity_high (optional) is the highest humidity reading for this period expressed in the timestamp.
humidity_average (optional) is the average humidity reading for this period expressed in the timestamp.
humidity_low (optional) is the lowest humidity reading for this period expressed in the timestamp.
weight (optional) is the current weight of the device.
signal_wifi (optional) is the numberic WiFi signal strength, expressed as a percentage, of the device at the time of the read. Valid values are 0 trough 100.
signal_bluetooth (optional) is the numberic Blootooth signal strength, expressed as a percentage, of the device at the time of the read. Valid values are 0 trough 100.
battery (optional) is the numeric strength of the battery, expressed as a percentage, at the time of the read. Valid values are 0 trough 100.

Tips
The API sends live data into the system, so when testing, just refresh the web page to see if your new data appears on the graph. Always check for the returning code in JSON format after an upload has completed as it will confirm that your data has been received properly, or give you a disgnostic code indicating what went wrong.

Get Apiary Detail

GET  http://api.beekeeping.io/api_v1/get_apiary_detail?license_key=1234567890&uuid=abcdef

This call is used for uploading data in REST format by putting all data on the URL. To use it, replace the items in red with valid ones from your data.

Supported Fields
license_key (required) Assigned by beekeeping.io staff.
uuid (required) is the unique code assigned to each device type. Valid value is any unique value that beekeeping.io has assigned to your unique apiary.
Data Returned
{
"code":200,
"description":"Apiary queried OK",
"result":{
    "apiary_uuid":"5avs976765utbic5vd876a5vs7d65v",
    "zipcode":"02653",
    "apiary_name":"Beachtree Apiary",
    "latitude":"-69.94039400",
    "longitude":"41.79891900",
    "is_read_public":"1",
    "privilege":"2"
    }
}
Tips
All data returned from the API is in JSON format. Look for a code of 200 to ensure the data you're seeing was returned in a valid format. All times are in in the UTC timezone, and will need to be converted to your local format. Any time field with that has "timestamp" as part of the name will be in Unix standard timestamp format, based from the UNIX Epoc of 1970.

Get Hive Detail

GET  http://api.beekeeping.io/api_v1/get_hive_detail?license_key=1234567890&uuid=abcdef

This call is used for uploading data in REST format by putting all data on the URL. To use it, replace the items in red with valid ones from your data.

Supported Fields
license_key (required) Assigned by beekeeping.io staff.
uuid (required) is the unique code assigned to each device type. Valid value is any unique value that beekeeping.io has assigned to your unique hive.
Data Returned
{
"code":200,
"description":"Hive queried OK",
"result":{
    "uuid":"969asd5965volb96ba09s6db96ab9s",
    "name":"Hive 2 (quilt)",
    "data_last_received":"2016-01-25 03:36:03",
    "apiary_uuid":"i876b8787d5v8a7s5vd87iytbiuts7d65v",
    "zipcode":"02653",
    "apiary_name":"Beachtree Apiary",
    "privilege":"2"
    }
}
Tips
All data returned from the API is in JSON format. Look for a code of 200 to ensure the data you're seeing was returned in a valid format. All times are in in the UTC timezone, and will need to be converted to your local format. Any time field with that has "timestamp" as part of the name will be in Unix standard timestamp format, based from the UNIX Epoc of 1970.

Get Device Detail

GET  http://api.beekeeping.io/api_v1/get_device_detail?license_key=1234567890&uuid=abcdef

This call is used for uploading data in REST format by putting all data on the URL. To use it, replace the items in red with valid ones from your data.

Supported Fields
license_key (required) Assigned by beekeeping.io staff.
uuid (required) is the unique code assigned to each device type. Valid value is any unique value that beekeeping.io has assigned to your unique device.

Data Returned
{
"code":200,
"description":"Device queried OK",
"result":
    {
    "uuid":"i6av58s7d5vb9a785sv8d7v5ab98s76d",
    "created":"2016-01-31 19:20:03",
    "name":"Sensor 1",
    "vendor":"BroodMinder",
    "model":"1.0",
    "api_id":"aa:bb:cc",
    "data_last_received":"2016-02-10 21:20:03",
    "data_last_received_timestamp":"1455157203",
    "hive_uuid":"969asd596964s6db96ba09s6d986ab9s",
    "hive_name":"Hive 2 (quilt)",
    "apiary_uuid":"5avs87d5v8a876s7s5vd876764s7d65v",
    "apiary_name":"Ridge Apiary",
    "zipcode":"02118",
    "country_code":"us",
    "privilege":"2"
    }
}
Tips
All data returned from the API is in JSON format. Look for a code of 200 to ensure the data you're seeing was returned in a valid format. All times are in in the UTC timezone, and will need to be converted to your local format. Any time field with that has "timestamp" as part of the name will be in Unix standard timestamp format, based from the UNIX Epoc of 1970.