Package 'mfclim'

Title: Download Archived Meteorological Data from Meteo-France
Description: Download meteorological data from the 'Meteo-France' public API 'Données climatologiques' and 'SYNOP' open data archives. It provides functions to authenticate, list stations, retrieve station metadata, request data, download files, and import data directly into 'R'.
Authors: Nicolas Moiroux [aut, cre] (ORCID: <https://orcid.org/0000-0001-6755-6167>)
Maintainer: Nicolas Moiroux <[email protected]>
License: AGPL (>= 3)
Version: 0.1.0
Built: 2026-04-03 11:44:49 UTC
Source: https://github.com/Nmoiroux/mfclim

Help Index

Download a climate data file from the Meteo-France API

Description

Download the CSV file corresponding to a previously submitted data order . The function repeatedly queries the API until the file is ready and then downloads it to disk.

Usage

mfclim_download(token, id_cmde, filename = "data.csv", folder = tempdir())

Arguments

token

Character string. OAuth2 access token obtained with mfclim_get_token().
id_cmde

Numeric or character. Order ID returned by mfclim_order().
filename

Character string. Name of the output CSV file.
folder

Character string. Where to save the downloaded CSV file. Default to tempdir()

Details

The function polls the API every 5 seconds until the file is available. When the file is ready, it is downloaded and saved to filename.

Value

Character string. Path to the downloaded file.

See Also

mfclim_order()

Examples

## Not run: 
file <- mfclim_download(token, id_cmde = 123456, filename = "meteo.csv")

## End(Not run)

Download archived meteorological data from the Meteo-France "Donnees Climatologiques" API in one step

Description

This is a wrapper function that retrieves data from the Climatological Data API for a given station and period. The function can either use an existing token or automatically request a new token using client credentials.

Usage

mfclim_get_data(
  token,
  client_auth,
  station,
  step,
  date_deb,
  date_fin,
  filename = "data.csv",
  folder = tempdir()
)

Arguments

token

Character string. OAuth2 access token obtained with mfclim_get_token() (optional if client_auth is provided).
client_auth

Character string. Authentication string provided by the Meteo-France API portal (optional if token is provided).
station

Character string. Station identifier.
step

Character string. Time step of the requested data.
date_deb

Character string. Start date in ISO 8601 UTC format (see example). If step = "6m", minutes values must be multiples of 6 (00, 06, 12, 18, 24, 30, 36, 42, 48, 54).
date_fin

Character string. End date in ISO 8601 UTC format. If step = "6m", minutes values must be multiples of 6 (00, 06, 12, 18, 24, 30, 36, 42, 48, 54).
filename

Character string. Name of the downloaded CSV file. Default to
folder

Character string. Where to save the downloaded CSV file. Default to tempdir().

Details

The function:

  1. Obtains an access token if not provided

  2. Submits a data order

  3. Waits for the file to be generated

  4. Downloads the CSV file

  5. Reads the CSV file into R

Value

A data.frame containing the climate data.

See Also

mfclim_get_token(), mfclim_order(), mfclim_download()

Examples

## Not run: 
data <- mfclim_get_data(
  client_auth = client_auth,
  station = "75114001",
  step = "1d",
  date_deb = "2020-01-01T00:00:00Z",
  date_fin = "2020-12-31T23:59:59Z"
)

## End(Not run)

Get Meteo-France API access token

Description

Request an OAuth2 access token from the Meteo-France API using the client credentials authentication flow.

Usage

mfclim_get_token(client_auth)

Arguments

client_auth

Character string. Authentication identifier provided by the Meteo-France API portal (string following "Authorization: Basic").

Details

Requires a valid account on the Meteo-France API portal https://portail-api.meteofrance.fr and a (free) subscription to the 'Climatological data' API (https://portail-api.meteofrance.fr/web/en/api/DonneesPubliquesClimatologie). The client_auth value must be obtained from your account on the Meteo-France API portal:

  • Go to 'My API' -> 'Climatological data' -> 'Generate Token' -> 'Curl'

  • Copy the string that appears after "Authorization: Basic" in the provided curl command (remove the trailing ⁠"⁠).

Value

A character string containing the access token used to authenticate subsequent API requests.

Examples

## Not run: 
token <- mfclim_get_token(client_auth)

## End(Not run)

Get information about a Meteo-France station

Description

Retrieve metadata and information for a given Meteo-France station using its station identifier.

Usage

mfclim_info_station(token, client_auth, station)

Arguments

token

Character string. OAuth2 access token obtained with mfclim_get_token().
client_auth

Character string. Authentication string provided by the Meteo-France API portal. Used to automatically obtain a token if token is not provided.
station

Character string. Station identifier (8-digit station code).

Details

If token is not provided, the function will automatically request a new token using client_auth. The returned list structure depends on the API response and may include station metadata, location, altitude, opening and closing dates, and available parameters.

Value

A list containing station metadata. Scalar elements are returned as vectors, and nested list elements are converted into data frames.

Examples

## Not run: 
info <- mfclim_info_station(
  client_auth = client_auth,
  station = "75114001"
)

## End(Not run)

Get the list of Meteo-France stations by department

Description

Retrieve the list of available Meteo-France stations for a given French department and data frequency. The list can optionally be filtered by meteorological parameter.

Usage

mfclim_list_stations(
  token,
  client_auth,
  departement,
  step = c("1d", "1h", "6m"),
  parametre = NULL
)

Arguments

token

Character string. OAuth2 access token obtained with mfclim_get_token().
client_auth

Character string. Authentication string provided by the Meteo-France API portal. Used to automatically obtain a token if token is not provided.
departement

Character or numeric. French department code.
step

Character string. Data frequency. One of: "1d" (daily), "1h" (hourly), "6m" (6 minutes).
parametre

Character string. Optional meteorological parameter used to filter stations. One of: "precipitation", "temperature", "humidite", "vent", "pression", "rayonnement", "insolation", "etat_mer", "evapo".

Details

If token is not provided, the function will automatically request a new token using client_auth.

Value

A data.frame containing the list of stations and their metadata.

Examples

## Not run: 
stations <- mfclim_list_stations(
  client_auth = client_auth,
  departement = "75",
  step = "1d",
  parametre = "temperature"
)

## End(Not run)

Order climate data for a station from the Meteo-France API

Description

Submit an asynchronous order for climatological data from a Meteo-France station. The function returns a order ID that must be used later to download the data file.

Usage

mfclim_order(
  token,
  station,
  step = c("1mo", "10d", "1d", "1h", "6m"),
  date_deb,
  date_fin
)

Arguments

token

Character string. OAuth2 access token obtained with mfclim_get_token().
station

Character string. Station identifier (8-digit station code).
step

Character string. Time step of the ordered data. One of: "6m" (6 minutes), "1h" (hourly), "1d" (daily), "10d" (10-day), "1mo" (monthly).
date_deb

Character string. Start date of the requested period in ISO 8601 UTC format (e.g. "2020-01-01T00:00:00Z"). If step = "6m", minutes value must be a multiple of 6 (00, 06, 12, 18, 24, 30, 36, 42, 48, 54).
date_fin

Character string. End date of the requested period in ISO 8601 UTC format (e.g. "2020-12-31T23:59:59Z"). If step = "6m", minutes value must be a multiple of 6 (00, 06, 12, 18, 24, 30, 36, 42, 48, 54).

Details

The order is asynchronous: the data file is generated by the server and must be retrieved afterward using the order ID.

Value

Numeric or character value corresponding to the order ID. This ID must be used to download the data file.

See Also

mfclim_download()

Examples

## Not run: 
id_cmd <- mfclim_order(
  token,
  station = "75114001",
  step = "1d",
  date_deb = "2020-01-01T00:00:00Z",
  date_fin = "2020-12-31T23:59:59Z"
)

## End(Not run)

Download SYNOP data from Meteo-France open data

Description

Downloads SYNOP surface observation data from the Meteo-France open data portal for a given year, decompresses the archive, and return a data frame.

Usage

mfclim_synop(year, path = tempdir())

Arguments

year

Numeric or character. Year of the data to download (YYYY), between 1996 and present year (included).
path

Path to folder where to save the archive. Default to tempdir().

Details

SYNOP data come from observation messages exchanged through the World Meteorological Organization (WMO) Global Telecommunication System (GTS). These observations include measured atmospheric parameters such as temperature, humidity, wind direction and speed, atmospheric pressure, and precipitation amount, as well as observed variables such as present weather, cloud description, and visibility. Depending on instrumentation and local conditions, additional variables may be available (e.g., snow depth, ground state).

The dataset covers mainland France and overseas territories with a typical observation frequency of 3 hours. Available years cover 1996 to present.

Data description and documentation is available here (French): https://meteo.data.gouv.fr/datasets/686f8595b351c06a3a790867

Files are downloaded as .csv.gz, decompressed on the fly, and read. Typical size of compressed files is <7MB for period 1996-2024 and <20MB for more recent years. Missing values coded as "", "NA", or "mq" are converted to NA in the returned data frame.

Value

A data.frame containing the downloaded data.

Examples

## Not run: 
mydata <- mfclim_synop(2020)

## End(Not run)