API Reference

AtlanticCloudClient(; api_key, base_url)

Client for the AIR Centre Atlantic Cloud API.

The API key is resolved in this order:

1. Explicit api_key keyword argument
2. ATLANTICCLOUD_API_KEY environment variable
3. Error with registration URL if neither is present

Example

client = AtlanticCloudClient(api_key="your_key")

Register at: https://services.aircentre.org/access/account

AtlanticCloudError(message)

Exception thrown by AtlanticCloud when an API request fails.

Catch this type to handle all errors from the package in one place.

Station

A meteorological station in the AIR Centre network.

Implements GeoInterface.jl PointTrait, so stations can be used directly with GeoMakie, GeometryOps, GeoJSON.jl, and any other JuliaGeo-compatible package.

Fields

• station_id: Unique identifier (may be nothing).
• place: Human-readable location name (may be nothing).
• latitude_deg: Latitude in decimal degrees.
• longitude_deg: Longitude in decimal degrees.
• source: Data source, e.g. "IPMA", "CEMADEN" (may be nothing).
• country: Two-letter country code, "PT" or "BR" (may be nothing).
• state: Two-letter Brazilian state code; nothing for PT stations.
• elevation_m: Station altitude in metres (may be nothing).
• responsible: Operating agency, e.g. "INMET" (may be nothing).
• utc_offset: UTC offset in hours (may be nothing).
• temporal_resolution_min: Nominal observation interval in minutes (may be nothing).

get_stations(client; station_id, source, country, state)

Retrieve meteorological stations from the AIR Centre network.

Arguments

• client: An AtlanticCloudClient instance.
• station_id: Filter by station ID (optional).
• source: Filter by data source, e.g. "IPMA", "CEMADEN" (optional).
• country: Filter by country code, "PT" or "BR" (optional).
• state: Filter by Brazilian state code, e.g. "SP", "MG" (optional).

Returns

Vector{Station}

Example

client = AtlanticCloudClient(api_key="your_key")
stations = get_stations(client)
br = get_stations(client, country="BR")
sp = get_stations(client, country="BR", state="SP")

Observation

A single hourly meteorological observation from a station.

Fields

• station_id: Station identifier (may be nothing).
• timestamp: Observation time as DateTime.
• wind_speed_kmh: Wind speed in km/h.
• temperature_c: Air temperature in °C.
• radiation_kjm2: Solar radiation in kJ/m².
• wind_direction_bin: Wind direction bin index (integer).
• precipitation_accum_mm: Accumulated precipitation in mm.
• rel_humidity_pctg: Relative humidity as percentage.
• pressure_hpa: Atmospheric pressure in hPa (may be nothing).

All metric fields are Union{Float64, Nothing} except wind_direction_bin which is Union{Int, Nothing}.

get_observations(client, station_id; start_date, end_date, metrics)

Retrieve hourly meteorological observations for a station.

Arguments

• client: An AtlanticCloudClient instance.
• station_id: Required station identifier.
• start_date: Start of date range as Date or DateTime (optional).
• end_date: End of date range as Date or DateTime (optional).
• metrics: Vector of metric names to include (optional). See VALID_METRICS.

Throws ArgumentError if start_date is after end_date.

Returns

Vector{Observation}

Example

using Dates
client = AtlanticCloudClient(api_key="your_key")
obs = get_observations(client, "11217160",
    start_date=Date(2024,1,1),
    end_date=Date(2024,1,31),
    metrics=["temperature_c", "wind_speed_kmh"])

get_observations_bulk(client, station_ids; start_date, end_date, metrics, on_error, progress)

Fetch observations for multiple stations, returning a combined Vector{Observation}.

The API requires one station per request, so this function loops internally and concatenates the results. All filter parameters are passed through to get_observations.

Arguments

• client: An AtlanticCloudClient instance.
• station_ids: Vector of station identifiers to fetch.
• start_date: Start of date range as Date or DateTime (optional).
• end_date: End of date range as Date or DateTime (optional).
• metrics: Vector of metric names to include (optional).
• on_error: Error handling mode (default :warn).
  • :warn — log a warning, skip the station, continue.
  • :throw — re-raise immediately (fail-fast).
  • :skip — silently skip failed stations.
• progress: Log progress every 10 stations (default true).

Returns

Vector{Observation}

Example

client = AtlanticCloudClient(api_key="your_key")
stations = get_stations(client)
ids = [s.station_id for s in stations]
obs = get_observations_bulk(client, ids,
    start_date=Date(2024, 1, 1),
    end_date=Date(2024, 1, 31))

VALID_METRICS

Set of valid metric names that can be passed to get_observations and get_observations_bulk via the metrics keyword argument.

Valid values: wind_speed_kmh, temperature_c, radiation_kjm2, wind_direction_bin, precipitation_accum_mm, rel_humidity_pctg, pressure_hpa.

BrObservation

A single Brazilian rainfall observation (hourly or daily).

Fields

• station_id: Station identifier (may be nothing).
• timestamp: Observation time as DateTime.
• precipitation_accum_mm: Accumulated precipitation in mm.
• qc_flag: Quality control flag, "PASS" or "SUSPECT_*".
• flagged: true if the observation is suspect.
• state: Two-letter Brazilian state code.

get_br_observations(client; resolution, station_id, state, start_date, end_date, flagged, qc_flag)

Retrieve Brazilian rainfall observations.

Arguments

• client: An AtlanticCloudClient instance.
• resolution: Required. "hourly" or "daily".
• station_id: Filter by station ID (optional).
• state: Filter by Brazilian state code, e.g. "SP" (optional).
• start_date: Start of date range as Date or DateTime (optional).
• end_date: End of date range as Date or DateTime (optional).
• flagged: Filter by QC flag status: true for suspect, false for clean (optional).
• qc_flag: Filter by exact QC flag string, e.g. "PASS" (optional).

At least one of station_id or state must be provided. Date range cannot exceed 6 months (API limit).

Returns

Vector{BrObservation}

Example

using Dates
client = AtlanticCloudClient(api_key="your_key")
obs = get_br_observations(client,
    resolution="hourly", state="SP",
    start_date=Date(2020, 1, 1),
    end_date=Date(2020, 1, 31))

get_br_observations_bulk(client, station_ids; resolution, start_date, end_date, flagged, qc_flag, on_error, progress)

Fetch Brazilian rainfall observations for multiple stations, returning a combined Vector{BrObservation}.

The API requires one station per request, so this function loops internally. For state-based queries, use get_br_observations directly — a single call with state already returns all stations for that state.

Arguments

• client: An AtlanticCloudClient instance.
• station_ids: Vector of station identifiers to fetch.
• resolution: Required. "hourly" or "daily".
• start_date: Start of date range as Date or DateTime (optional).
• end_date: End of date range as Date or DateTime (optional).
• flagged: Filter by QC flag status (optional).
• qc_flag: Filter by exact QC flag string (optional).
• on_error: Error handling mode (default :warn).
  • :warn — log a warning, skip the station, continue.
  • :throw — re-raise immediately (fail-fast).
  • :skip — silently skip failed stations.
• progress: Log progress every 10 stations (default true).

Returns

Vector{BrObservation}

Example

using Dates
client = AtlanticCloudClient(api_key="your_key")
stations = get_stations(client, country="BR", state="MG")
ids = [s.station_id for s in stations if s.station_id !== nothing]
obs = get_br_observations_bulk(client, ids[1:5],
    resolution="hourly",
    start_date=Date(2020, 1, 1),
    end_date=Date(2020, 1, 31))

to_dataframe(stations::Vector{Station}) -> DataFrame

Convert a vector of Station objects to a DataFrame.

Columns: station_id, place, latitude_deg, longitude_deg, source, country, state, elevation_m, responsible, utc_offset, temporal_resolution_min. Fields that are nothing are converted to missing.

Example

client = AtlanticCloudClient(api_key="your_key")
stations = get_stations(client)
df = to_dataframe(stations)

to_dataframe(observations::Vector{Observation}) -> DataFrame

Convert a vector of Observation objects to a DataFrame.

Columns: station_id, timestamp, and one column per metric field. Fields that are nothing are converted to missing.

Example

client = AtlanticCloudClient(api_key="your_key")
obs = get_observations(client, "11217160")
df = to_dataframe(obs)

to_dataframe(observations::Vector{BrObservation}) -> DataFrame

Convert a vector of BrObservation objects to a DataFrame.

Columns: station_id, timestamp, precipitation_accum_mm, qc_flag, flagged, state. The station_id field uses nothing → missing conversion; all other fields are non-nullable.

Example

using Dates
client = AtlanticCloudClient(api_key="your_key")
obs = get_br_observations(client,
    resolution="hourly", state="SP",
    start_date=Date(2020, 1, 1), end_date=Date(2020, 1, 31))
df = to_dataframe(obs)