Consulta e invia i dati di ovitrap, isolato e visite in campo direttamente dal tuo sistema. Questa pagina documenta tutti gli endpoint pubblici e privati disponibili.
Questa API ha endpoint pubblici e privati. L'API pubblica restituisce nel tempo i dati su latitudine, longitudine e numero di uova per ciascun comune partecipante, senza necessità di autenticazione. L'API privata è consigliata solo per le applicazioni che lavorano in collaborazione con Conta Ovos, poiché espone dati sensibili e consente di inserire, modificare e rimuovere record.
Autenticazione e chiavi
Per utilizzare l'API privata avrai bisogno di una chiave di accesso (key). Per acquistarlo inviare una mail a contaovosdengue@gmail.com affermando:
Perché hai bisogno dell'accesso API;
Quale livello di accesso è richiesto (comunale, regionale, statale o nazionale);
Di quale regione geografica fai parte?
La chiave è composta da 45 lettere casuali e deve essere inviato nel parametro key di ogni richiesta privata. L'ambito geografico e il piano collegati alla chiave (api_access_municipality_id, state_id, region_id, country_id, plan) definire automaticamente quali record può leggere o modificare: una chiave comunale, ad esempio, può leggere o modificare solo i dati del comune stesso.
Dove inviare la chiave: 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". Gli altri campi POST continuano a essere visualizzati nel corpo della richiesta.
Impaginazione: i parametri page accettare un massimo di 100 sugli endpoint che supportano il paging. I valori non validi o mancanti occupano la pagina 1.
Codici di risposta
Tutti gli endpoint seguono lo stesso modello di stato HTTP:
Codice
Senso
200
Richiesta elaborata con successo.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
La risorsa informata non appartiene all'ambito (città/stato/regione) della chiave utilizzata.
404
Chiave non valida (Wrong key) o risorsa non trovata.
409
Esiste già un record per questa combinazione di identificatore, anno e settimana.
500
Errore interno durante l'elaborazione della richiesta.
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.
Endpoint pubblici
GET/api/lastcountingpublicPubblico
Ultimi conteggi rilasciati
Restituisce gli ultimi conteggi rilasciati per località (città, stato o paese), con il numero di uova e i dati di ovitrap.
Parametri
Nome
Tipo
Descrizione
state
string
Codice dello stato. Esempio: state=RJ.
municipality
string
Nome del comune. Esempio: municipality=Ponta Pora
country
string
Nome del paese. Esempio: country=Brasil. Se omesso, presuppone "Brasile".
page
int
Pagina di impaginazione (default 1, massimo 100).
id
int
Visualizza solo le occorrenze dell'ID specificato. Esempio: id=7876.
date
date
Visualizza le occorrenze dalla data di inclusione. Esempio: date=2025-01-01.
date_collect
date
Visualizza le occorrenze dalla data di raccolta in poi. Esempio: date_collect=2024-12-12.
date_start
date
Data di inizio per filtrare i conteggi. Esempio: date_start=2025-01-01.
date_end
date
Data di fine per filtrare i conteggi. Esempio: date_end=2025-12-31.
Nota: Se non vengono inviati parametri di posizione, l'endpoint restituisce i conteggi più recenti dal Brasile.
Risposte specifiche:
400 — quando una qualsiasi delle date inviate non è nel formato YYYY-MM-DD. La risposta contiene l'elenco dei campi non validi in invalid_fields.
Restituisce gli isolati censiti nel comune: una riga per isolato, con il poligono, il totale delle proprietà per tipologia e il numero medio di quote.
Nuovo punto finale. Se cerchi visite effettuate a isolati utilizza /api/getmunicipalityblocksvisitpublic. Poiché si tratta di un endpoint pubblico, la risposta non include l'agente responsabile dell'isolato o gli identificatori dell'utente/team.
Parametri
Nome
Tipo
Descrizione
state
string
Codice dello stato. Esempio: state=RJ.
municipality
string
Nome del comune. Esempio: municipality=Ponta Pora
country
string
Nome del paese. Esempio: country=Brasil. Se omesso, presuppone "Brasile".
Restituisce i dati sulla manutenzione eseguita sugli EDL, inclusa l'osservazione registrata durante ogni manutenzione.
Sostituisce/api/getmunicipalityedlvisitspublic. Gli EDL ricevono manutenzione, non visite: i campi sono scomparsi edl_visit_* A edl_maintenance_*. La vecchia URL continua a funzionare e continua a restituire i vecchi nomi, per non interrompere le integrazioni in produzione, ma è dismessa.
Parametri
Nome
Tipo
Descrizione
state
string
Codice dello stato. Esempio: state=RJ.
municipality
string
Nome del comune. Esempio: municipality=Ponta Pora
country
string
Nome del paese. Esempio: country=Brasil. Se omesso, presuppone "Brasile".
Restituisce i dati dagli EDL (punti strategici visitati periodicamente dagli agenti) nell'ambito geografico della chiave. L'ambito è definito automaticamente dal piano collegato alla chiave – comunale, regionale, statale o nazionale – e non è necessario informare il comune, lo stato o il paese nella richiesta.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Definisce l'ambito geografico degli EDL restituiti.
Attenzione: i campi di risposta da questo endpoint privato continuano con il prefisso edl_visit_*. Ha iniziato a utilizzare solo l'endpoint pubblico equivalente edl_maintenance_*.
Restituisce i dati sulle visite effettuate agli EDL nell'ambito geografico della chiave, inclusa l'osservazione registrata su ciascuna visita. L'ambito è definito automaticamente dal piano collegato alla chiave – comunale, regionale, statale o nazionale – e non è necessario informare il comune, lo stato o il paese nella richiesta.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Definisce l'ambito geografico delle visite ripetute.
Restituisce i dati sulle azioni (visite terapeutiche) eseguite in isolati nell'ambito geografico della chiave. L'ambito è definito automaticamente dal piano collegato alla chiave – comunale, regionale, statale o nazionale – e non è necessario informare il comune, lo stato o il paese nella richiesta.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Definisce l'ambito geografico delle azioni restituite.
Restituisce i dati dalle ovitrappole (punti di monitoraggio delle uova) nell'ambito geografico della chiave. L'ambito è definito automaticamente dal piano collegato alla chiave – comunale, regionale, statale o nazionale – e non è necessario informare il comune, lo stato o il paese nella richiesta.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Imposta l'ambito geografico degli ovitrap restituiti.
Restituisce gli immobili (punti strategici e immobili speciali) nell'ambito geografico della chiave. L'ambito è definito automaticamente dal piano collegato alla chiave — comunale, regionale, statale o nazionale — quindi non è necessario indicare comune, stato o paese nella richiesta.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Definisce l'ambito geografico dei punti restituiti.
Invia la lettura di una ovitrappola. È possibile inviare dati ad un ovitrap esistente oppure inviare i dati e contemporaneamente installare un nuovo ovitrap.
Per le spedizioni standard, dove non è necessario installare un nuovo ovitrap, inviare i seguenti campi (tutto obbligatorio) nel corpo della richiesta (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
}
Tabella con gli ID di ogni tipo di osservazione (counting_observation_id):
ID
Senso
1
Nessuna osservazione
2
Intervallo tra installazione e ritiro più lungo del previsto
3
Ovitrap o tavolozza mancante
4
Ovitrap o tavolozza rotta
5
Ovitrap o tavolozza rimossi
6
Ovitrappola secca
7
Casa chiusa
8
Ovitrappola riempita d'acqua
9
Ovitrap con poca acqua
10
Un'altra osservazione
Per installare una nuova trappola per uova accanto alla spedizione, obbligatorio i campi: ovitrap_lat, ovitrap_lng, ovitrap_group_id
Tabella con gli ID di ciascun tipo di ovitrap (ovitrap_type_id): inviarne 1 all'ovitrappola urbana e 2 all'ovitrappola rurale. Il campo è facoltativo e, quando non inviato, l'ovitrap viene installato come urbano:
ID
Senso
1
Ovitrappola urbana (standard)
2
Ovitrappola rurale
Risposte specifiche:
400 — quando uno qualsiasi dei campi obbligatori non viene inviato: 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 — quando il ovitrap_type_id inviato non è né 1 né 2.
400 — quando una qualsiasi delle date inviate non è nel formato YYYY-MM-DD. La risposta contiene l'elenco dei campi non validi in invalid_fields.
404 — C'è già un conteggio per questa ovitrappola, anno e settimana.
POST/api/postdeletecountingPrivato
Elimina la lettura
Rimuove la lettura da un'ovitrappola.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API. Definisce l'ambito della rimozione.
Richiedi esempio
curl -X POST \
"/it-ch/api/postdeletecounting?key=KEY"
Dati richiesti nel corpo della richiesta (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Risposte specifiche:
400 — Quando date non viene inviato.
400 — quando una qualsiasi delle date inviate non è nel formato YYYY-MM-DD. La risposta contiene l'elenco dei campi non validi in invalid_fields.
POST/api/postdeleteovitrapPrivato
Elimina l'ovitrappola
Rimuovi un'ovitrappola.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postdeleteovitrap?key=KEY"
Dati richiesti nel corpo della richiesta (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivato
Inserisci visita
Mudança de unidade em 23/09/2026: i campi action_deposit_<grupo>_larvicid passaram a ser em GRAMA, como pede a diretriz nacional. Antes eram miligrama. Se o seu sistema envia miligrama, divida por 1.000 antes de enviar — caso contrário a quantidade chega 1.000 vezes maior. O campo aceita decimais (0,5 g vai como 0.5).
Registra una visita/azione in un isolato. Per aggiungere la visita ad un isolato esistente inviare il campo block_id. Se non esiste, usa block_group_id — il sistema creerà automaticamente l'isolato. Questo endpoint consente solo l'inserimento di isolati che si trovano all'interno del comune del richiedente.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postaction?key=KEY"
Dati inviati form-data, x-www-form-urlencoded, JSON o parametri di query, utilizzando block_id:
400 — Quando date non viene inviato o quando uno dei campi numerici non è un numero valido.
400 — quando una qualsiasi delle date inviate non è nel formato YYYY-MM-DD. La risposta contiene l'elenco dei campi non validi in invalid_fields.
400 — Quando block_group_id non viene inviato durante la creazione di un nuovo isolato.
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 — Quando 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 — quando il block_id informato non appartiene al comune chiave.
409 — quando c'è già una visita per quel isolato, anno e settimana.
POST/api/postdeleteactionPrivato
Elimina visita
Rimuove una visita da un isolato.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postdeleteaction?key=KEY"
Dati richiesti nel corpo della richiesta (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Risposte specifiche:
400 — Quando date non viene inviato.
400 — quando una qualsiasi delle date inviate non è nel formato YYYY-MM-DD. La risposta contiene l'elenco dei campi non validi in invalid_fields.
POST/api/postdeleteblockPrivato
Elimina isolato
Rimuove un isolato.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postdeleteblock?key=KEY"
Dati richiesti nel corpo della richiesta (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlPrivato
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.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postedl?key=KEY"
Dati richiesti nel corpo della richiesta (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.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
Richiedi esempio
curl -X POST \
"/it-ch/api/postdeleteplace?key=KEY"
Dati richiesti nel corpo della richiesta (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/posteditactionPrivato
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
Nome
Tipo
Descrizione
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
action_land_<tipo>_out, _breedings, _treated
action_deposit_<a1|a2|b|c|d1|d2|e>_quantity, _eliminated, _treated, _larvicid (em grama, com decimais, desde 23/09/2026)
action_observation, action_responsable
Os totais da visita (visitados, pendentes, positivos, tratados e larvicida) e a média do quarteirão são recalculados.
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.