Consulte e envie dados de ovitrampas, quarteirões e visitas de campo diretamente do seu sistema. Esta página documenta todos os endpoints públicos e privados disponíveis.
Esta API possui endpoints públicos e privados. A API pública devolve dados de latitude, longitude e quantidade de ovos de cada município participante ao longo do tempo, sem necessidade de autenticação. A API privada é recomendada apenas para aplicativos que trabalham em parceria com o Conta Ovos, pois ela expõe dados sensíveis e permite inserir, alterar e remover registros.
Autenticação e chaves
Para utilizar a API privada você precisará de uma chave de acesso (key). Para adquiri-la, envie um e-mail para contaovosdengue@gmail.com informando:
Por que você precisa de acesso à API;
Qual o nível de acesso necessário (municipal, regional, estadual ou país);
De qual região geográfica você faz parte.
A chave é composta por 45 letras aleatórias e deve ser enviada no parâmetro key de cada requisição privada. O escopo geográfico e o plano vinculados à chave (api_access_municipality_id, state_id, region_id, country_id, plan) definem automaticamente quais registros ela pode ler ou alterar — uma chave municipal, por exemplo, só consegue ler ou modificar dados do próprio município.
Onde enviar a chave: 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". Os demais campos do POST continuam indo no corpo da requisição.
Paginação: os parâmetros page aceitam no máximo 100 nos endpoints que suportam paginação. Valores inválidos ou ausentes assumem a página 1.
Códigos de resposta
Todos os endpoints seguem o mesmo padrão de status HTTP:
Código
Significado
200
Requisição processada com sucesso.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
O recurso informado não pertence ao escopo (município/estado/região) da chave utilizada.
404
Chave inválida (Wrong key) ou recurso não encontrado.
409
Já existe um registro para essa combinação de identificador, ano e semana.
500
Erro interno ao processar a requisição.
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.
Endpoints Públicos
GET/api/lastcountingpublicPúblico
Últimas contagens lançadas
Retorna as últimas contagens lançadas por localização (municipal, estadual ou país), com o número de ovos e os dados da ovitrampa.
Parâmetros
Nome
Tipo
Descrição
state
string
Código do estado. Exemplo: state=RJ.
municipality
string
Nome do município. Exemplo: municipality=Ponta Pora
country
string
Nome do país. Exemplo: country=Brasil. Se omitido, assume "Brasil".
page
int
Página de paginação (padrão 1, máximo 100).
id
int
Exibe apenas ocorrências a partir do id informado. Exemplo: id=7876.
date
date
Exibe ocorrências a partir da data de inclusão. Exemplo: date=2025-01-01.
date_collect
date
Exibe ocorrências a partir da data de coleta. Exemplo: date_collect=2024-12-12.
date_start
date
Data inicial para filtrar as contagens. Exemplo: date_start=2025-01-01.
date_end
date
Data final para filtrar as contagens. Exemplo: date_end=2025-12-31.
Obs.: se nenhum parâmetro de localização for enviado, o endpoint devolve as últimas contagens do Brasil.
Respostas específicas:
400 — quando alguma das datas enviadas não está no formato YYYY-MM-DD. A resposta traz a lista dos campos inválidos em invalid_fields.
Retorna os quarteirões (blocks) cadastrados no município — uma linha por quarteirão, com o polígono, os totais de imóveis por tipo e a média de ações.
Endpoint novo. Se você procura as visitas realizadas em quarteirões, use /api/getmunicipalityblocksvisitpublic. Por ser um endpoint público, a resposta não inclui o agente responsável pelo quarteirão nem identificadores de usuário/equipe.
Parâmetros
Nome
Tipo
Descrição
state
string
Código do estado. Exemplo: state=RJ.
municipality
string
Nome do município. Exemplo: municipality=Ponta Pora
country
string
Nome do país. Exemplo: country=Brasil. Se omitido, assume "Brasil".
Retorna os dados das manutenções realizadas nos EDLs, incluindo a observação registrada em cada manutenção.
Substitui/api/getmunicipalityedlvisitspublic. EDLs recebem manutenções, não visitas — os campos passaram de edl_visit_* para edl_maintenance_*. A URL antiga continua funcionando e continua devolvendo os nomes antigos, para não quebrar integrações em produção, mas está descontinuada.
Parâmetros
Nome
Tipo
Descrição
state
string
Código do estado. Exemplo: state=RJ.
municipality
string
Nome do município. Exemplo: municipality=Ponta Pora
country
string
Nome do país. Exemplo: country=Brasil. Se omitido, assume "Brasil".
Retorna os dados dos EDLs (pontos estratégicos visitados periodicamente pelos agentes) dentro do escopo geográfico da chave. O escopo é definido automaticamente pelo plano vinculado à chave — municipal, regional, estadual ou país — não sendo necessário informar município, estado ou país na requisição.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo geográfico dos EDLs retornados.
Atenção: os campos da resposta deste endpoint privado continuam com o prefixo edl_visit_*. Apenas o endpoint público equivalente passou a usar edl_maintenance_*.
Retorna os dados das visitas realizadas aos EDLs dentro do escopo geográfico da chave, incluindo a observação registrada em cada visita. O escopo é definido automaticamente pelo plano vinculado à chave — municipal, regional, estadual ou país — não sendo necessário informar município, estado ou país na requisição.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo geográfico das visitas retornadas.
Retorna os dados das ações (visitas de tratamento) realizadas em quarteirões dentro do escopo geográfico da chave. O escopo é definido automaticamente pelo plano vinculado à chave — municipal, regional, estadual ou país — não sendo necessário informar município, estado ou país na requisição.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo geográfico das ações retornadas.
Retorna os dados das ovitrampas (pontos de monitoramento de ovos) dentro do escopo geográfico da chave. O escopo é definido automaticamente pelo plano vinculado à chave — municipal, regional, estadual ou país — não sendo necessário informar município, estado ou país na requisição.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo geográfico das ovitrampas retornadas.
Retorna os imóveis (pontos estratégicos e imóveis especiais) dentro do escopo geográfico da chave. O escopo é definido automaticamente pelo plano vinculado à chave — municipal, regional, estadual ou país — não sendo necessário informar município, estado ou país na requisição.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo geográfico dos pontos retornados.
Envia a leitura de uma ovitrampa. É possível enviar dados para uma ovitrampa já existente ou enviar os dados e instalar uma nova ovitrampa ao mesmo tempo.
Tabela com os IDs de cada tipo de ovitrampa (ovitrap_type_id): envie 1 para ovitrampa urbana e 2 para ovitrampa rural. O campo é opcional e, quando não enviado, a ovitrampa é instalada como urbana:
ID
Significado
1
Ovitrampa urbana (padrão)
2
Ovitrampa rural
Respostas específicas:
400 — quando algum dos campos obrigatórios não é enviado: 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 o ovitrap_type_id enviado não é 1 nem 2.
400 — quando alguma das datas enviadas não está no formato YYYY-MM-DD. A resposta traz a lista dos campos inválidos em invalid_fields.
404 — já existe uma contagem para essa ovitrampa, ano e semana.
POST/api/postdeletecountingPrivado
Deletar leitura
Remove a leitura de uma ovitrampa.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API. Define o escopo da remoção.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postdeletecounting?key=KEY"
Dados necessários no corpo da requisição (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Respostas específicas:
400 — quando date não é enviado.
400 — quando alguma das datas enviadas não está no formato YYYY-MM-DD. A resposta traz a lista dos campos inválidos em invalid_fields.
POST/api/postdeleteovitrapPrivado
Deletar ovitrampa
Remove uma ovitrampa.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postdeleteovitrap?key=KEY"
Dados necessários no corpo da requisição (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivado
Inserir visita
Mudança de unidade em 23/09/2026: os campos 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 uma visita/ação em um quarteirão. Para adicionar a visita a um quarteirão já existente, envie o campo block_id. Caso ele não exista, use block_group_id — o sistema criará o quarteirão automaticamente. Este endpoint só permite a inserção de quarteirões que estejam dentro do município do solicitante.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postaction?key=KEY"
Dados enviados em form-data, x-www-form-urlencoded, JSON ou query parameters, usando block_id:
400 — quando date não é enviado ou quando um dos campos numéricos não é um número válido.
400 — quando alguma das datas enviadas não está no formato YYYY-MM-DD. A resposta traz a lista dos campos inválidos em invalid_fields.
400 — quando block_group_id não é enviado ao criar um novo quarteirão.
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 o block_id informado não pertence ao município da chave.
409 — quando já existe uma visita para esse quarteirão, ano e semana.
POST/api/postdeleteactionPrivado
Deletar visita
Remove uma visita de um quarteirão.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postdeleteaction?key=KEY"
Dados necessários no corpo da requisição (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Respostas específicas:
400 — quando date não é enviado.
400 — quando alguma das datas enviadas não está no formato YYYY-MM-DD. A resposta traz a lista dos campos inválidos em invalid_fields.
POST/api/postdeleteblockPrivado
Deletar quarteirão
Remove um quarteirão.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postdeleteblock?key=KEY"
Dados necessários no corpo da requisição (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlPrivado
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.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postedl?key=KEY"
Dados necessários no corpo da requisição (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.
Parâmetros
Nome
Tipo
Descrição
key
string
Sua chave de API.
Exemplo de requisição
curl -X POST \
"/pt-pt/api/postdeleteplace?key=KEY"
Dados necessários no corpo da requisição (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/posteditactionPrivado
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
Nome
Tipo
Descrição
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.