Skip to main content

​
Overview

The Humidity endpoint allows you to submit humidity readings from sensors monitoring plant environments. This endpoint tracks relative humidity levels in plant growing areas.

​
Endpoint

POST /api/umidade/

​
Model Structure

The Umidade model extends the base Sensor model: 
class Umidade(Sensor):
    umidade = models.FloatField(max_length=200, default='00')
    unidade_medida = models.CharField(max_length=50, default='porcentagem')
Source: models.py:19-23

​
ViewSet Implementation

class UmidadeViewset(viewsets.ViewSet):
    permission_classes = (IsAuthenticated,)
    
    def create(self, request):
        serializer = UmidadeSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        the_response = UmidadeSerializer(serializer.save())
        return Response(the_response.data, status=status.HTTP_201_CREATED)
Source: views.py:106-112

​
Authentication

This endpoint requires authentication. Include your API token in the Authorization header.
Authorization: Token 2d75140c068049278f9cb7d39b1a20f05aecdc56
See Authentication for details.

​
Request Parameters

​
nome
string
required
Sensor name identifierExample: "Umidade"
​
tipo
string
required
Type of sensor locationExample: "Plantas"
​
grupo
string
required
Sensor group classificationExample: "Grupo P"
​
umidade
float
required
Humidity reading from the sensor (percentage)Example: 65.5
​
unidade_medida
string
required
Unit of measurement for humidityDefault: "porcentagem"Example: "porcentagem"

​
Response Fields

​
id
integer
Auto-generated unique identifier for the record
​
nome
string
Sensor name as provided in request
​
tipo
string
Sensor type as provided in request
​
grupo
string
Sensor group as provided in request
​
umidade
float
Humidity value submitted (percentage)
​
unidade_medida
string
Unit of measurement for the humidity
​
data_criacao
datetime
Timestamp when the record was created (auto-generated)

​
Example Request

curl -X POST http://127.0.0.1:8000/api/umidade/ \
  -H "Authorization: Token 2d75140c068049278f9cb7d39b1a20f05aecdc56" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Umidade",
    "tipo": "Plantas",
    "grupo": "Grupo P",
    "umidade": "65.5",
    "unidade_medida": "porcentagem"
  }'

​
Example Response

Status Code: 201 Created 
{
  "id": 28,
  "nome": "Umidade",
  "tipo": "Plantas",
  "grupo": "Grupo P",
  "umidade": 65.5,
  "unidade_medida": "porcentagem",
  "data_criacao": "2026-03-11T10:30:45.123456Z"
}

​
Error Responses

​
Missing Authentication Token

Status Code: 401 Unauthorized 
{
  "detail": "Authentication credentials were not provided."
}

​
Invalid Token

Status Code: 401 Unauthorized 
{
  "detail": "Invalid token."
}

​
Missing Required Fields

Status Code: 400 Bad Request 
{
  "umidade": [
    "This field is required."
  ],
  "nome": [
    "This field is required."
  ]
}

​
Invalid Data Type

Status Code: 400 Bad Request 
{
  "umidade": [
    "A valid number is required."
  ]
}

​
MQTT Integration Example

Example from the Raspberry Pi MQTT client: 
# From mqtt-django.py:36-47
if message.topic == topic_hum:
    nome = "Umidade"
    tipo = "Plantas"
    grupo = "Grupo P"
    umidade = str(message.payload.decode("utf-8"))
    unidade_medida = "porcentagem"
    
    umidade = {
        'nome': nome,
        'tipo': tipo,
        'grupo': grupo,
        'umidade': umidade,
        'unidade_medida': unidade_medida
    }
    
    headers = {'Authorization': 'Token 2d75140c068049278f9cb7d39b1a20f05aecdc56'}
    url_umidade = "http://127.0.0.1:8000/api/umidade/"
    send_umidade = requests.post(
        url_umidade,
        headers=headers,
        json=umidade
    )

​
Serializer Details

The endpoint uses UmidadeSerializer with depth=1 to include related object details: 
class UmidadeSerializer(serializers.ModelSerializer):
    class Meta:
        model = Umidade
        fields = '__all__'
        depth = 1

    def create(self, validated_data):
        umidade = Umidade.objects.create(**validated_data)
        umidade.save()
        return umidade
Source: serializers.py:17-26

​
Use Cases

  • Monitor relative humidity in plant growing environments
  • Track humidity fluctuations throughout the day
  • Trigger irrigation or ventilation based on humidity levels
  • Historical humidity data analysis for plant health
  • IoT device integration via MQTT
  • Greenhouse climate control
  • Prevent mold and fungal issues

​
Optimal Humidity Ranges

Different plants require different humidity levels:
  • Tropical Plants: 60-80%
  • Succulents: 30-50%
  • General Houseplants: 40-60%
  • Seedlings: 70-90%

​
Best Practices

  1. Regular Readings: Submit humidity readings at consistent intervals (e.g., every 5-10 minutes)
  2. Valid Ranges: Ensure humidity values are between 0-100%
  3. Error Handling: Implement retry logic for failed submissions
  4. Data Validation: Validate sensor readings before submission
  5. Calibration: Regularly calibrate humidity sensors for accuracy

Build docs developers (and LLMs) love

Get started for freeTalk to us