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.
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.
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 -d "key=KEY" \ /en-ca/api/postcounting
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
400 — when any of the mandatory fields is not sent: ovitrap_lat, ovitrap_lng, ovitrap_group_id
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 -d "key=KEY" \ /en-ca/api/postdeletecounting
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 -d "key=KEY" \ /en-ca/api/postdeleteovitrap
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 -d "key=KEY" \ /en-ca/api/postaction
Data sent in form or query parameters, using block_id: