Skip to main content

​
Overview

The Water Level endpoint allows you to submit water level readings from sensors monitoring aquarium water levels. This endpoint tracks water depth and helps maintain optimal water levels.

​
Endpoint

POST /api/nivel/

​
Model Structure

The NivelAgua model extends the base Sensor model: 
class NivelAgua(Sensor):
    nivel = models.FloatField(max_length=200, default='00')
    nivel_minimo = models.FloatField(max_length=200, default='200')
    unidade_medida = models.CharField(max_length=50, default='centímetros')
Source: models.py:31-36

​
ViewSet Implementation

class NivelAguaViewset(viewsets.ViewSet):
    permission_classes = (IsAuthenticated,)
    
    def create(self, request):
        serializer = NivelAguaSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        the_response = NivelAguaSerializer(serializer.save())
        return Response(the_response.data, status=status.HTTP_201_CREATED)
Source: views.py:115-121

​
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: "Nível de Água"
​
tipo
string
required
Type of sensor locationExample: "Acuario"
​
grupo
string
required
Sensor group classificationExample: "Grupo A"
​
nivel
float
required
Current water level reading from the sensorExample: 45.5
​
nivel_minimo
float
required
Minimum acceptable water level thresholdDefault: 200Example: 30
​
unidade_medida
string
required
Unit of measurement for water levelDefault: "centímetros"Example: "centímetros"

​
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
​
nivel
float
Current water level value submitted
​
nivel_minimo
float
Minimum water level threshold
​
unidade_medida
string
Unit of measurement for the water level
​
data_criacao
datetime
Timestamp when the record was created (auto-generated)

​
Example Request

curl -X POST http://127.0.0.1:8000/api/nivel/ \
  -H "Authorization: Token 2d75140c068049278f9cb7d39b1a20f05aecdc56" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Nível de Água",
    "tipo": "Acuario",
    "grupo": "Grupo A",
    "nivel": "45.5",
    "nivel_minimo": 30,
    "unidade_medida": "centímetros"
  }'

​
Example Response

Status Code: 201 Created 
{
  "id": 67,
  "nome": "Nível de Água",
  "tipo": "Acuario",
  "grupo": "Grupo A",
  "nivel": 45.5,
  "nivel_minimo": 30.0,
  "unidade_medida": "centímetros",
  "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 
{
  "nivel": [
    "This field is required."
  ],
  "nome": [
    "This field is required."
  ]
}

​
Invalid Data Type

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

​
MQTT Integration Example

Example from the Raspberry Pi MQTT client: 
# From mqtt-django.py:90-102
if message.topic == topic_nivel:
    nome = "Nível de Água"
    tipo = "Acuario"
    grupo = "Grupo A"
    nivel = str(message.payload.decode("utf-8"))
    nivel_minimo = 30
    unidade_medida = "centímetros"
    
    nivel = {
        'nome': nome,
        'tipo': tipo,
        'grupo': grupo,
        'nivel': nivel,
        'nivel_minimo': nivel_minimo,
        'unidade_medida': unidade_medida
    }
    
    headers = {'Authorization': 'Token 2d75140c068049278f9cb7d39b1a20f05aecdc56'}
    url_nivel = "http://127.0.0.1:8000/api/nivel/"
    send_nivel = requests.post(
        url_nivel,
        headers=headers,
        json=nivel
    )

​
Serializer Details

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

    def create(self, validated_data):
        nivel = NivelAgua.objects.create(**validated_data)
        nivel.save()
        return nivel
Source: serializers.py:29-38

​
Use Cases

  • Monitor aquarium water level in real-time
  • Track water evaporation rates over time
  • Trigger alerts when water level drops below minimum threshold
  • Automate water refill systems
  • Prevent pump damage from low water levels
  • Historical water level data analysis
  • IoT device integration via MQTT

​
Water Level Monitoring Best Practices

  1. Set Appropriate Thresholds: Configure nivel_minimo based on your aquarium requirements
  2. Regular Readings: Submit readings at consistent intervals (e.g., every 10-15 minutes)
  3. Calibration: Regularly calibrate sensors for accuracy
  4. Alert Systems: Implement alerts when level drops below nivel_minimo
  5. Evaporation Compensation: Account for normal evaporation rates in your monitoring

​
Safety Considerations

  • Maintain water level above minimum to protect pumps and filters
  • Low water levels can stress aquatic life
  • Sudden drops may indicate leaks requiring immediate attention
  • Ensure sensors are waterproof and properly sealed

Build docs developers (and LLMs) love

Get started for freeTalk to us