05: Getting Started with the Atmotube Cloud API

Goals of this Notebook

This vignette demonstrates how to use the get_atmotube_data() to download Atmotube data via the Atmotube Cloud API using the tidypollute package.

API Authentication

To access the Atmotube API, you need: - An API key (provided by Atmotube) - The MAC address of your Atmotube device

Make sure you store your API key securely.

Introduction

This vignette demonstrates how to use the get_atmotube_data() function to retrieve air quality data from the Atmotube Cloud API. The function automatically adapts to the requested date range, making a single API request for short durations and batching requests for longer durations.

Retrieving Atmotube Data

The get_atmotube_data() function fetches Atmotube air quality data based on user-defined parameters.

Required Parameters

api_key: Your Atmotube API key.
mac: The MAC address of your Atmotube device (format: "aa:bb:cc:dd:ee:ff").
start_date: Start date in YYYY-MM-DD format.
end_date: End date in YYYY-MM-DD format.

Optional Parameters

order: Sorting order, either "asc" (ascending) or "desc" (descending). Default is "asc".
format: Response format, either "json" or "csv". Default is "json".
offset: Starting index for pagination. Default is 0.
limit: Number of records to retrieve per request (1-1440). Default is 1440.
separator: CSV separator if format="csv". Default is ",".
base_url: API base URL. Default is "https://api.atmotube.com/api/v1/data".

Also in this table:

Parameter	Description	Default	Valid Values
`order`	Sorting order	`"asc"`	`"asc"`, `"desc"`
`format`	Response format	`"json"`	`"json"`, `"csv"`
`offset`	Pagination offset	`0`	`≥0`
`limit`	Number of records	`1440`	`1-1440`
`separator`	CSV separator	`"semicolon"`	Any delimiter

Example: Fetch Data for a Short Period (Within 7 Days)

api_key <- "your_api_key_here"
mac <- "aa:bb:cc:dd:ee:ff"
start_date <- "2024-06-01"
end_date <- "2024-06-03"

data <- get_atmotube_data(api_key, mac, start_date, end_date)
print(data)

Example: Fetch Data for a Longer Period (More than 7 Days)

The function automatically breaks the request into 7-day chunks with a 1-day overlap.

start_date <- "2024-06-01"
end_date <- "2024-07-01"

data <- get_atmotube_data(api_key, mac, start_date, end_date)
print(data)

Handling CSV Output

If you prefer CSV format, set format="csv":

data_csv <- get_atmotube_data(api_key, mac, start_date, end_date, format="csv")
writeLines(data_csv, "atmotube_data.csv")

Example: Fetching Data for Multiple Devices, Across Large Intervals

library(dplyr)
library(tidyr)
library(purrr)

# Example table with multiple Atmotube devices & date ranges
mac_table <- tibble::tibble(
  mac = c("aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66"),
  start_date = c("2024-06-01", "2024-06-10"),
  end_date = c("2024-07-01", "2024-07-05")
)

# Your Atmotube API Key
api_key <- "your_api_key_here"

# Fetch data and unnest results into a long format
results_df <- mac_table %>%
  rowwise() %>%
  mutate(data = list(get_atmotube_data(api_key, mac, start_date, end_date))) %>%
  ungroup() %>%
  unnest_wider(data)  # Expands list columns into separate columns

# View tidy output
print(results_df)

Error Handling

The function validates all parameters before making an API request. If an invalid parameter is provided, an error message is returned. Common checks include: - Invalid MAC address format. - Invalid date format. - Start date after the end date. - Exceeding API limits on pagination or record retrieval.

Summary

This vignette demonstrated how to use the get_atmotube_data() function to retrieve air quality data from the Atmotube API efficiently. The function dynamically handles single requests for short periods and batched requests for long periods to comply with API limits.

For further questions, refer to the Atmotube API documentation or contact support.

Coming Soon

Support for the Atmocube API. (Q1 2025)

Happy coding! 🚀

Dr. Nelson Roque