Respirer API Documentation

API Overview

The Respirer Quartz Bulk Raw Data API is a specialized tool designed for the seamless collection and uploading of environmental sensor data. This API facilitates the transmission of multiple sensor readings in a single request, promoting efficiency and reducing the need for repeated individual submissions.

Purpose and Use Cases

The primary purpose of this API is to enable users, particularly developers and technical teams in the environmental monitoring and IoT sectors, to upload data from various environmental sensors. This includes but is not limited to:

• Particulate Matter Measurements: Tracking air quality by measuring levels of PM1, PM2.5, and PM10.
• Environmental Conditions: Collecting data on temperature, humidity, atmospheric pressure, and altitude.

General Functionalities

The API allows for:

• Batch Processing: Users can submit multiple readings in one single API call, which streamlines data handling.
• Comprehensive Data Collection: A wide array of fields enables detailed monitoring, though many are optional
• Error Handling: It provides clear responses based on the success or failure of the requests, ensuring users can troubleshoot effectively.

Endpoint

The Respirer Quartz Bulk Raw Data API is accessed through a specific endpoint designed for data submission. To upload your sensor readings, use the following HTTP method and URL:

HTTP Method: POST

When making a request to this endpoint, users can expect a structured response that will inform them about the success or failure of their data submissions. The API is designed to accept an array of JSON objects in the request body, with each object containing various fields related to environmental sensor metrics

API Structure

• Request Format: The request body must include an array of JSON objects.
• Response Format: Depending on the outcome of the request, users can receive different status codes indicating success, partial success, or error conditions.

Request Format

To successfully interact with the Respirer Quartz Bulk Raw Data API, it is essential to format the requests correctly as JSON objects. The API requires an array of JSON objects to be sent in the request body, where each object corresponds to an individual sensor reading. Below are the specific considerations for constructing these requests.

Example Request Format

The request body must adhere to the following JSON array structure:

[
  {
    "imei": "device_identifier",
    "timestr2": "DD/MM/YYYYTHH:MM:SS",
    "pm1cnc": "value",
    ...
  }
]

Mandatory Fields

Each JSON object must contain certain required fields:

• imei (String): This is the unique identifier for the sensor device.
• timestr2 (String): The timestamp indicating when the reading was taken. The format must be "DD/MM/YYYYTHH:MM:SS".

Optional Fields

While the API allows for numerous optional fields that provide additional data on environmental conditions, submitting as much data as available is encouraged for comprehensive monitoring. The optional fields include:

• pm1cnc, pm2.5cnc, pm10cnc (String/null): Concentrations of particulate matter in micrograms per cubic meter (μg/m³).
• temp, humidity, pres, altd (String): Environmental metrics such as temperature (°C), humidity percentage, atmospheric pressure (hPa), and altitude (meters).

Formatting Requirements

• Null Values: It is acceptable to set optional fields to null if data is unavailable.
• Unique Timestamps: Each reading in the batch must have a distinct timestamp to ensure clarity and prevent data overlap.

Providing well-structured and comprehensive JSON objects will enhance the effectiveness and efficiency of data uploads, maximizing the utility of the API in environmental monitoring applications.

Headers

To ensure proper functioning of the Respirer Quartz Bulk Raw Data API, specific headers are required in the API requests. The primary header to include is:

• Content-Type: application/json

Request Body

When submitting sensor readings to the Respirer Quartz Bulk Raw Data API, it is crucial that the request body is accurately constructed. The requested data must be formatted as an array of JSON objects, with each representing an individual sensor reading. Below is a detailed breakdown of the required and optional fields that should be included in the request body.

Mandatory Fields

The following fields must be present in each JSON object:

Optional Fields

The API allows the inclusion of several optional fields that can enhance the richness of the environmental data being submitted. These include:

Formatting Guidelines

• Null Values: It is acceptable to include null values in optional fields that do not have available data.
• Unique Timestamps: Each reading in the array must have a unique timestamp to maintain clarity within the data set.

By adhering to these guidelines, users can maximize the effectiveness of their data submissions to the Respirer Quartz Bulk Raw Data API, contributing to more robust environmental monitoring.

Example Request

To demonstrate the proper use of the Respirer Quartz Bulk Raw Data API, below is a detailed example of a valid request body, complete with commentary on its key elements.

Example JSON Request

[
  {
    "imei": "simulator",
    "timestr2": "11/11/2025T16:12:00",
    "pm1cnc": "95",
    "pm2.5cnc": "121",
    "pm10cnc": null,
    "pm0.3cnt": "0",
    "pm0.5cnt": "658",
    "pm1cnt": "763",
    "pm2.5cnt": "767",
    "temp": "28.2",
    "humidity": "38.9",
    "pres": "947",
    "altd": "1841",
    "power_avl": "1",
    "solar_avl": "0",
    "lat": "23.98569",
    "lon": "74.63634",
    "battery": "97.50"
  },
  {
    "imei": "simulator",
    "timestr2": "11/11/2025T16:13:00",
    "pm1cnc": "90",
    "pm2.5cnc": "115",
    "pm10cnc": null,
    "pm0.3cnt": "1",
    "pm0.5cnt": "600",
    "pm1cnt": "710",
    "pm2.5cnt": "750",
    "temp": "28.3",
    "humidity": "39.2",
    "pres": "948",
    "altd": "1840",
    "power_avl": "1",
    "solar_avl": "0",
    "lat": "23.98569",
    "lon": "74.63634",
    "battery": "96.50"
  }
]

Key Elements Breakdown

• imei: This field uniquely identifies the device sending the data. In this example, both JSON objects use "simulator" as the identifier, which must correspond to a registered device.
• timestr2: The timestamp format is crucial. Each reading captures the time in "DD/MM/YYYYTHH:MM:SS" format. Here, 11/11/2025T16:12:00 and 11/11/2025T16:13:00 represent consecutive readings taken a minute apart.
• pm1cnc, pm2.5cnc, pm10cnc: These fields reflect concentrations of particulate matter in micrograms per cubic meter (μg/m³). Notably, pm10cnc is set to null, indicating data is unavailable, showcasing that null values are acceptable.
• Temperature and Humidity: The fields temp and humidity provide additional environmental context with values of "28.2" Celsius and "38.9" percent respectively.
• Power Availability: The fields power_avl and solar_avl indicate electricity availability for the device, highlighted as 1 (available) and 0 (unavailable).

This structured request clearly illustrates not just correct syntax but also how to incorporate a mix of required and optional fields, optimizing data collection and environmental monitoring capabilities

Response Codes

When interacting with the Respirer Quartz Bulk Raw Data API, it's vital to understand the various HTTP status codes that can be returned in the API's responses. These codes provide insight into the outcome of your requests, indicating whether they were successful, partially successful, or failed. Here are the key response codes you may encounter:

Detailed Explanations

1. 200 OK: This status indicates that the API has successfully processed all sent messages. For example, a successful bulk ingestion response might return:

   {
     "message": "Bulk ingestion successful",
     "messages_processed": 3
   }
   

2. 207 Multi-Status: In this case, the API managed to process some, but not all, of the submitted messages. The response will include details about which messages failed along with the reasons. An example response is:

   {
     "message": "Bulk ingestion partially successful",
     "messages_processed": 2,
     "failed_messages": 1,
     "errors": [
       "Message 2 failed: KafkaError ..."
     ]
   }
   

3. 400 Bad Request: This error signifies that the request was not formatted correctly, possibly due to it not being a list or incorrect data types. An example response format is:

   {
     "error": "Expected a list of JSON objects"
   }
   

4. 500 Internal Server Error: This indicates an unexpected server issue that could not handle the request properly. The response may look like:

   {
     "error": "Internal Server Error: <error message>"
   }
   
   

Understanding these response codes will help you quickly diagnose issues that may arise during the data submission process while working with the Respirer Quartz Bulk Raw Data API.

Response Examples

The Respirer Quartz Bulk Raw Data API provides various response codes to indicate the success or failure of bulk data submissions. Below are detailed examples of potential responses for each status code, featuring sample JSON payloads.

Successful Response (200 OK)

When the API processes all messages successfully, it will return a response indicating the successful ingestion of data:

{
  "message": "Bulk ingestion successful",
  "messages_processed": 3
}

This response confirms that all three sensor readings sent were processed without any issues.

Partial Success (207 Multi-Status)

In cases where some messages are processed, while others fail, the API will respond with a multi-status indication. For example:

{
  "message": "Bulk ingestion partially successful",
  "messages_processed": 2,
  "failed_messages": 1,
  "errors": [
    "Message 2 failed: KafkaError ..."
  ]
}

This response informs users that two readings were successfully ingested while one encountered an error, allowing for targeted troubleshooting.

Bad Request (400)

If the request format is incorrect, the API will respond with a 400 status code. An example could be:

{
  "error": "Expected a list of JSON objects"
}

This alerts users to the formatting issue that needs rectification.

Internal Server Error (500)

If a server-side issue occurs, the API returns a 500 status code, as shown here:

{
  "error": "Internal Server Error: <error message>"
}

This response indicates an unexpected problem within the server, requiring further investigation for resolution.

These response examples guide users in understanding the outcome of their API interactions and help troubleshoot issues effectively.

Usage Notes

When utilizing the Respirer Quartz Bulk Raw Data API, there are several important considerations to keep in mind for efficient and effective use

Batch Processing Capabilities

1. Batch Submissions: The API allows you to submit multiple sensor readings in a single request. This significantly enhances efficiency, reducing the overhead associated with multiple individual requests.
2. Unique Timestamps: Each reading in a batch must have a unique timestamp. This is critical to prevent data overlap and ensure accurate tracking of environmental conditions over time.

Significance of the imei Field

• Device Identifier: The imei field serves as the unique identifier for each sensor device. It is essential that this value matches the device registered in the system to prevent data mismatches.

Best Practices

• While certain fields are optional, providing as much data as available is highly recommended. This ensures comprehensive monitoring and analysis of environmental conditions.
• It is crucial to format the request according to the specified guidelines. Incorrectly structured requests may lead to errors and hinder data collection efforts.

By observing these practices, users can maximize the utility of the Respirer Quartz Bulk Raw Data API for their environmental monitoring initiatives

Rate Limits

The Respirer Quartz Bulk Raw Data API can handle up to 2,000 records per request. Exceeding this may lead to errors or failed submissions

For detailed guidance, please contact Respirer Living Sciences Pvt. Ltd. directly based on your project and usage needs.