Here’s a list of the names and their meanings, as I understand it. Please let me know if these are correct.
device_id - printed on the sensor, doesn’t seem to be used in the api. It looks like a MAC id.
sensor_id and sensor_index - a unique name for each monitor. From the api - " The sensor_id should be exactly as printed on the label on the sensor." The sensor_index is a 4 to 6 digit number. Here’s a definition in the api - “The sensor_index as found in the JSON for this specific sensor.” Hmmm. It also comes embedded in the download link received with registration, along with a key.
group_id - the unique number for a group of sensors. There is also a group name.
member_id - a unique number for each sensor in a group. There is a sensor index associated with that member id.
Yes, that is all correct. I’ll attempt here to provide some context into these different identifiers.
device_id/sensor_id: this is indeed the MAC address of the device, however, any leading zeros in the number and letter pairs are omitted. This is used for sensor identification when troubleshooting, as well as order organization. A sensor’s device ID will never change.
sensor_index: this is the number that our system, including the API, uses to identify sensors. A device can have more than one sensor_index over the course of its lifespan, as a new index value is assigned to a sensor after archival.
group_id: the number used to identify a certain group. Groups are used to query multiple sensors in the same request.
member_id: used to specify and identify sensors in a group.
Thanks for getting back to me. Some more questions
sensor_id/sensor_index - Is a sensor_id tied to the hardware (ie like a MAC id) and the sensor_index is tied to a data set associated with a sensor for a period of time in operation? So can a sensor_id have more than one sensor indexes?
device_id versus sensor_id - Why have two numbers if they basically are the same? If I know a sensor_id, can I get the device_id using the api?
Yes, the sensor_id and device_id are the same thing, which are based off of a device’s MAC address. A device will only have one sensor_id. The sensor-index is an identifier that marks a specific dataset associated with the sensor’s operation for a period of time. Sensor-indexes change after a device’s archival. A device can be associated with any number of sensor_indexes, however, only one will be active at a time. When a devices is archived, and gets a new index value, our system essentially treats it as a totally new device.
It’s not that device_id and sensor_id are two numbers, because they are the same value. It’s just a matter of terminology changing and differing between people. If a sensor’s device_id is 1a:1a:1a:1a:1a:1a, then its sensor_id is also 1a:1a:1a:1a:1a:1a. Having two terms mean the same thing is overly complicated, and confusing. We will hopefully be shifting into using only one of these terms in the future.
I have been collecting what I now understand as sensor indexes. But I want to get the sensor ids. There doesn’t seem to be any way in the api to request those. Get Group Details returns a group_id, a sensor_index and a creation date. Is there anyway to get it to include the sensor_id?
There’s currently no way to obtain the device ID/sensor_id for a sensor from the API. It can be obtained by using the label printed on the device or using the registration confirmation email. It’s used in conjunction with emails to register the sensor to the PurpleAir Map or add a privately registered sensor to a group in the PurpleAir API.
We currently have no plans to add this to the API due to the semi-sensitive nature of the ID, what it’s used for, and the fact that it never changes.
Sorry to hear this. We have monitors that we purchased before you had even thought about an api. And that refer to the device ID as a MAC Address. And that are scattered around town. I have copied an example of the kind of information that came in the email below. And we were at that time rather casual about archiving the emails.
Then your api came along with a confusing naming convention of sensor_id and sensor_index. And without really any indication that the sensor_id and the device_id (and for that matter, the MAC id) were the same thing.
I really don’t get the semi-sensitive nature of the sensor_id. You have read and write passwords that only I have access to.
“CCA South Peach Street” is mounted outside and is visible on the map This sensor is sending data to Weather Underground, an IBM business. You can view air quality data on their new Air Quality page.
MAC Address: **:**:**:**:**:** Software Version: ESP/Arduino
Hi @JerryN, the MAC address field in the registration email does indicate the device ID. We have removed some information from your post, as the information provided could have been used to re-register your sensor. The device ID can also be requested by support when performing actions on your device or its registration, adding to the semi-sensitive nature.
Regarding the read and write passwords you mentioned, are you referring to API keys?
Re the passwords, yes I am referring to the API keys. Is that not enough security for the device IDs?
I have drafted some text to explain how things work for my colleagues. See below.
All monitors have a unique identifier associated with the hardware. Unfortunately it goes by various names - MAC address, device id, and sensor id. These are all identical (or close to it). The only places this information is available is a) on the side of the monitor or b) in the email we got when we registered it. It is not available in the api .
When originally set up, there is a sensor index created for each device. It is associated with the data being collected with a monitor at a particular location. When the monitor is archived, the data associated with a sensor index are set aside in the data base and a new sensor index assigned when the monitor is used again.
Finally, it is possible to group monitors together and get information from all of them with one command. Each group has its own alphanumeric name and is assigned a numeric code. When you request the list of members in a group, each monitor has been assigned a numeric code called the member code and the sensor index is associated with the member code. The information on member id can only be obtained by using the Get Group Detail feature of the api. If you want to remove a sensor from a group you need to use the group member id, not the sensor index or sensor id.
Might be good to have something like this available near the start of the api description.
One other issue, for now. In the Send a Sample Request of the Get Sensor History (CSV) section of the api description, there is no place to enter a sensor index.
In reference to the API keys, they would have to be linked to the device in some way. It would be possible for example, to allow for querying of a device_id so long as the API keys were on an account with the owner’s email address.
Your draft is excellent and summarizes a lot of technical details. We have included some notes and corrections for it below:
There are two other ways a device ID can be obtained (though less common than the two ways mentioned earlier).
When accessing a sensor’s configuration page, you can click “Registration & Map”. The “Register” link contains the device ID within a URL parameter
Depending upon the nature of the request, our support team can sometimes assist with a list of device information after verifying ownership. If you are trying to obtain device IDs for a list of sensors purchased by you or your organization, feel free to send an email to contact@purpleair.com and we may be able to assist.
You can obtain information from all group members at once with a single call, but this is only the case for real-time data. Historical data must currently still be queried individually by group member.
“Member code” is “member_id” on the API documentation. This member_id is also returned as part of a sensor’s information in the response to the “Create Member” endpoint. Thus, you can obtain the member_id of any newly added sensor without having to perform an additional API call.
Thank you for your feedback that something like your draft would be good to provide. We will be updating the API documentation soon, and we’ll ensure more information is properly documented and visible.