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.
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.
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-au/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, date
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-au/api/postdeletecounting?key=KEY"
Data required in the body of the request (form):
{
"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-au/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-au/api/postaction?key=KEY"
Data sent in form or query parameters, using block_id: