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). Gestores (municipal para cima) geram a própria chave no botão Richiedi chiave API, logados na conta do município: a chave sai na hora, com o município e o cargo da conta, e fica visível no perfil. Se a chave vazar, troque-a na mesma tela (ou em “Trocar a chave”, no perfil): a nova vale na hora e a anterior deixa de funcionar. Agentes de endemias pedem ao gestor do município. Para outro nível de acesso, envie um e-mail para 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).
Desde 30/10/2026: valor de 500 ou mais em action_deposit_<grupo>_larvicid é lido como miligrama e gravado dividido por 1.000 (500 vira 0,5 g), nas inclusões e nas edições. A resposta não muda.
Registra uma visita/ação em um quarteirão. Há duas formas de dizer qual é o quarteirão:
block_id — o número interno do quarteirão no Conta Ovos, sempre inteiro (é o block_id devolvido por /api/getmunicipalityblocks). Se não existir ou for de outro município, a resposta é 403 e nada é cadastrado.
block_group_id — o código do quarteirão usado pelo município, em texto (por exemplo "A1"). Se já existir um quarteirão com esse código no município, a visita é gravada nele; os dados do quarteirão enviados junto são ignorados. Se não existir, o quarteirão é criado com esses dados e recebe a visita. Por isso é seguro reenviar um lote.
Se os dois forem enviados, vale o block_id. Não envie o código do município em block_id: ele é recusado com 400. Este endpoint só aceita quarteirões do município da chave.
Parametri
Nome
Tipo
Descrizione
key
string
La tua chiave API.
date
string
Data da visita, AAAA-MM-DD. A semana epidemiológica é calculada a partir dela e não pode ser futura. Obrigatório.
block_id
integer
Número interno do quarteirão no Conta Ovos. Obrigatório se block_group_id não for enviado.
block_group_id
string
Código do quarteirão no município (até 45 caracteres). Obrigatório se block_id não for enviado.
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 a data da visita é anterior a 1900 ou posterior a amanhã, ou quando a coordenada é exatamente zero. A mensagem diz qual valor foi recusado. Até 20/10/2026 esse caso respondia 500.
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.
400 — Quando block_id não é um número inteiro. O código usado pelo município vai em block_group_id.
403 — quando il block_id informado não existe ou não pertence ao município da chave.
409 — quando já existe uma visita para esse quarteirão nessa mesma data. Visitas ao mesmo quarteirão em dias diferentes, inclusive na mesma semana, são aceitas; o envio não precisa ser semanal.
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):
place_type_id é o tipo do imóvel; place_subtype é o subtipo, e precisa pertencer ao tipo enviado — um par que não combina é recusado com 400. Os mesmos códigos saem em place_type_id e place_subtype nas respostas de /api/getmunicipalityplaces e /api/getmunicipalityplacespublic.
place_type_id
place_subtype
Descrizione
1
Ponto Estratégico
1
1
Cemitério
1
2
Borracharia
1
3
Ferro-Velho
1
4
Depósito de Sucata
1
5
Depósito de Material de Construção
1
6
Garagem de ônibus ou outros veículos de grand
1
7
Residência de acumuladores de inservíveis
1
8
Outro
2
Imóvel especial
2
9
Rodoviária
2
10
Aeroporto
2
11
Escola
2
12
Unidade Básica de Saúde (UBS)
2
13
Universidade
2
14
Prédio de Administração Pública
2
15
Outro
POST/api/postdeleteplacePrivato
Deletar imóvel
Remove um imóvel do município da sua chave.
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.