This API has endpoints public and private. The public API returns data on latitude, longitude and number of eggs for each participating municipality over time, without the need for authentication. The private API is only recommended for applications that work in partnership with Conta Ovos, as it exposes sensitive data and allows you to insert, change and remove records.
Authentication and keys
To use the private API you will need an access key (key). To purchase it, send an email to contaovosdengue@gmail.com stating:
Why do you need API access;
What level of access is required (municipal, regional, state or country);
Which geographic region are you part of?
The key is made up of 45 random letters and must be sent in the parameter key of each private request. The geographic scope and plan linked to the key (api_access_municipality_id, state_id, region_id, country_id, plan) automatically define which records it can read or change — a municipal key, for example, can only read or modify data from the municipality itself.
Where to send the key: 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". The other POST fields continue to appear in the request body.
Pagination: the parameters page accept a maximum of 100 on endpoints that support paging. Invalid or missing values take page 1.
Response Codes
All endpoints follow the same HTTP status pattern:
Code
Meaning
200
Request processed successfully.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
The resource informed does not belong to the scope (city/state/region) of the key used.
404
Invalid key (Wrong key) or resource not found.
409
A record already exists for this identifier, year, and week combination.
500
Internal error processing the request.
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.
Public Endpoints
GET/api/lastcountingpublicPublic
Latest released counts
Returns the latest counts released by location (city, state or country), with the number of eggs and ovitrap data.
Parameters
Name
Type
Description
state
string
State code. Example: state=RJ.
municipality
string
Name of the municipality. Example: municipality=Ponta Pora
country
string
Country name. Example: country=Brasil. If omitted, assumes "Brazil".
page
int
Pagination page (default 1, maximum 100).
id
int
Displays only occurrences from the given id. Example: id=7876.
date
date
Displays occurrences from the date of inclusion. Example: date=2025-01-01.
date_collect
date
Displays occurrences from the collection date onwards. Example: date_collect=2024-12-12.
date_start
date
Start date to filter the counts. Example: date_start=2025-01-01.
date_end
date
End date to filter counts. Example: date_end=2025-12-31.
Note: If no location parameters are sent, the endpoint returns the latest counts from Brazil.
Specific answers:
400 — when any of the dates sent are not in the format YYYY-MM-DD. The response brings the list of invalid fields in invalid_fields.
Returns the blocks registered in the municipality — one line per block, with the polygon, total properties by type and average number of shares.
New endpoint. If you are looking for visits carried out in blocks, use /api/getmunicipalityblocksvisitpublic. As it is a public endpoint, the response does not include the agent responsible for the block or user/team identifiers.
Parameters
Name
Type
Description
state
string
State code. Example: state=RJ.
municipality
string
Name of the municipality. Example: municipality=Ponta Pora
country
string
Country name. Example: country=Brasil. If omitted, assumes "Brazil".
Returns data on maintenance performed on the EDLs, including the observation recorded during each maintenance.
Replaces/api/getmunicipalityedlvisitspublic. EDLs receive maintenance, not visits — the fields have gone from edl_visit_* to edl_maintenance_*. The old URL continues to work and continues to return the old names, so as not to break integrations in production, but it is discontinued.
Parameters
Name
Type
Description
state
string
State code. Example: state=RJ.
municipality
string
Name of the municipality. Example: municipality=Ponta Pora
country
string
Country name. Example: country=Brasil. If omitted, assumes "Brazil".
Returns data from EDLs (strategic points periodically visited by agents) within the geographic scope of the key. The scope is automatically defined by the plan linked to the key — municipal, regional, state or country — and it is not necessary to inform the municipality, state or country in the request.
Parameters
Name
Type
Description
key
string
Your API key. Defines the geographic scope of the returned EDLs.
Attention: the response fields from this private endpoint continue with the prefix edl_visit_*. Only the equivalent public endpoint started using edl_maintenance_*.
Returns data on visits made to EDLs within the geographic scope of the key, including the observation recorded on each visit. The scope is automatically defined by the plan linked to the key — municipal, regional, state or country — and it is not necessary to inform the municipality, state or country in the request.
Parameters
Name
Type
Description
key
string
Your API key. Defines the geographic scope of returned visits.
Returns data on actions (treatment visits) carried out in blocks within the geographic scope of the key. The scope is automatically defined by the plan linked to the key — municipal, regional, state or country — and it is not necessary to inform the municipality, state or country in the request.
Parameters
Name
Type
Description
key
string
Your API key. Defines the geographic scope of the returned actions.
Returns data from ovitraps (egg monitoring points) within the geographic scope of the key. The scope is automatically defined by the plan linked to the key — municipal, regional, state or country — and it is not necessary to inform the municipality, state or country in the request.
Parameters
Name
Type
Description
key
string
Your API key. Sets the geographic scope of the returned ovitraps.
Returns the properties (strategic points and special premises) within the key's geographic scope. The scope is set automatically by the plan linked to the key — municipal, regional, state or country — so there is no need to inform municipality, state or country in the request.
Parameters
Name
Type
Description
key
string
Your API key. Defines the geographic scope of the returned points.
For standard shipping, where it is not necessary to install a new ovitrap, send the following fields (all mandatory) in the body of the request (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
}
Table with the IDs of each type of observation (counting_observation_id):
ID
Meaning
1
No observations
2
Interval between installation and collection longer than expected
3
Ovitrap or missing palette
4
Ovitrap or broken palette
5
Ovitrap or palette removed
6
Dry ovitrap
7
Closed house
8
Ovitrap filled with water
9
Ovitrap with little water
10
Another observation
To install a new ovitrap next to the shipment, mandatory the fields: ovitrap_lat, ovitrap_lng, ovitrap_group_id
Table with the IDs of each type of ovitrap (ovitrap_type_id): send 1 to urban ovitrap and 2 to rural ovitrap. The field is optional and, when not sent, the ovitrap is installed as urban:
ID
Meaning
1
Urban ovitrap (standard)
2
Rural ovitrap
Specific answers:
400 — when any of the mandatory fields is not sent: 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 — when the ovitrap_type_id sent is neither 1 nor 2.
400 — when any of the dates sent are not in the format YYYY-MM-DD. The response brings the list of invalid fields in invalid_fields.
404 — There is already a count for this ovitrap, year and week.
POST/api/postdeletecountingPrivate
Delete reading
Removes reading from an ovitrap.
Parameters
Name
Type
Description
key
string
Your API key. Defines the scope of removal.
Request example
curl -X POST \
"/en-ie/api/postdeletecounting?key=KEY"
Data required in the body of the request (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Specific answers:
400 — when date is not sent.
400 — when any of the dates sent are not in the format YYYY-MM-DD. The response brings the list of invalid fields in invalid_fields.
POST/api/postdeleteovitrapPrivate
Delete ovitrap
Remove an ovitrap.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postdeleteovitrap?key=KEY"
Data required in the body of the request (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivate
Insert visit
Register a visit/action in a block. To add the visit to an existing block, send the field block_id. If it does not exist, use block_group_id — the system will create the block automatically. This endpoint only allows the insertion of blocks that are within the applicant's municipality.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postaction?key=KEY"
Data sent in form-data, x-www-form-urlencoded, JSON or query parameters, using block_id:
400 — when date is not sent or when one of the numeric fields is not a valid number.
400 — when any of the dates sent are not in the format YYYY-MM-DD. The response brings the list of invalid fields in invalid_fields.
400 — when block_group_id is not sent when creating a new block.
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 — when 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 — when the block_id informed does not belong to the key municipality.
409 — when there is already a visit for that block, year and week.
POST/api/postdeleteactionPrivate
Delete visit
Removes a visit from one block.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postdeleteaction?key=KEY"
Data required in the body of the request (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Specific answers:
400 — when date is not sent.
400 — when any of the dates sent are not in the format YYYY-MM-DD. The response brings the list of invalid fields in invalid_fields.
POST/api/postdeleteblockPrivate
Delete block
Removes a block.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postdeleteblock?key=KEY"
Data required in the body of the request (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlPrivate
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.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postedl?key=KEY"
Data required in the body of the request (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.
Parameters
Name
Type
Description
key
string
Your API key.
Request example
curl -X POST \
"/en-ie/api/postdeleteplace?key=KEY"
Data required in the body of the request (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/posteditactionPrivate
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
Name
Type
Description
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.