Consulta y envía datos de ovitrampas, manzanas y visitas de campo directamente desde tu sistema. Esta página documenta todos los puntos finales públicos y privados disponibles.
Esta API tiene puntos finales público y privado. La API pública devuelve datos sobre latitud, longitud y número de huevos de cada municipio participante a lo largo del tiempo, sin necesidad de autenticación. La API privada solo se recomienda para aplicaciones que funcionan en asociación con Conta Ovos, ya que expone datos confidenciales y le permite insertar, cambiar y eliminar registros.
Autenticación y claves
Para utilizar la API privada necesitarás una clave de acceso. (key). Para adquirirlo envía un email a contaovosdengue@gmail.com indicando:
¿Por qué necesita acceso API?
Qué nivel de acceso se requiere (municipal, regional, estatal o nacional);
¿De qué región geográfica eres parte?
La clave se compone de 45 letras al azar y debe ser enviado en el parámetro key de cada solicitud privada. El alcance geográfico y el plan vinculado a la clave. (api_access_municipality_id, state_id, region_id, country_id, plan) define automáticamente qué registros puede leer o cambiar; una clave municipal, por ejemplo, solo puede leer o modificar datos del propio municipio.
Dónde enviar la clave: 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". Los demás campos POST siguen apareciendo en el cuerpo de la solicitud.
Paginación: los parametros page acepte un máximo de 100 en puntos finales que admitan paginación. Los valores no válidos o faltantes toman la página 1.
Códigos de respuesta
Todos los puntos finales siguen el mismo patrón de estado HTTP:
Código
Significado
200
Solicitud procesada exitosamente.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
El recurso informado no pertenece al alcance (ciudad/estado/región) de la clave utilizada.
404
Clave no válida (Wrong key) o recurso no encontrado.
409
Ya existe un registro para esta combinación de identificador, año y semana.
500
Error interno al procesar la solicitud.
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.
Puntos finales públicos
GET/api/lastcountingpublicPúblico
Últimos recuentos publicados
Devuelve los últimos recuentos publicados por ubicación (ciudad, estado o país), con el número de huevos y datos de ovitrampas.
Parámetros
Nombre
Tipo
Descripción
state
string
Código de estado. Ejemplo: state=RJ.
municipality
string
Nombre del municipio. Ejemplo: municipality=Ponta Pora
country
string
Nombre del país. Ejemplo: country=Brasil. Si se omite, se supone "Brasil".
page
int
Página de paginación (por defecto 1, máximo 100).
id
int
Muestra solo ocurrencias de la identificación dada. Ejemplo: id=7876.
date
date
Muestra ocurrencias desde la fecha de inclusión. Ejemplo: date=2025-01-01.
date_collect
date
Muestra ocurrencias desde la fecha de recolección en adelante. Ejemplo: date_collect=2024-12-12.
date_start
date
Fecha de inicio para filtrar los conteos. Ejemplo: date_start=2025-01-01.
date_end
date
Fecha de finalización para filtrar recuentos. Ejemplo: date_end=2025-12-31.
Nota: Si no se envían parámetros de ubicación, el punto final devuelve los recuentos más recientes de Brasil.
Respuestas específicas:
400 — cuando alguna de las fechas enviadas no esté en el formato YYYY-MM-DD. La respuesta trae la lista de campos no válidos en invalid_fields.
Devuelve las manzanas registradas en el municipio, una línea por manzana, con el polígono, el total de propiedades por tipo y el número medio de acciones.
Nuevo punto final. Si buscas visitas realizadas por manzanas, utiliza /api/getmunicipalityblocksvisitpublic. Al ser un endpoint público, la respuesta no incluye el agente responsable de la manzana ni los identificadores de usuario/equipo.
Parámetros
Nombre
Tipo
Descripción
state
string
Código de estado. Ejemplo: state=RJ.
municipality
string
Nombre del municipio. Ejemplo: municipality=Ponta Pora
country
string
Nombre del país. Ejemplo: country=Brasil. Si se omite, se supone "Brasil".
Devuelve datos sobre el mantenimiento realizado en las EDL, incluida la observación registrada durante cada mantenimiento.
Reemplaza/api/getmunicipalityedlvisitspublic. Las EDL reciben mantenimiento, no visitas: los campos han pasado de edl_visit_* a edl_maintenance_*. La antigua URL sigue funcionando y sigue devolviendo los nombres antiguos, para no interrumpir las integraciones en producción, pero está descontinuada.
Parámetros
Nombre
Tipo
Descripción
state
string
Código de estado. Ejemplo: state=RJ.
municipality
string
Nombre del municipio. Ejemplo: municipality=Ponta Pora
country
string
Nombre del país. Ejemplo: country=Brasil. Si se omite, se supone "Brasil".
Devuelve datos de EDL (puntos estratégicos visitados periódicamente por los agentes) dentro del alcance geográfico de la clave. El alcance lo define automáticamente el plan vinculado a la clave (municipal, regional, estatal o país) y no es necesario informar el municipio, estado o país en la solicitud.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Define el alcance geográfico de las EDL devueltas.
Atención: los campos de respuesta de este punto final privado continúan con el prefijo edl_visit_*. Solo el punto final público equivalente comenzó a utilizar edl_maintenance_*.
Devuelve datos sobre las visitas realizadas a las EDL dentro del alcance geográfico de la clave, incluida la observación registrada en cada visita. El alcance lo define automáticamente el plan vinculado a la clave (municipal, regional, estatal o país) y no es necesario informar el municipio, estado o país en la solicitud.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Define el alcance geográfico de las visitas regresadas.
Devuelve datos sobre acciones (visitas de tratamiento) realizadas en manzanas dentro del alcance geográfico de la clave. El alcance lo define automáticamente el plan vinculado a la clave (municipal, regional, estatal o país) y no es necesario informar el municipio, estado o país en la solicitud.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Define el alcance geográfico de las acciones devueltas.
Devuelve datos de ovitrampas (puntos de monitoreo de huevos) dentro del alcance geográfico de la clave. El alcance lo define automáticamente el plan vinculado a la clave (municipal, regional, estatal o país) y no es necesario informar el municipio, estado o país en la solicitud.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Establece el alcance geográfico de las ovitrampas devueltas.
Devuelve los inmuebles (puntos estratégicos e inmuebles especiales) dentro del alcance geográfico de la clave. El alcance se define automáticamente por el plan vinculado a la clave — municipal, regional, estatal o país — por lo que no es necesario informar municipio, estado o país en la solicitud.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Define el alcance geográfico de los puntos devueltos.
Envía la lectura de una ovitrampa. Es posible enviar datos a una ovitrampa existente o enviar los datos e instalar una nueva ovitrampa al mismo tiempo.
Para envío estándar, donde no es necesario instalar una ovitrampa nueva, envíe los siguientes campos (todo obligatorio) en el cuerpo de la solicitud (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
}
Tabla con los ID de cada tipo de observación (counting_observation_id):
ID
Significado
1
Sin observaciones
2
Intervalo entre instalación y recogida más largo de lo esperado
3
Ovitrampa o paleta faltante
4
Ovitrampa o paleta rota
5
Ovitrampa o paleta retirada
6
Ovitrampa seca
7
casa cerrada
8
Ovitrampa llena de agua
9
Ovitrampa con poca agua
10
Otra observación
Para instalar una nueva ovitrampa junto al envío, obligatorio los campos: ovitrap_lat, ovitrap_lng, ovitrap_group_id
Tabla con los ID de cada tipo de ovitrampa (ovitrap_type_id): enviar 1 a ovitrampa urbana y 2 a ovitrampa rural. El campo es opcional y, al no enviarse, la ovitrampa se instala como urbana:
ID
Significado
1
Ovitrampa urbana (estándar)
2
Ovitrampa rural
Respuestas específicas:
400 — cuando no se envía alguno de los campos obligatorios: 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 — cuando el ovitrap_type_id enviado no es ni 1 ni 2.
400 — cuando alguna de las fechas enviadas no esté en el formato YYYY-MM-DD. La respuesta trae la lista de campos no válidos en invalid_fields.
404 — Ya hay un recuento para esta ovitrampa, año y semana.
POST/api/postdeletecountingPrivado
Eliminar lectura
Elimina la lectura de una ovitrampa.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API. Define el alcance de la eliminación.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postdeletecounting?key=KEY"
Datos requeridos en el cuerpo de la solicitud (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Respuestas específicas:
400 — cuando date no se envía.
400 — cuando alguna de las fechas enviadas no esté en el formato YYYY-MM-DD. La respuesta trae la lista de campos no válidos en invalid_fields.
POST/api/postdeleteovitrapPrivado
Eliminar ovitrampa
Retire una ovitrampa.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postdeleteovitrap?key=KEY"
Datos requeridos en el cuerpo de la solicitud (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivado
Insertar visita
Registrar una visita/acción en una manzana. Para agregar la visita a una manzana existente, envíe el campo block_id. Si no existe, utilice block_group_id — el sistema creará la manzana automáticamente. Este punto final solo permite la inserción de manzanas que se encuentren dentro del municipio del solicitante.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postaction?key=KEY"
Datos enviados en form-data, x-www-form-urlencoded, JSON o parámetros de consulta, utilizando block_id:
400 — cuando date no se envía o cuando uno de los campos numéricos no es un número válido.
400 — cuando alguna de las fechas enviadas no esté en el formato YYYY-MM-DD. La respuesta trae la lista de campos no válidos en invalid_fields.
400 — cuando block_group_id no se envía al crear un nueva manzana.
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 — cuando 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 — cuando el block_id informado no pertenece al municipio clave.
409 — cuando ya hay visita para ese manzana, año y semana.
POST/api/postdeleteactionPrivado
Eliminar visita
Elimina una visita de una manzana.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postdeleteaction?key=KEY"
Datos requeridos en el cuerpo de la solicitud (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Respuestas específicas:
400 — cuando date no se envía.
400 — cuando alguna de las fechas enviadas no esté en el formato YYYY-MM-DD. La respuesta trae la lista de campos no válidos en invalid_fields.
POST/api/postdeleteblockPrivado
Eliminar manzana
Elimina una manzana.
Parámetros
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postdeleteblock?key=KEY"
Datos requeridos en el cuerpo de la solicitud (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
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postedl?key=KEY"
Datos requeridos en el cuerpo de la solicitud (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
Nombre
Tipo
Descripción
key
string
Su clave API.
Ejemplo de solicitud
curl -X POST \
"/es-pr/api/postdeleteplace?key=KEY"
Datos requeridos en el cuerpo de la solicitud (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
Nombre
Tipo
Descripción
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.