meteole 0.2.3

A Python client library for forecast model APIs (e.g., Météo-France).

Easy access to Météo-France weather models and data

---

Documentation: https://maif.github.io/meteole/home/

Repository: https://github.com/MAIF/meteole

Release article: Medium

---

Overview

Meteole is a Python library designed to simplify accessing weather data from the Météo-France APIs. It provides:

• Automated token management: Simplify authentication with a single application_id.
• Unified model usage: AROME, AROME INSTANTANE, ARPEGE, PIAF forecasts with a consistent interface.
• User-friendly parameter handling: Intuitive management of key weather forecasting parameters.
• Seamless data integration: Directly export forecasts as Pandas DataFrames
• Vigilance bulletins: Retrieve real-time weather warnings across France.

Perfect for data scientists, meteorologists, and developers, Meteole helps integrate weather forecasts into projects effortlessly.

Installation

pip install meteole

🕐 Quickstart

Step 1: Obtain an API token or key

Create an account on the Météo-France API portal. Next, subscribe to the desired APIs (Arome, Arpege, Arome Instantané, etc.). Retrieve the API token (or key) by going to “Mes APIs” and then “Générer token”.

Step 2: Fetch Forecasts

Meteole allows you to retrieve forecasts for a wide range of weather indicators. Here's how to get started:

Characteristics	AROME	AROME-PE	ARPEGE	ARPEGE-PE	AROME INSTANTANE	PIAF
Resolution	1.3 km	2.8 km	10 km	10 km	1.3 km	1.3 km
Update Frequency	Every 3 hours	Every 6 hours	Every 6 hours	Every 6 hours	Every 1 hour	Every 10 minutes
Forecast Range	Every hour, up to 51 hours	Every hour, up to 51 hours	Every hour, up to 114 hours	Every hour up to 48 hours, then every 3 hours up to 114 hours	Every 15 minutes, up to 360 minutes	Every 5 minutes, up to 195 minutes
Numbers of scenarios	1	25	1	35	1	1

The AromePE and ArpegePE models are ensemble models. Instead of making a single forecast of the most likely weather, a set (or ensemble) of forecasts is produced. This set of forecasts aims to give an indication of the range of possible future states of the atmosphere (from Wikipedia). It provides several scenarios of the possible weather parameters instead of one for the standard determinist models.

note : the date of the run cannot be more than 4 days in the past. Consequently, change the date of the run in the example below.

import datetime as dt
from meteole import AromeForecast

# Configure the logger to provide information on data recovery: recovery status, default settings, etc.
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("meteole")

# Initialize the AROME forecast client
# Find your APPLICATION_ID by following these guidelines: https://maif.github.io/meteole/how_to/?h=application_id#get-a-token-an-api-key-or-an-application-id
arome_client = AromeForecast(application_id=APPLICATION_ID)

# Check indicators available
print(arome_client.indicators)

# Fetch weather data
df_arome = arome_client.get_coverage(
    indicator="V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",  # Optional: if not, you have to fill coverage_id
    run="2025-01-10T00.00.00Z",                                                # Optional: forecast start time
    forecast_horizons=[                                                       # Optional: prediction times (in hours)
      dt.timedelta(hours=1),
      dt.timedelta(hours=2),
    ],  
    heights=[10],                                                              # Optional: height above ground level
    pressures=None,                                                            # Optional: pressure level
    long = (-5.1413, 9.5602),                                                  # Optional: longitude
    lat = (41.33356, 51.0889),                                                 # Optional: latitude
    coverage_id=None,                                                          # Optional: an alternative to indicator/run/interval
    temp_dir=None,                                                             # Optional: Directory to store the temporary file
    ensemble_numbers=range(3),                                                 # Optional: Only for ensemble models (AromePE), the number of scenarios
    )

Note: The coverage_id can be used instead of indicator, run, and interval.

The usage of ARPEGE, AROME INSTANTANE, PIAF is identical to AROME, except that you initialize the appropriate class

Step 3: Explore Parameters and Indicators

Discover Available Indicators

Use the get_capabilities() method to list all available indicators, run times, and intervals:

indicators = arome_client.get_capabilities()
print(indicators)

Fetch Description for a Specific Indicator

Understand the required parameters (forecast_horizons, heights, pressures) for any indicator using get_coverage_description():

description = arome_client.get_coverage_description(coverage_id)
print(description)

Geographical Coverage

The geographical coverage of forecasts can be customized using the lat and long parameters in the get_coverage method. By default, Meteole retrieves data for the entire metropolitan France.

Fetch Forecasts for Multiple Indicators

The get_combined_coverage method allows you to retrieve weather data for multiple indicators at the same time, streamlining the process of gathering forecasts for different parameters (e.g., temperature, wind speed, etc.). For detailed guidance on using this feature, refer to this tutorial.

Explore detailed examples in the tutorials folder to quickly get started with Meteole.

⚠️ VIGILANCE METEO FRANCE

Meteo France provides nationwide vigilance bulletins, highlighting potential weather risks. These tools allow you to integrate weather warnings into your workflows, helping trigger targeted actions or models.

from meteole import Vigilance

vigi = Vigilance(application_id=APPLICATION_ID)

df_phenomenon, df_timelaps = vigi.get_phenomenon()

bulletin = vigi.get_bulletin()

vigi.get_vignette()

To have more documentation from Meteo-France in Vigilance Bulletin :

• Meteo France Documentation

Contributing

Contributions are very welcome!

If you see an issue that you'd like to see fixed, the best way to make it happen is to help out by submitting a pull request implementing it.

Refer to the CONTRIBUTING.md file for more details about the workflow, and general hints on how to prepare your pull request. You can also ask for clarifications or guidance in GitHub issues directly.

License

This project is Open Source and available under the Apache 2 License.

🙏 Acknowledgements

The development of Meteole was inspired by the excellent work in the meteofranceapi repository by Antoine Tavant.