Package {rmet}

Type: Package
Title: Download and Read Brazilian Meteorological Data from INMET
Version: 0.3.0
Description: Automates the download and processing of historical hourly weather data from automatic stations of the Brazilian National Institute of Meteorology (INMET). It provides the official station catalogue with an offline snapshot and nearest-station search, validated and resumable downloads that detect updated archives, and a fast parser for the formatting and encoding inconsistencies of raw CSV files across years. It returns analysis-ready data frames with standardized column names and UTC timestamps. It flags implausible values with transparent quality-control checks, reports data completeness, and builds daily summaries in each station's local time with explicit rules for incomplete days. Data are retrieved from https://portal.inmet.gov.br/dadoshistoricos and https://apitempo.inmet.gov.br/estacoes/T.
Depends: R (≥ 4.0.0)
Encoding: UTF-8
LazyData: true
Language: en-US
License: GPL (≥ 3)
URL: https://github.com/rodrigosqrt3/rmet
BugReports: https://github.com/rodrigosqrt3/rmet/issues
RoxygenNote: 7.3.3
Imports: curl (≥ 4.0), jsonlite
Suggests: spelling, testthat (≥ 3.0.0), knitr, rmarkdown, sf
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-10-19 19:55:25 UTC; rodri
Author: Rodrigo Fonseca Villa ORCID iD [aut, cre]
Maintainer: Rodrigo Fonseca Villa <rodrigo03.villa@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-20 13:30:02 UTC

rmet: Access Historical Weather Data from INMET

Description

Tools to find stations and to download, cache, parse, and summarise historical hourly weather data from Brazil's National Institute of Meteorology (INMET).

Main functions

Author(s)

Maintainer: Rodrigo Fonseca Villa rodrigo03.villa@gmail.com (ORCID)

See Also

Useful links:

Convert stations or data to spatial points

Description

Turns any data frame with latitude and longitude columns, such as the output of inmet_stations(), inmet_nearest(), inmet_read() or inmet_daily(), into an sf object for mapping and spatial joins. Requires the sf package.

Usage

inmet_as_sf(x, remove = FALSE)

Arguments

x

A data frame with numeric latitude and longitude columns.

remove

Drop the coordinate columns from the attributes.

Value

An sf data frame with point geometries in WGS 84 (EPSG:4326). Rows with missing coordinates are dropped with a warning.

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  rs <- inmet_stations(state = "RS", source = "bundled")
  points <- inmet_as_sf(rs)
  plot(points["elevation"])
}

Clear the rmet cache

Description

Clear the rmet cache

Usage

inmet_cache_clear(
  years = NULL,
  dest_dir = tools::R_user_dir("rmet", "cache"),
  ask = interactive(),
  catalog = FALSE
)

Arguments

years

Integer years to remove, or NULL for every archive.

dest_dir

Cache directory.

ask

Ask for confirmation before deleting.

catalog

Also remove the cached official station catalogue.

Value

Invisible NULL.

Examples

inmet_cache_clear(dest_dir = file.path(tempdir(), "rmet"), ask = FALSE)

Inspect downloaded INMET archives

Description

Inspect downloaded INMET archives

Usage

inmet_cache_status(dest_dir = tools::R_user_dir("rmet", "cache"))

Arguments

dest_dir

Cache directory used by inmet_download().

Value

A data frame with one row per cached year: archive path, size in MB, whether the ZIP is valid, whether a partial download exists, and when the archive was downloaded (UTC, if recorded). Returned invisibly when the cache is empty.

Examples

inmet_cache_status(dest_dir = file.path(tempdir(), "rmet"))

Data completeness by station and period

Description

Summarises how complete hourly data are, to choose stations and periods before an analysis.

Usage

inmet_completeness(x, by = c("month", "year"), variables = NULL)

Arguments

x

A data frame as returned by inmet_read().

by

Period length: "month" (default) or "year". Periods are UTC calendar months or years.

variables

Measurement columns to assess. Defaults to all numeric measurement columns.

Details

The expected number of hours is the full length of the period, so periods only partly covered by x (for example, the current month, or a period cut by start_date in inmet_read()) show low completeness. Global radiation is missing at night at most stations, so its completeness is usually around 50 %.

Value

A data frame with one row per station and period: station_code, period ("YYYY-MM" or "YYYY"), hours_expected (hours in the period), hours_present (hourly records in x), and, for each variable, the percentage of the expected hours with a valid value. Values flagged by inmet_qc() do not count as valid.

See Also

inmet_qc(), inmet_daily()

Examples

inmet_completeness(rmet_example, variables = c("temp_dry_c", "precip_mm"))

Daily summaries of hourly INMET data

Description

Aggregates the hourly output of inmet_read() or inmet_get() into one row per station and local calendar day, handling the conventions of the source data correctly.

Usage

inmet_daily(x, tz = "auto", min_hours = 20L)

Arguments

x

A data frame as returned by inmet_read(), with at least a datetime column.

tz

Time zone defining the calendar day. "auto" (default) uses each station's own local time, from its state and longitude (see inmet_timezone()); this needs the state column. Otherwise, any name in OlsonNames(), for example "America/Sao_Paulo", or "UTC" for UTC days.

min_hours

Minimum number of non-missing hourly values a variable needs on a given day; otherwise its daily value is NA. Local days have 24 hours (23 or 25 on daylight-saving transitions, which Brazil observed until 2019).

Details

INMET stamps every record with the end of the hour it describes, in UTC. A record is therefore assigned to the local day containing the middle of its hour (datetime minus 30 minutes): the value stamped 03:00 UTC, for example, describes 23:00 to 00:00 Brasilia time and belongs to the earlier day. Grouping with as.Date(datetime) instead would use UTC days, which in Brazil end at 21:00 or 22:00 local time.

Radiation is usually missing at night, so radiation_mj_m2 does not use min_hours. It is the sum of the available values on days with at least min_hours hourly records, and NA otherwise; daytime gaps make it an underestimate.

The function does not itself check data quality, but values flagged by inmet_qc() (non-missing ⁠<variable>_flag⁠ columns) are left out of the daily statistics.

Value

A data frame with one row per station and day, sorted by station and date, containing the station identifiers, date, time_zone, n_hours (number of hourly records for that day) and the daily variables that can be computed from the columns present:

Column Definition
temp_max_c Maximum of temp_max_prev_c (or of temp_dry_c if absent)
temp_min_c Minimum of temp_min_prev_c (or of temp_dry_c if absent)
temp_mean_c Mean of temp_dry_c
temp_dew_mean_c Mean of temp_dew_c
humid_rel_mean_pct Mean of humid_rel_pct
humid_rel_min_pct Minimum of humid_rel_min_pct (or of humid_rel_pct)
precip_mm Sum of precip_mm
pressure_station_mean_hpa Mean of pressure_station_hpa
wind_speed_mean_ms Mean of wind_speed_ms
wind_gust_max_ms Maximum of wind_gust_ms
radiation_mj_m2 Sum of positive radiation_kjm2, in MJ/m^2

Examples

daily <- inmet_daily(rmet_example)
head(daily[, c("date", "n_hours", "temp_max_c", "temp_min_c", "precip_mm")])

# after quality control, flagged hourly values are ignored
daily_qc <- inmet_daily(inmet_qc(rmet_example))

Download INMET historical data archives

Description

Downloads annual ZIP archives (one per year, containing every automatic station) from INMET's historical data portal into a local cache.

Usage

inmet_download(
  years = .current_year(),
  dest_dir = tools::R_user_dir("rmet", "cache"),
  max_tries = 15L,
  quiet = FALSE,
  force = FALSE,
  check_updates = TRUE
)

Arguments

years

Integer vector of years to download. Archives start in 2000. Defaults to the current year.

dest_dir

Cache directory. It is created when necessary.

max_tries

Maximum attempts per year.

quiet

Suppress progress messages.

force

Download again even when a valid archive is cached.

check_updates

For cached archives of the current and previous year, ask the server whether a newer version exists and download it if so. INMET keeps appending data to these archives. Older years are never re-checked. Requires a (very small) request per recent year.

Details

Archives are written to ⁠<year>.zip.part⁠ and only renamed to ⁠<year>.zip⁠ after their size has been checked against the size reported by the server and the ZIP structure has been validated, so a partial file is never mistaken for a complete one. Interrupted downloads resume from where they stopped on the next call. A small ⁠<year>.zip.meta⁠ file records the server's version information.

The INMET server sends one archive at a time per client, so years are downloaded sequentially. Typical archives for recent years are 90 to 110 MB.

Value

Invisibly, a named character vector with the paths of the archives available after the call.

See Also

inmet_get(), inmet_read(), inmet_cache_status()

Examples


paths <- inmet_download(2023, dest_dir = file.path(tempdir(), "rmet"))

Extract INMET archives

Description

Copies the original station CSV files out of the annual archives, for use with other software.

Usage

inmet_extract(
  years,
  dest_dir = tools::R_user_dir("rmet", "cache"),
  out_dir = file.path(dest_dir, "csv"),
  stations = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

years

Integer years to extract.

dest_dir

Directory containing annual ZIP files.

out_dir

Destination directory.

stations

Optional station codes; only their files are extracted.

overwrite

Overwrite existing files.

quiet

Suppress progress messages.

Value

Invisibly, the paths of the extracted files.

Examples


cache <- file.path(tempdir(), "rmet")
inmet_download(2023, dest_dir = cache)
inmet_extract(2023, dest_dir = cache, out_dir = file.path(tempdir(), "csv"),
              stations = "A801")

Download and read INMET data in one call

Description

The recommended high-level interface: downloads missing annual archives with inmet_download(), reuses valid cached files, and returns the result of inmet_read().

Usage

inmet_get(
  years,
  stations = NULL,
  dest_dir = tools::R_user_dir("rmet", "cache"),
  tz = "UTC",
  variables = NULL,
  start_date = NULL,
  end_date = NULL,
  drop_empty = TRUE,
  max_tries = 15L,
  force = FALSE,
  check_updates = TRUE,
  quiet = FALSE
)

Arguments

years

Integer vector of years.

stations

Optional station codes, such as "A801". Matching is case-insensitive. Use inmet_stations() or inmet_nearest() to find codes.

dest_dir

Directory containing ⁠<year>.zip⁠ archives.

tz

Output time zone. Defaults to "UTC", the time standard used in the source files. Any name in OlsonNames() is accepted; only the display of the timestamps changes, not the instants they represent.

variables

Optional measurement columns to retain (see Columns). Identifier columns are always kept.

start_date, end_date

Optional inclusive date limits in YYYY-MM-DD format, interpreted in tz.

drop_empty

Drop hours in which every measurement is missing (default). INMET files contain such rows for periods when a station was not reporting. Use FALSE to keep them, for example to obtain a regular hourly grid.

max_tries

Maximum attempts per year.

force

Download again even when a valid archive is cached.

check_updates

For cached archives of the current and previous year, ask the server whether a newer version exists and download it if so. INMET keeps appending data to these archives. Older years are never re-checked. Requires a (very small) request per recent year.

quiet

Suppress progress messages.

Value

A data frame as documented in inmet_read().

See Also

inmet_daily(), inmet_stations(), inmet_nearest()

Examples


weather <- inmet_get(
  years = 2023,
  stations = "A801",
  variables = c("temp_dry_c", "precip_mm"),
  dest_dir = file.path(tempdir(), "rmet")
)
daily <- inmet_daily(weather)

Find the stations closest to a location

Description

Ranks automatic stations by great-circle distance from a point.

Usage

inmet_nearest(latitude, longitude, n = 5L, ...)

Arguments

latitude, longitude

Coordinates of the location in decimal degrees (south and west are negative).

n

Number of stations to return.

...

Further arguments passed to inmet_stations(), for example status = "Operante" or source = "bundled".

Value

The rows of inmet_stations() for the n nearest stations, with an added distance_km column, closest first.

Examples

# Stations near Porto Alegre, from the bundled catalogue
inmet_nearest(-30.03, -51.23, n = 3, source = "bundled")

Quality control of hourly INMET data

Description

Flags implausible hourly values with simple, transparent checks. INMET publishes automatic-station data without consistency validation; these checks catch the most common errors (impossible values, sensor spikes, stuck sensors and internally inconsistent records) but are no substitute for checks tailored to an analysis.

Usage

inmet_qc(
  x,
  action = c("flag", "remove"),
  checks = c("range", "consistency", "spike", "persistence"),
  persistence_hours = 12L,
  quiet = FALSE
)

Arguments

x

A data frame as returned by inmet_read().

action

"flag" (default) adds a ⁠<variable>_flag⁠ column for each checked variable, holding the names of the failed checks (separated by commas) or NA. "remove" sets flagged values to NA instead.

checks

Checks to run; any of "range", "consistency", "spike", and "persistence" (see Checks).

persistence_hours

Minimum number of consecutive hours with an identical value for the persistence check.

quiet

Suppress the summary message.

Value

x with flag columns added (or flagged values removed). The attribute qc_summary is a data frame with the number and percentage of flagged values per variable and check.

Checks

Neighbouring hours are only compared within a station and when exactly one hour apart.

See Also

inmet_daily(), inmet_completeness()

Examples

checked <- inmet_qc(rmet_example)
attr(checked, "qc_summary")
table(checked$temp_dry_c_flag, useNA = "ifany")

# daily values ignore flagged hours
daily <- inmet_daily(checked)

Read cached INMET historical data

Description

Parses the station CSV files inside annual INMET archives (downloaded with inmet_download()) into one data frame. Files are read directly from the ZIP archives; nothing is extracted to disk.

Usage

inmet_read(
  years,
  stations = NULL,
  dest_dir = tools::R_user_dir("rmet", "cache"),
  tz = "UTC",
  variables = NULL,
  start_date = NULL,
  end_date = NULL,
  drop_empty = TRUE,
  quiet = FALSE
)

Arguments

years

Integer vector of years.

stations

Optional station codes, such as "A801". Matching is case-insensitive. Use inmet_stations() or inmet_nearest() to find codes.

dest_dir

Directory containing ⁠<year>.zip⁠ archives.

tz

Output time zone. Defaults to "UTC", the time standard used in the source files. Any name in OlsonNames() is accepted; only the display of the timestamps changes, not the instants they represent.

variables

Optional measurement columns to retain (see Columns). Identifier columns are always kept.

start_date, end_date

Optional inclusive date limits in YYYY-MM-DD format, interpreted in tz.

drop_empty

Drop hours in which every measurement is missing (default). INMET files contain such rows for periods when a station was not reporting. Use FALSE to keep them, for example to obtain a regular hourly grid.

quiet

Suppress progress messages.

Value

A data frame with one row per station and hour, sorted by station code and time. Identifier columns come first: station_code, station_name, region, state, latitude, longitude, elevation (from each file's header) and datetime (POSIXct). Measurement columns are numeric; missing values are NA.

Repeated files

The archive of the current year contains several cumulative versions of each station file (for example, January to August and January to September). Each station and hour is returned once, taken from the most recent version that contains it.

Timestamps

Each row is stamped with the end of the hour it describes, in UTC. Values labelled "previous hour" (such as temp_max_prev_c and precip_mm) summarise the hour ending at datetime. Use inmet_daily() to build daily summaries in local time.

Columns

Column Description Unit
precip_mm Precipitation in the previous hour mm
pressure_station_hpa Station-level pressure hPa
pressure_max_hpa, pressure_min_hpa Pressure extremes, previous hour hPa
radiation_kjm2 Global radiation, previous hour kJ/m^2
temp_dry_c Air (dry-bulb) temperature degC
temp_dew_c Dew-point temperature degC
temp_max_prev_c, temp_min_prev_c Air temperature extremes, previous hour degC
temp_dew_max_c, temp_dew_min_c Dew-point extremes, previous hour degC
humid_rel_pct Relative humidity %
humid_rel_max_pct, humid_rel_min_pct Humidity extremes, previous hour %
wind_dir_deg Wind direction degrees
wind_gust_ms Maximum gust m/s
wind_speed_ms Wind speed m/s

Unrecognised source columns are kept under a snake_case version of their original title.

See Also

inmet_get(), inmet_download(), inmet_daily(), inmet_stations()

Examples


cache <- file.path(tempdir(), "rmet")
inmet_download(2023, dest_dir = cache)
poa <- inmet_read(2023, stations = "A801", dest_dir = cache)

Search the INMET automatic-station catalogue

Description

Returns automatic weather stations published by INMET. By default, the function uses a cached copy of the official API response and refreshes stale caches periodically. If the service is unavailable, it falls back to an older cache or to a snapshot of the official catalogue bundled with the package (its date is stored in the snapshot_date attribute).

Usage

inmet_stations(
  region = NULL,
  state = NULL,
  search = NULL,
  status = NULL,
  entity = NULL,
  source = c("auto", "remote", "bundled"),
  refresh = FALSE,
  max_age = 30,
  cache_dir = tools::R_user_dir("rmet", "cache"),
  quiet = FALSE
)

Arguments

region, state

Optional region or state abbreviations.

search

Optional literal text contained in the station name or code.

status

Optional operational status, such as "Operante" or "Pane".

entity

Optional station owner/provider, such as "INMET".

source

One of "auto", "remote", or "bundled". "auto" uses the cache, then the official API, then the bundled fallback.

refresh

Force a fresh request to the official API.

max_age

Maximum cache age in days before an automatic refresh.

cache_dir

Directory used for the catalogue cache.

quiet

Suppress informational messages.

Value

A data frame with station code, name, region, state, coordinates, altitude, operational dates (UTC calendar dates) and status, provider metadata, and the local time_zone (see inmet_timezone()). The legacy start_year column is retained for compatibility. The attribute catalog_source records where the data came from ("cache", "INMET API", "stale cache", or "bundled fallback").

See Also

inmet_nearest(), inmet_get(), inmet_read()

Examples

# Offline, reproducible example using the bundled fallback
inmet_stations(state = "RS", source = "bundled")


# Current official catalogue (downloaded once and then cached)
inmet_stations(state = "RS", refresh = TRUE, cache_dir = tempdir())

Local time zone of Brazilian stations

Description

Returns the Olson time-zone name for each station from its state and, where a state spans more than one historical zone, its longitude. The zones carry Brazil's full history of offsets and daylight saving time, so they give correct local times for any year since 2000.

Usage

inmet_timezone(state, longitude = NA_real_)

Arguments

state

Two-letter state abbreviations, such as "RS".

longitude

Station longitudes in decimal degrees. Only used for Amazonas (west of 67.2 degrees W is UTC-5), Para (west of 52.5 degrees W was UTC-4 until 2008), and Pernambuco (Fernando de Noronha).

Details

Zone boundaries inside Amazonas and Para follow municipal borders; the longitude limits reproduce them for INMET's stations but are an approximation elsewhere.

Value

A character vector of time-zone names, NA for unknown states.

Examples

inmet_timezone(c("RS", "MT", "AC", "AM", "AM"),
               c(-51.2, -56.1, -67.8, -60.0, -69.9))

Hourly weather data from INMET station A801 (Porto Alegre), 2023

Description

One year of hourly observations from the automatic station A801 (Porto Alegre - Jardim Botanico, RS), exactly as returned by inmet_get(2023, stations = "A801"). Timestamps are in UTC. Hours with no measurements at all are not included.

Usage

rmet_example

Format

A data frame with 8,663 rows and 25 columns. See inmet_read() for the description of each column.

Source

INMET (Instituto Nacional de Meteorologia), https://portal.inmet.gov.br/dadoshistoricos. Generated by data-raw/rmet_example.R.

Examples

range(rmet_example$datetime)
head(inmet_daily(rmet_example))