Konsultieren und senden Sie Ovitrap-, Block- und Feldbesuchsdaten direkt von Ihrem System aus. Auf dieser Seite werden alle verfügbaren öffentlichen und privaten Endpunkte dokumentiert.
Diese API verfügt über Endpunkte öffentlich und privat. Die öffentliche API gibt Daten zu Breitengrad, Längengrad und Anzahl der Eier für jede teilnehmende Gemeinde im Zeitverlauf zurück, ohne dass eine Authentifizierung erforderlich ist. Die private API wird nur für Anwendungen empfohlen, die mit Conta Ovos zusammenarbeiten, da sie vertrauliche Daten offenlegt und Ihnen das Einfügen, Ändern und Entfernen von Datensätzen ermöglicht.
Authentifizierung und Schlüssel
Um die private API nutzen zu können, benötigen Sie einen Zugriffsschlüssel (key). Um es zu kaufen, senden Sie eine E-Mail an contaovosdengue@gmail.com mit der Angabe:
Warum benötigen Sie API-Zugriff?
Welche Zugangsebene ist erforderlich (kommunal, regional, staatlich oder landesweit);
Zu welcher geografischen Region gehören Sie?
Der Schlüssel besteht aus 45 zufällige Buchstaben und muss im Parameter mitgesendet werden key jeder privaten Anfrage. Der mit dem Schlüssel verknüpfte geografische Geltungsbereich und Plan (api_access_municipality_id, state_id, region_id, country_id, plan) definiert automatisch, welche Datensätze es lesen oder ändern kann – ein Gemeindeschlüssel kann beispielsweise nur Daten der Gemeinde selbst lesen oder ändern.
Wohin soll der Schlüssel geschickt werden: prefira o cabeçalho Authorization: Bearer SUA_CHAVE. A query string da URL (?key=SUA_CHAVE) continua aceita em todos os endpoints, mas fica gravada em logs de servidor e proxies, e o cabeçalho não. Enviar a chave apenas no corpo do formulário resulta em 404 "Wrong key". Die anderen POST-Felder erscheinen weiterhin im Anfragetext.
Pagination: die Parameter page Akzeptieren Sie maximal 100 auf Endpunkten, die Paging unterstützen. Ungültige oder fehlende Werte nehmen Seite 1 ein.
Antwortcodes
Alle Endpunkte folgen demselben HTTP-Statusmuster:
Code
Bedeutung
200
Anfrage erfolgreich bearbeitet.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
Die informierte Ressource gehört nicht zum Geltungsbereich (Stadt/Bundesland/Region) des verwendeten Schlüssels.
404
Ungültiger Schlüssel (Wrong key) oder Ressource nicht gefunden.
409
Für diese Kombination aus Kennung, Jahr und Woche ist bereits ein Datensatz vorhanden.
500
Interner Fehler bei der Verarbeitung der Anfrage.
Como enviar o corpo de um POST
Todos os endpoints POST aceitam três formatos, e você escolhe o que for mais fácil no seu sistema:
Formato
Content-Type
Formulário simples
application/x-www-form-urlencoded
Formulário multipart
multipart/form-data
JSON
application/json
Não defina o cabeçalho Content-Type à mão no Postman, no Insomnia ou em bibliotecas de HTTP. Deixe a ferramenta gerá-lo: no multipart ela precisa incluir o boundary, e um Content-Type que não corresponde ao corpo faz todos os campos chegarem vazios.
Quando isso acontece a resposta é 400 com esta mensagem, e ela é sobre o envelope, não sobre os seus campos:
{
"error": "Não consegui ler os campos do corpo da requisição. Envie como form-data, x-www-form-urlencoded ou JSON.",
"dica": "Se usa Postman ou Insomnia, apague o cabeçalho Content-Type e deixe a ferramenta gerá-lo sozinha."
}
A chave (key) vai sempre na URL, nunca no corpo.
Öffentliche Endpunkte
GET/api/lastcountingpublicÖffentlich
Zuletzt veröffentlichte Zählungen
Gibt die neuesten nach Standort (Stadt, Bundesland oder Land) veröffentlichten Zählungen mit der Anzahl der Eier und den Eileiterdaten zurück.
Parameter
Name
Typ
Beschreibung
state
string
Landescode. Beispiel: state=RJ.
municipality
string
Name der Gemeinde. Beispiel: municipality=Ponta Pora
country
string
Ländername. Beispiel: country=Brasil. Wenn weggelassen, wird von „Brasilien“ ausgegangen.
page
int
Paginierungsseite (Standard 1, maximal 100).
id
int
Zeigt nur Vorkommen der angegebenen ID an. Beispiel: id=7876.
date
date
Zeigt Vorkommen ab dem Datum der Aufnahme an. Beispiel: date=2025-01-01.
date_collect
date
Zeigt Vorkommnisse ab dem Abholdatum an. Beispiel: date_collect=2024-12-12.
date_start
date
Startdatum zum Filtern der Zählungen. Beispiel: date_start=2025-01-01.
date_end
date
Enddatum zum Filtern der Anzahl. Beispiel: date_end=2025-12-31.
Notiz: Wenn keine Standortparameter gesendet werden, gibt der Endpunkt die neuesten Zählungen aus Brasilien zurück.
Konkrete Antworten:
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
Gibt die in der Gemeinde registrierten Blöcke zurück – eine Zeile pro Block, mit dem Polygon, der Gesamtzahl der Grundstücke nach Typ und der durchschnittlichen Anzahl der Anteile.
Neuer Endpunkt. Wenn Sie Besuche in Blöcken suchen, verwenden Sie /api/getmunicipalityblocksvisitpublic. Da es sich um einen öffentlichen Endpunkt handelt, enthält die Antwort nicht den für die Blockierung verantwortlichen Agenten oder Benutzer-/Team-IDs.
Parameter
Name
Typ
Beschreibung
state
string
Landescode. Beispiel: state=RJ.
municipality
string
Name der Gemeinde. Beispiel: municipality=Ponta Pora
country
string
Ländername. Beispiel: country=Brasil. Wenn weggelassen, wird von „Brasilien“ ausgegangen.
Gibt Daten zu den an den EDLs durchgeführten Wartungsarbeiten zurück, einschließlich der während jeder Wartung aufgezeichneten Beobachtungen.
Ersetzt/api/getmunicipalityedlvisitspublic. EDLs erhalten Wartung, keine Besuche – die Felder sind verschwunden edl_visit_* Zu edl_maintenance_*. Die alte URL funktioniert weiterhin und gibt weiterhin die alten Namen zurück, um Integrationen in der Produktion nicht zu unterbrechen, wird jedoch eingestellt.
Parameter
Name
Typ
Beschreibung
state
string
Landescode. Beispiel: state=RJ.
municipality
string
Name der Gemeinde. Beispiel: municipality=Ponta Pora
country
string
Ländername. Beispiel: country=Brasil. Wenn weggelassen, wird von „Brasilien“ ausgegangen.
Alle unten aufgeführten Endpunkte erfordern den Parameter key mit Ihrem API-Schlüssel.
GET/api/lastcountingPrivat
Zuletzt veröffentlichte Zählungen
Gibt die letzten im Rahmen des Schlüssels freigegebenen Zählungen zurück, mit Anzahl der Eier, Ovitrap-Daten und dem verantwortlichen Benutzer.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den Umfang der zurückgegebenen Zählungen.
page
int
Paginierungsseite (Standard 1, maximal 100).
date_start
date
Startdatum zum Filtern der Zählungen. Beispiel: date_start=2025-01-01.
date_end
date
Enddatum zum Filtern der Anzahl. Beispiel: date_end=2025-12-31.
Konkrete Antworten:
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
Gibt Daten von EDLs (strategische Punkte, die Agenten regelmäßig besuchen) innerhalb des geografischen Geltungsbereichs des Schlüssels zurück. Der Geltungsbereich wird automatisch durch den mit dem Schlüssel verknüpften Plan definiert – Gemeinde, Region, Staat oder Land – und es ist nicht erforderlich, die Gemeinde, den Staat oder das Land in der Anfrage zu informieren.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den geografischen Bereich der zurückgegebenen EDLs.
Achtung: Die Antwortfelder von diesem privaten Endpunkt werden mit dem Präfix fortgesetzt edl_visit_*. Nur der entsprechende öffentliche Endpunkt hat mit der Verwendung begonnen edl_maintenance_*.
Gibt Daten zu Besuchen bei EDLs innerhalb des geografischen Geltungsbereichs des Schlüssels zurück, einschließlich der bei jedem Besuch aufgezeichneten Beobachtungen. Der Geltungsbereich wird automatisch durch den mit dem Schlüssel verknüpften Plan definiert – Gemeinde, Region, Staat oder Land – und es ist nicht erforderlich, die Gemeinde, den Staat oder das Land in der Anfrage zu informieren.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den geografischen Bereich der wiederkehrenden Besuche.
Gibt Daten zu Aktionen (Behandlungsbesuchen) zurück, die in Blöcken innerhalb des geografischen Bereichs des Schlüssels durchgeführt werden. Der Geltungsbereich wird automatisch durch den mit dem Schlüssel verknüpften Plan definiert – Gemeinde, Region, Staat oder Land – und es ist nicht erforderlich, die Gemeinde, den Staat oder das Land in der Anfrage zu informieren.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den geografischen Bereich der zurückgegebenen Aktionen.
Gibt Daten von Ovitraps (Eiüberwachungspunkten) innerhalb des geografischen Geltungsbereichs des Schlüssels zurück. Der Geltungsbereich wird automatisch durch den mit dem Schlüssel verknüpften Plan definiert – Gemeinde, Region, Staat oder Land – und es ist nicht erforderlich, die Gemeinde, den Staat oder das Land in der Anfrage zu informieren.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Legt den geografischen Bereich der zurückgegebenen Ovitraps fest.
Gibt die Immobilien (strategische Punkte und besondere Immobilien) im geografischen Bereich des Schlüssels zurück. Der Bereich wird automatisch durch den mit dem Schlüssel verknüpften Plan festgelegt — kommunal, regional, bundesstaatlich oder landesweit — daher müssen Gemeinde, Bundesstaat oder Land in der Anfrage nicht angegeben werden.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den geografischen Bereich der zurückgegebenen Punkte.
Sendet den Messwert einer Ovitrap. Es ist möglich, Daten an eine bestehende Ovitrap zu senden oder die Daten zu senden und gleichzeitig eine neue Ovitrap zu installieren.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den Umfang der Einreichung.
Für den Standardversand, bei dem die Installation einer neuen Ovitrap nicht erforderlich ist, senden Sie die folgenden Felder (alles verpflichtend) im Hauptteil der Anfrage (form):
{
"ovitrap_group_id": 97,
"ovitrap_lat": -7.000000,
"ovitrap_lng": -8.000000,
"date": "2025-01-20",
"counting_observation_id": 1,
"counting_observation": "caso o counting_observation_id seja 9",
"counting_eggs": 5
}
Tabelle mit den IDs der einzelnen Beobachtungstypen (counting_observation_id):
ID
Bedeutung
1
Keine Beobachtungen
2
Abstand zwischen Installation und Abholung länger als erwartet
3
Ovitrap oder fehlende Palette
4
Ovitrap oder kaputte Palette
5
Ovitrap oder Palette entfernt
6
Trockene Eileiter
7
Geschlossenes Haus
8
Mit Wasser gefüllte Ovitrap
9
Ovitrap mit wenig Wasser
10
Noch eine Beobachtung
Um eine neue Ovitrap neben der Sendung zu installieren, obligatorisch die Felder: ovitrap_lat, ovitrap_lng, ovitrap_group_id
Tabelle mit den IDs der einzelnen Ovitrap-Typen (ovitrap_type_id): Senden Sie 1 an die städtische Ovitrap und 2 an die ländliche Ovitrap. Das Feld ist optional und wenn es nicht gesendet wird, wird die Ovitrap als urban installiert:
ID
Bedeutung
1
Städtische Ovitraps (Standard)
2
Ländliche Ovitrap
Konkrete Antworten:
400 — wenn eines der Pflichtfelder nicht gesendet wird: ovitrap_lat, ovitrap_lng, ovitrap_group_id, date
400 — quando a coordenada está fora da faixa geográfica: ovitrap_lat precisa estar entre -90 e 90, e ovitrap_lng entre -180 e 180. O erro mais comum é o ponto decimal se perder na formatação do número — enviar -23374059 no lugar de -23.374059. A resposta traz os valores recebidos em ovitrap_lat e ovitrap_lng.
400 — wenn die ovitrap_type_id gesendet ist weder 1 noch 2.
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
404 — Für diese Ovitrap gibt es bereits eine Zählung, Jahr und Woche.
POST/api/postdeletecountingPrivat
Lesung löschen
Entfernt das Lesen von einer Ovitrap.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel. Definiert den Umfang der Entfernung.
Beispiel anfordern
curl -X POST \
"/de-de/api/postdeletecounting?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Konkrete Antworten:
400 — Wann date wird nicht gesendet.
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
POST/api/postdeleteovitrapPrivat
Ovitraps löschen
Entfernen Sie eine Ovitrap.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postdeleteovitrap?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivat
Besuch einfügen
Registrieren Sie einen Besuch/eine Aktion in einem Block. Um den Besuch zu einem bestehenden Block hinzuzufügen, senden Sie das Feld block_id. Wenn es nicht existiert, verwenden Sie block_group_id — Das System erstellt den Block automatisch. Dieser Endpunkt ermöglicht nur das Einfügen von Blöcken, die innerhalb der Gemeinde des Antragstellers liegen.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postaction?key=KEY"
Eingesandte Daten form-data, x-www-form-urlencoded, JSON oder Abfrageparameter verwenden block_id:
400 — Wann date nicht gesendet wird oder wenn eines der numerischen Felder keine gültige Zahl ist.
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
400 — Wann block_group_id wird beim Erstellen eines neuen Blocks nicht gesendet.
400 — quando a coordenada está fora da faixa geográfica: block_lat precisa estar entre -90 e 90, e block_lng entre -180 e 180. O erro mais comum é o ponto decimal se perder na formatação do número — enviar -23374059 no lugar de -23.374059.
400 — Wann block_coordinates passa de 2000 caracteres. Antes o desenho era gravado pela metade, em silêncio, e o quarteirão abria sem mapa; agora a requisição é recusada e a resposta traz o tamanho enviado em block_coordinates_length.
403 — wenn die block_id Die informierte Person gehört nicht zur Kerngemeinde.
409 — wenn für diesen Block, dieses Jahr und diese Woche bereits ein Besuch vorliegt.
POST/api/postdeleteactionPrivat
Besuch löschen
Entfernt einen Besuch aus einem Block.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postdeleteaction?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Konkrete Antworten:
400 — Wann date wird nicht gesendet.
400 — wenn einer der gesendeten Datumswerte nicht im Format vorliegt YYYY-MM-DD. Die Antwort bringt die Liste der ungültigen Felder ein invalid_fields.
POST/api/postdeleteblockPrivat
Block löschen
Entfernt einen Block.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postdeleteblock?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlPrivat
Inserir EDL
Cadastra um EDL (ponto estratégico de vigilância) no município da sua chave. Reenviar o mesmo edl_group_id devolve o EDL já existente em vez de duplicar, então é seguro repetir um lote.
O município é sempre o da sua chave — não é possível enviá-lo no corpo.
Obrigatórios: edl_group_id, edl_date (AAAA-MM-DD), edl_lat e edl_lng. Os demais campos são opcionais. Devolve o edl_id.
Se você usa Postman ou Insomnia, não defina o cabeçalho Content-Type à mão: a ferramenta precisa gerá-lo sozinha. Um Content-Type que não corresponde ao corpo faz os campos chegarem vazios.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postedl?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
Este é o único endpoint que pede um id interno: a tabela de imóveis não tem um código definido por você, ao contrário de ovitrampa, quarteirão e EDL. O place_id vem de /api/getmunicipalityplaces.
Parameter
Name
Typ
Beschreibung
key
string
Ihr API-Schlüssel.
Beispiel anfordern
curl -X POST \
"/de-de/api/postdeleteplace?key=KEY"
Im Hauptteil der Anfrage erforderliche Daten (form-data, x-www-form-urlencoded ou JSON):
{
"place_id": 142
}
Editar registros
Os endpoints /api/postedit* editam ovitrampas, contagens, quarteirões, visitas, EDLs, manutenções e imóveis que já existem. As regras valem para todos:
Escopo: só registros do município da sua chave, como nos demais POST. Registro de outro município responde 404.
Edição parcial: só muda o que você envia. Campo ausente fica como está; campo enviado vazio grava vazio (é assim que se apaga um complemento, por exemplo). Números, datas, coordenadas e códigos não aceitam vazio.
Tudo ou nada: se um dos campos for inválido, nenhum é gravado e a resposta 400 diz qual e por quê.
Mesmos nomes da criação: os campos têm os nomes que você já usa em /api/postcounting, /api/postaction, /api/postedlmaintenance e /api/postplace.
Trocar código ou data:new_ovitrap_group_id, new_block_group_id, new_edl_group_id renomeiam; nas leituras, new_date muda a data e recalcula a semana epidemiológica. Se o novo código ou a nova data já existirem, a resposta é 409 e nada muda.
Resposta:200 com o registro como ficou. Médias, totais e semanas que dependem do registro são recalculados na mesma chamada.
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as leituras a partir dessa data. Sem ele, as leituras antigas continuam com o endereço de quando foram feitas.
A resposta traz também countings_updated: quantas leituras receberam o endereço novo.
Imóveis existentes: block_land_residence, block_land_commercial, block_land_empty, block_land_strategy, block_land_another (o total é recalculado)
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as visitas a partir dessa data. Sem ele, as visitas antigas continuam com o endereço de quando foram feitas.
400 — algum campo tem valor inválido: nada é alterado, e a resposta lista os campos em invalid_fields e o motivo de cada um em details.
400 — nenhum campo editável foi enviado.
404 — o registro não existe no município da sua chave.
409 — já existe um quarteirão com o new_block_group_id no município.
POST/api/posteditactionPrivat
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
Name
Typ
Beschreibung
block_group_id
string
Código do quarteirão no município.
date
string
Data da visita a editar (YYYY-MM-DD).
Campos editáveis
new_date
Visitados, como em /api/postaction: block_land_residence, block_land_commercial, block_land_empty, block_land_strategy, block_land_special, block_land_another
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as manutenções a partir dessa data. Sem ele, as manutenções antigas continuam com o endereço de quando foram feitas.