Reference

meteofrance

Météo-France API.

class meteofrance_api.MeteoFranceClient(access_token=None)

Proxy to the Météo-France REST API.

You will find methods and helpers to request weather forecast, rain forecast and weather alert bulletin.

Parameters:

access_token (str | None) –

get_forecast(latitude, longitude, language='fr')

Retrieve the weather forecast for a given GPS location.

Results can be fetched in french or english according to the language parameter.

Parameters:
  • latitude (float) – Latitude in degree of the GPS point corresponding to the weather forecast.

  • longitude (float) – Longitude in degree of the GPS point corresponding to the weather forecast.

  • language (str) – Optional; If language is equal “fr” (default value) results will be in French. All other value will give results in English.

Returns:

A Forecast intance representing the hourly and daily weather forecast.

Return type:

Forecast

get_forecast_for_place(place, language='fr')

Retrieve the weather forecast for a given Place instance.

Results can be fetched in french or english according to the language parameter.

Parameters:
  • place (Place) – Place class instance corresponding to a location.

  • language (str) – Optional; If language is equal “fr” (default value) results will be in French. All other value will give results in English.

Returns:

A Forecast intance representing the hourly and daily weather forecast.

Return type:

Forecast

get_observation(latitude, longitude, language='fr')

Retrieve the weather observation for a given GPS location.

Results can be fetched in french or english according to the language parameter.

Parameters:
  • latitude (float) – Latitude in degree of the GPS point corresponding to the weather forecast.

  • longitude (float) – Longitude in degree of the GPS point corresponding to the weather forecast.

  • language (str) – Optional; If language is equal “fr” (default value) results will be in French. All other value will give results in English.

Returns:

An Observation instance.

Return type:

Observation

get_observation_for_place(place, language='fr')

Retrieve the weather observation for a given Place instance.

Results can be fetched in french or english according to the language parameter.

Parameters:
  • place (Place) – Place class instance corresponding to a location.

  • language (str) – Optional; If language is equal “fr” (default value) results will be in French. All other value will give results in English.

Returns:

An Observation intance.

Return type:

Observation

get_picture_of_the_day(domain='france')

Retrieve the picture of the day image URL & description.

Parameters:

domain (str) – could be france

Returns:

PictureOfTheDay instance with the URL and the description of the picture of the day.

Return type:

PictureOfTheDay

get_rain(latitude, longitude, language='fr')

Retrieve the next 1 hour rain forecast for a given GPS the location.

Results can be fetched in french or english according to the language parameter.

Parameters:
  • latitude (float) – Latitude in degree of the GPS point corresponding to the rain forecast.

  • longitude (float) – Longitude in degree of the GPS point corresponding to the rain forecast.

  • language (str) – Optional; If language is equal “fr” (default value) results will be in French. All other value will give results in English.

Returns:

A Rain instance representing the next hour rain forecast.

Return type:

Rain

get_warning_current_phenomenoms(domain, depth=0, with_coastal_bulletin=False)

Return the current weather phenomenoms (or alerts) for a given domain.

Parameters:
  • domain (str) – could be france or any metropolitan France department numbers on two digits. For some departments you can access an additional bulletin for coastal phenomenoms. To access it add 10 after the domain id (example: 1310).

  • depth (int) – Optional; To be used with domain = ‘france’. With depth = 0 the results will show only natinal sum up of the weather alerts. If depth = 1, you will have in addition, the bulletin for all metropolitan France department and Andorre

  • with_coastal_bulletin (bool) – Optional; If set to True (default is False), you can get the basic bulletin and coastal bulletin merged.

Returns:

A warning.CurrentPhenomenons instance representing the weather alert bulletin.

Return type:

CurrentPhenomenons

get_warning_dictionary(language='fr')

Retrieves the meteorological dictionary from the Météo-France API.

This dictionary includes information about various meteorological phenomena and color codes used for weather warnings.

Parameters:

language (str) – The language in which to retrieve the dictionary data. Default is ‘fr’ for French. Other language codes can be used if supported by the API.

Returns:

An object containing structured data about

meteorological phenomena and warning color codes. It has two main attributes: ‘phenomenons’ (list of PhenomenonDictionaryEntry) and ‘colors’ (list of ColorDictionaryEntry).

Return type:

WarningDictionary

get_warning_full(domain, with_coastal_bulletin=False)

Retrieve a complete bulletin of the weather phenomenons for a given domain.

For a given domain we can access the maximum alert, a timelaps of the alert evolution for the next 24 hours, a list of alerts and other metadatas.

Parameters:
  • domain (str) – could be france or any metropolitan France department numbers on two digits. For some departments you can access an additional bulletin for coastal phenomenoms. To access it add 10 after the domain id (example: 1310).

  • with_coastal_bulletin (bool) – Optional; If set to True (default is False), you can get the basic bulletin and coastal bulletin merged.

Returns:

A warning.Full instance representing the complete weather alert bulletin.

Return type:

Full

get_warning_thumbnail(domain='france')

Retrieve the thumbnail URL of the weather phenomenoms or alerts map.

Parameters:

domain (str) – could be france or any metropolitan France department numbers on two digits.

Returns:

The URL of the thumbnail representing the weather alert status.

Return type:

str

search_places(search_query, latitude=None, longitude=None)

Search the places (cities) linked to a query by name.

You can add GPS coordinates in parameter to search places arround a given location.

Parameters:
  • search_query (str) – A complete name, only a part of a name or a postal code (for France only) corresponding to a city in the world.

  • latitude (str | None) – Optional; Latitude in degree of a reference point to order results. The nearest places first.

  • longitude (str | None) – Optional; Longitude in degree of a reference point to order results. The nearest places first.

Returns:

A list of places (Place instance) corresponding to the query.

Return type:

List[Place]

meteofrance.model

Météo-France models for the REST API.

class meteofrance_api.model.CurrentPhenomenons(raw_data)

Class to access the results of a warning/currentPhenomenons REST API request.

For coastal department two bulletins are avalaible corresponding to two different domains.

Parameters:

raw_data (WarnningCurrentPhenomenonsData) –

update_time

A timestamp (as integer) corresponding to the latest update of the pheomenoms.

end_validity_time

A timestamp (as integer) corresponding to expiration date of the phenomenoms.

domain_id

A string corresponding do the domain ID of the bulletin. Value is ‘France’ or a department number.

phenomenons_max_colors

A list of dictionnaries with type of phenomenoms and the current alert level.

property domain_id: str

Return the domain ID of the phenomenoms.

property end_validity_time: int

Return the end of validty time of the phenomenoms.

get_domain_max_color()

Get the maximum level of alert of a given domain (class helper).

Returns:

An integer corresponding to the status code representing the maximum alert.

Return type:

int

merge_with_coastal_phenomenons(coastal_phenomenoms)

Merge the classical phenomenoms bulleting with the coastal one.

Extend the phenomenomes_max_colors property with the content of the coastal weather alert bulletin.

Parameters:

coastal_phenomenoms (CurrentPhenomenons) – CurrentPhenomenons instance corresponding to the coastal weather alert bulletin.

Return type:

None

property phenomenons_max_colors: List[PhenomenonMaxColor]

Return the list and colors of the phenomenoms.

property update_time: int

Return the update time of the phenomenoms.

class meteofrance_api.model.Forecast(raw_data)

Class to access the results of a forecast API request.

Parameters:

raw_data (ForecastData) –

position

A dictionary with metadata about the position of the forecast place.

updated_on

A timestamp as int corresponding to the latest update date.

daily_forecast

A list of dictionaries to describe the daily forecast for the next 15 days.

forecast

A list of dictionaries to describe the hourly forecast for the next days.

probability_forecast

A list of dictionaries to describe the event probability forecast (rain, snow, freezing) for next 10 days.

today_forecast

A dictionary corresponding to the daily forecast for the current

day.
nearest_forecast

A dictionary corresponding to the nearest hourly forecast.

current_forecast

A dictionary corresponding to the hourly forecast for the current hour.

property current_forecast: Dict[str, Any]

Return the forecast of the current hour.

property daily_forecast: List[Dict[str, Any]]

Return the daily forecast for the following days.

property forecast: List[Dict[str, Any]]

Return the hourly forecast.

property nearest_forecast: Dict[str, Any]

Return the nearest hourly forecast.

property position: Dict[str, Any]

Return the position information of the forecast.

property probability_forecast: List[Dict[str, Any]]

Return the wheather event forecast.

timestamp_to_locale_time(timestamp)

Convert timestamp in datetime in the forecast location timezone (Helper).

Parameters:

timestamp (int) – An integer to describe the UNIX timestamp.

Returns:

Datetime instance corresponding to the timestamp with the timezone of the

forecast location.

Return type:

datetime

property today_forecast: Dict[str, Any]

Return the forecast for today.

property updated_on: int

Return the update timestamp of the forecast.

class meteofrance_api.model.Full(raw_data)

This class allows to access the results of a warning/full API command.

For a given domain we can access the maximum alert, a timelaps of the alert evolution for the next 24 hours, and a list of alerts.

For coastal department two bulletins are avalaible corresponding to two different domains.

Parameters:

raw_data (WarnningFullData) –

update_time

A timestamp (as integer) corresponding to the latest update of the pheomenoms.

end_validity_time

A timestamp (as integer) corresponding to expiration date of the phenomenoms.

domain_id

A string corresponding do the domain ID of the bulletin. Value is ‘France’ or a department number.

color_max

An integer representing the maximum alert level in the domain.

timelaps

A list of dictionnaries corresponding to the schedule of each phenomenoms in the next 24 hours.

phenomenons_items

list of dictionnaries corresponding the alert level for each phenomenoms type.

property color_max: int

Return the color max of the domain.

property domain_id: str

Return the domain ID of the the full bulletin.

property end_validity_time: int

Return the end of validty time of the full bulletin.

merge_with_coastal_phenomenons(coastal_phenomenoms)

Merge the classical phenomenon bulletin with the coastal one.

Extend the color_max, timelaps and phenomenons_items properties with the content

of the coastal weather alert bulletin.

Parameters:

coastal_phenomenoms (Full) – Full instance corresponding to the coastal weather alert bulletin.

Return type:

None

property phenomenons_items: List[PhenomenonMaxColor]

Return the phenomenom list of the domain.

property timelaps: List[Dict[str, Any]]

Return the timelaps of each phenomenom for the domain.

property update_time: int

Return the update time of the full bulletin.

class meteofrance_api.model.Observation(raw_data)

Class to access the results of an observation API request.

Parameters:

raw_data (ObservationData) –

timezone

The observation timezone

time

The time at which the observation was made

temperature

The observed temperature (°C)

wind_speed

The observed wind speed (km/h)

wind_direction

The observed wind direction (°)

wind_icon

An icon ID illustrating the observed wind direction

weather_icon

An icon ID illustrating the observed weather condition

weather_description

A description of the observed weather condition

property temperature: float | None

Returns the observed temp (°C).

property time_as_datetime: datetime | None

Returns the time at which the observation was made.

property time_as_string: str | None

Returns the time at which the observation was made.

property timezone: str | None

Returns the observation timezone.

property weather_description: str | None

Returns a description of the observed weather condition.

property weather_icon: str | None

Returns an icon ID illustrating the observed weather condition.

property wind_direction: int | None

Returns the observed wind direction (°).

property wind_icon: str | None

Returns an icon ID illustrating the observed wind direction.

property wind_speed: float | None

Returns the observed wind speed (km/h).

class meteofrance_api.model.PictureOfTheDay(raw_data)

Class to access the results of a ImageJour/last REST API request.

Parameters:

raw_data (PictureOfTheDayData) –

image_url

A string corresponding to the picture of the day URL.

image_hd_url

A string corresponding to the URL for the HD version of the picture of the day.

descritpion

A string with the description of the picture of the day.

property description: str

Return the description of the picture of the day.

property image_url: str

Return the image URL of the picture of the day.

class meteofrance_api.model.Place(raw_data)

Class to access the results of ‘places’ REST API request.

Parameters:

raw_data (PlaceData) –

insee

A string corresponding to the INSEE ID of the place.

name

Name of the place.

lat

A float with the latitude in degree of the place.

lon

A float with the longitude in degree of the place

country

A string corresponding to the country code of the place.

admin

A string with the name of the administrative area (‘Département’ for France and Region for other countries).

admin2

A string correponding to an administrative code ( ‘Département’ number for France)

postCode

A string corresponding to the ZIP code of location.

property admin: str | None

Return the admin of the place.

property admin2: str | None

Return the admin2 of the place.

property country: str

Return the country code of the place.

property insee: str | None

Return the INSEE ID of the place.

property latitude: float

Return the latitude of the place.

property longitude: float

Return the longitude of the place.

property name: str

Return the name of the place.

property postal_code: str | None

Return the postal code of the place.

class meteofrance_api.model.Rain(raw_data)

Class to access the results of ‘rain’ REST API request.

Parameters:

raw_data (RainData) –

position

A dictionary with metadata about the position of the forecast place.

updated_on

A timestamp as int corresponding to the latest update date.

forecast

A list of dictionaries to describe the following next hour rain forecast.

quality

An integer. Don’t know yet the usage.

property forecast: List[Dict[str, Any]]

Return the rain forecast.

next_rain_date_locale()

Estimate the date of the next rain in the Place timezone (Helper).

Returns:

A datetime instance representing the date estimation of the next rain within the next hour. If no rain is expected in the following hour ‘None’ is returned.

The datetime use the location timezone.

Return type:

datetime | None

property position: Dict[str, Any]

Return the position information of the rain forecast.

property quality: int

Return the quality of the rain forecast.

timestamp_to_locale_time(timestamp)

Convert timestamp in datetime with rain forecast location timezone (Helper).

Parameters:

timestamp (int) – An integer representing the UNIX timestamp.

Returns:

A datetime instance corresponding to the timestamp with the timezone of the

rain forecast location.

Return type:

datetime

property updated_on: int

Return the update timestamp of the rain forecast.

class meteofrance_api.model.WarningDictionary(raw_data)

A class to represent and manipulate the Meteo France meteorological dictionary data.

Parameters:

raw_data (WarningDictionaryData) –

get_phenomenon_name_by_id(phenomenon_id

int): Returns the name of the phenomenon for the given ID.

get_color_name_by_id(color_id

int): Returns the name of the color for the given ID.

get_color_by_id(color_id)

Retrieves a warning color based on its ID.

Parameters:

color_id (int) – The ID of the color.

Returns:

The the color object if found, otherwise returns None.

Return type:

ColorDictionaryEntry | None

get_color_name_by_id(color_id)

Retrieves the name of a warning color based on its ID.

Parameters:

color_id (int) – The ID of the color.

Returns:

The name of the color if found, otherwise returns None.

Return type:

str | None

get_phenomenon_by_id(phenomenon_id)

Retrieves a meteorological phenomenon based on its ID.

Parameters:

phenomenon_id (int) – The ID of the meteorological phenomenon.

Returns:

The phenomenon if found, otherwise returns None.

Return type:

PhenomenonDictionaryEntry | None

get_phenomenon_name_by_id(phenomenon_id)

Retrieves the name of a meteorological phenomenon based on its ID.

Parameters:

phenomenon_id (int) – The ID of the meteorological phenomenon.

Returns:

The name of the phenomenon if found, otherwise returns None.

Return type:

str | None