Query Mosqlimate dengue, zika, and chikungunya data, models, and forecasts, and validate or upload predictions with mosqlient.
Mosqlimate
Use this skill for Brazilian arbovirus data and forecasting work through the
Mosqlimate platform. It wraps the public
mosqlient Python library and keeps write operations behind an explicit
confirmation.
When to use it
Use this skill when the user asks for:
- dengue, zika, or chikungunya cases in a Brazilian state or municipality;
- climate, mosquito (ContaOvos), vegetation, or Episcanner data;
- Mosqlimate model or prediction searches;
- validation or upload of a forecast to the Mosqlimate registry.
Do not use it to invent epidemiological values, to guess IBGE geocodes, or for countries other than Brazil.
Setup
Run the helper with uv; it installs mosqlient in an isolated environment:
uv run scripts/mosqlimate.py --help
From the repository root the path is:
uv run skills/mosqlimate/scripts/mosqlimate.py --help
The base install covers data access and the registry. Forecasting and scoring
helpers need the mosqlient[analyze] extra and are not part of this skill. The
first uv run can take several minutes because mosqlient has a large
scientific dependency tree; later runs reuse the cache.
Authentication
Set the API key in MOSQLIMATE_API_KEY or pass --api-key. The format is
username:uuid.
export MOSQLIMATE_API_KEY="your-user:00000000-0000-4000-8000-000000000000"
Never print, log, or commit the key. If no key is provided, mosqlient may
create a temporary demo user with limited access and rate limits.
Commands
| Command | Purpose |
|---|---|
infodengue | Fetch InfoDengue cases. |
climate | Fetch daily climate data; --weekly for weekly data. |
episcanner | Fetch Episcanner data. |
mosquito | Fetch ContaOvos mosquito data. |
vegetation | Fetch vegetation index data. |
models | List or search registered models. |
predictions | List or search predictions. |
validate-prediction | Validate a forecast without uploading. |
upload-prediction | Validate and upload a forecast. |
All read commands accept --output csv|json and --out FILE. Disease flags
accept names or ICD-10 codes. State filters accept a UF abbreviation or an IBGE
state code, and --adm-1 is an alias for --uf.
API endpoints
Base URL: https://api.mosqlimate.org/api/
The helper uses GET for datastore and registry reads and POST for prediction
uploads. Build full URLs by appending the partial paths below to the base URL.
The API also exposes DELETE and PATCH operations that this helper does not
call.
See API endpoints and output schemas for every method, partial URL, response envelope, and field schema.
Examples
Dengue cases for Rio de Janeiro city:
uv run scripts/mosqlimate.py infodengue \
--disease dengue \
--start 2023-01-01 \
--end 2023-12-31 \
--geocode 3304557 \
--output csv --out dengue_rj.csv
All municipalities in Parana state (UF or state code):
uv run scripts/mosqlimate.py infodengue \
--disease A90 --start 2023-01-01 --end 2023-06-30 --adm-1 41
Daily climate for Curitiba:
uv run scripts/mosqlimate.py climate \
--start 2023-01-01 --end 2023-01-31 --geocode 4106902
Weekly climate for a macro health region:
uv run scripts/mosqlimate.py climate --weekly \
--start 202501 --end 202510 --macro-health-code 1101
2024 IMDC dengue models:
uv run scripts/mosqlimate.py models --disease A90 --imdc-year 2024
Predictions for a model, filtered by state and municipality:
uv run scripts/mosqlimate.py predictions \
--model-name forecast_models_dengue \
--adm-1 RJ --adm-2 3304557
One prediction and its data:
uv run scripts/mosqlimate.py predictions --id 300 --include-data
Validate a forecast:
uv run scripts/mosqlimate.py validate-prediction \
--prediction forecast.json \
--repository owner/repo \
--disease A90 \
--description "Out-of-sample forecast for Rio de Janeiro" \
--commit 0123456789abcdef0123456789abcdef01234567 \
--adm-level 2 --adm-1 33 --adm-2 3304557
Upload an unpublished forecast:
uv run scripts/mosqlimate.py upload-prediction \
--prediction forecast.json \
--repository owner/repo \
--disease A90 \
--description "Out-of-sample forecast for Rio de Janeiro" \
--commit 0123456789abcdef0123456789abcdef01234567 \
--adm-level 2 --adm-1 33 --adm-2 3304557 \
--dry-run # remove this line to upload
--yes
--published is required to make an uploaded prediction public. Without it the
prediction is uploaded as unpublished.
Prediction file format
JSON files must contain a list of rows, or an object with a prediction or
data list. CSV files must use the same column names. Every row must contain:
date, lower_95, lower_90, lower_80, lower_50, pred,
upper_50, upper_80, upper_90, upper_95
Dates use YYYY-MM-DD. For weekly models, each date must be the Sunday that
starts the CDC epidemiological week. IMDC predictions must cover every week in
the required range without gaps. Bounds must be non-negative and ordered:
lower_95 <= lower_90 <= lower_80 <= lower_50 <= pred <= upper_50 <= upper_80 <= upper_90 <= upper_95.
Safety rules
- Never invent case counts, dates, geocodes, or model identifiers. Fetch them and report the parameters used.
- Call
validate-predictionor useupload-prediction --dry-runbefore any upload. - Do not run
upload-predictionwithout explicit user confirmation. The script refuses to write without--yes. - Do not add
--publishedunless the user explicitly asks to publish. - Do not modify or delete existing predictions from this skill.
- Treat HTTP 422 as a validation problem and show the API message. Back off on HTTP 429 and surface the rate limit.
- Do not pass secrets on the command line in shared shells; prefer the environment variable.
Conventions
- Disease flags accept either names (
dengue,zika,chikungunya,chik) or ICD-10 codes (A90,A92.5,A92.0). The script normalizes them for the target API. - State filters accept a UF abbreviation (
RJ) or an IBGE state code (33). Use--adm-1as an alias for--uf. - Administrative levels: 0 country, 1 state, 2 municipality, 3 sub-municipality.
- Municipality geocodes are 7-digit IBGE codes.
References
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 3w ago
- Current version
- v1.0.1
- License
- MIT-0
