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: a key is always read from the URL query string (?key=SUA_CHAVE), including POST endpoints. Sending it only in the body of the form results in 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
Mandatory parameter missing or in invalid format.
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.
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.
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".
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.
Parameters
Name
Type
Description
key
string
Sua chave de API. Define o escopo geográfico dos EDLs retornados.
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.
Parameters
Name
Type
Description
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.
Parameters
Name
Type
Description
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.
Parameters
Name
Type
Description
key
string
Sua chave de API. Define o escopo geográfico das ovitrampas retornadas.
Retorna os pontos estratégicos (locais de uso do solo com risco de proliferação) 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.
Parameters
Name
Type
Description
key
string
Sua chave de API. Define o escopo geográfico dos pontos retornados.
Sends the reading of an ovitrap. It is possible to send data to an existing ovitrap or send the data and install a new ovitrap at the same time.
Parameters
Name
Type
Description
key
string
Your API key. Defines the scope of the submission.
Request example
curl -X POST \
"/en-ie/api/postcounting?key=KEY"
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
400 — when the ovitrap_type_id sent is neither 1 nor 2.
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):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
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):
{
"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 or query parameters, using block_id: