meteole 0.0.1__py3-none-any.whl

meteole/__init__.py

@@ -0,0 +1,28 @@
+import logging
+from importlib.metadata import version
+
+from meteole._arome import AromeForecast
+from meteole._arpege import ArpegeForecast
+from meteole._vigilance import Vigilance
+
+__all__ = ["AromeForecast", "ArpegeForecast", "Vigilance"]
+
+__version__ = version("meteole")
+
+
+def setup_logger():
+    """Setup logger with proper StreamHandler and formatter"""
+    logger = logging.getLogger(__name__)
+    logger.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler()
+    handler.setLevel(logging.INFO)
+
+    # formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    formatter = logging.Formatter("%(message)s")
+    handler.setFormatter(formatter)
+
+    return logger.addHandler(handler)
+
+
+logger = setup_logger()

meteole/_arome.py

@@ -0,0 +1,70 @@
+"""The interface for the observational data from the meteo-France API.
+
+See :
+- https://portail-api.meteofrance.fr/web/fr/api/arome
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import final
+
+from meteole.clients import BaseClient, MeteoFranceClient
+from meteole.forecast import Forecast
+
+logger = logging.getLogger(__name__)
+
+AVAILABLE_AROME_TERRITORY: list[str] = [
+    "FRANCE",
+    "NCALED",
+    "INDIEN",
+    "POLYN",
+    "GUYANE",
+    "ANTIL",
+]
+
+AROME_INSTANT_INDICATORS: list[str] = [
+    "GEOMETRIC_HEIGHT__GROUND_OR_WATER_SURFACE",
+    "BRIGHTNESS_TEMPERATURE__GROUND_OR_WATER_SURFACE",
+    "CONVECTIVE_AVAILABLE_POTENTIAL_ENERGY__GROUND_OR_WATER_SURFACE",
+    "WIND_SPEED_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "WIND_SPEED__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "RELATIVE_HUMIDITY__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "LOW_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "HIGH_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "MEDIUM_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "PRESSURE__GROUND_OR_WATER_SURFACE",
+    "TOTAL_PRECIPITATION_RATE__GROUND_OR_WATER_SURFACE",
+    "TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "U_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "U_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "V_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+]
+
+AROME_OTHER_INDICATORS: list[str] = [
+    "TOTAL_WATER_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_SNOW_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+]
+
+
+@final
+class AromeForecast(Forecast):
+    """Access the AROME numerical forecast data."""
+
+    # Model constants
+    MODEL_NAME: str = "arome"
+    INDICATORS: list[str] = AROME_INSTANT_INDICATORS + AROME_OTHER_INDICATORS
+    INSTANT_INDICATORS: list[str] = AROME_INSTANT_INDICATORS
+    BASE_ENTRY_POINT: str = "wcs/MF-NWP-HIGHRES-AROME"
+    DEFAULT_TERRITORY: str = "FRANCE"
+    DEFAULT_PRECISION: float = 0.01
+    CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
+
+    def _validate_parameters(self):
+        """Assert the parameters are valid."""
+        if self.precision not in [0.01, 0.025]:
+            raise ValueError("Parameter `precision` must be in (0.01, 0.025). It is inferred from argument `territory`")
+        if self.territory not in AVAILABLE_AROME_TERRITORY:
+            raise ValueError(f"Parameter `territory` must be in {AVAILABLE_AROME_TERRITORY}")

meteole/_arpege.py

@@ -0,0 +1,119 @@
+"""The interface for the observational data from the meteo-France API.
+
+See :
+- https://portail-api.meteofrance.fr/web/fr/api/arpege
+"""
+
+from __future__ import annotations
+
+from typing import Any, final
+
+from meteole.clients import BaseClient, MeteoFranceClient
+from meteole.forecast import Forecast
+
+AVAILABLE_ARPEGE_TERRITORY: list[str] = ["EUROPE", "GLOBE", "ATOURX", "EURAT"]
+
+ARPEGE_INSTANT_INDICATORS: list[str] = [
+    "GEOMETRIC_HEIGHT__GROUND_OR_WATER_SURFACE",
+    "BRIGHTNESS_TEMPERATURE__GROUND_OR_WATER_SURFACE",
+    "CONVECTIVE_AVAILABLE_POTENTIAL_ENERGY__GROUND_OR_WATER_SURFACE",
+    "SPECIFIC_CLOUD_ICE_WATER_CONTENT__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "SPECIFIC_CLOUD_ICE_WATER_CONTENT__ISOBARIC_SURFACE",
+    "WIND_SPEED_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "WIND_SPEED__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "WIND_SPEED__ISOBARIC_SURFACE",
+    "RELATIVE_HUMIDITY__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "RELATIVE_HUMIDITY__ISOBARIC_SURFACE",
+    "PLANETARY_BOUNDARY_LAYER_HEIGHT__GROUND_OR_WATER_SURFACE",
+    "LOW_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "HIGH_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "MEDIUM_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+    "PRESSURE__GROUND_OR_WATER_SURFACE",
+    "PRESSURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "PRESSURE__MEAN_SEA_LEVEL",
+    "ABSOLUTE_VORTICITY__ISOBARIC_SURFACE",
+    "DEW_POINT_TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "DEW_POINT_TEMPERATURE__ISOBARIC_SURFACE",
+    "TURBULENT_KINETIC_ENERGY__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "TURBULENT_KINETIC_ENERGY__ISOBARIC_SURFACE",
+    "MAXIMUM_TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "MINIMUM_TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "PSEUDO_ADIABATIC_POTENTIAL_TEMPERATURE__ISOBARIC_SURFACE",
+    "POTENTIAL_VORTICITY__ISOBARIC_SURFACE",
+    "TEMPERATURE__GROUND_OR_WATER_SURFACE",
+    "TEMPERATURE__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "TEMPERATURE__ISOBARIC_SURFACE",
+    "U_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "U_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "U_COMPONENT_OF_WIND__ISOBARIC_SURFACE",
+    "U_COMPONENT_OF_WIND__POTENTIAL_VORTICITY_SURFACE_1500",
+    "U_COMPONENT_OF_WIND__POTENTIAL_VORTICITY_SURFACE_2000",
+    "VERTICAL_VELOCITY_PRESSURE__ISOBARIC_SURFACE",
+    "V_COMPONENT_OF_WIND_GUST__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "V_COMPONENT_OF_WIND__SPECIFIC_HEIGHT_LEVEL_ABOVE_GROUND",
+    "V_COMPONENT_OF_WIND__ISOBARIC_SURFACE",
+    "V_COMPONENT_OF_WIND__POTENTIAL_VORTICITY_SURFACE_1500",
+    "V_COMPONENT_OF_WIND__POTENTIAL_VORTICITY_SURFACE_2000",
+    "GEOPOTENTIAL__ISOBARIC_SURFACE",
+    "TOTAL_CLOUD_COVER__GROUND_OR_WATER_SURFACE",
+]
+
+ARPEGE_OTHER_INDICATORS: list[str] = [
+    "TOTAL_WATER_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_SNOW_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "TOTAL_PRECIPITATION__GROUND_OR_WATER_SURFACE",
+    "DOWNWARD_SHORT_WAVE_RADIATION_FLUX__GROUND_OR_WATER_SURFACE",
+    "SHORT_WAVE_RADIATION_FLUX__GROUND_OR_WATER_SURFACE",
+]
+
+
+@final
+class ArpegeForecast(Forecast):
+    """Access the ARPEGE numerical forecast data."""
+
+    # Model constants
+    MODEL_NAME: str = "arpege"
+    INDICATORS: list[str] = ARPEGE_INSTANT_INDICATORS + ARPEGE_OTHER_INDICATORS
+    INSTANT_INDICATORS: list[str] = ARPEGE_INSTANT_INDICATORS
+    BASE_ENTRY_POINT: str = "wcs/MF-NWP-GLOBAL-ARPEGE"
+    DEFAULT_TERRITORY: str = "EUROPE"
+    RELATION_TERRITORY_TO_PREC_ARPEGE: dict[str, float] = {"EUROPE": 0.1, "GLOBE": 0.25, "ATOURX": 0.1, "EURAT": 0.05}
+    CLIENT_CLASS: type[BaseClient] = MeteoFranceClient
+
+    def __init__(
+        self,
+        client: BaseClient | None = None,
+        *,
+        territory: str = "EUROPE",
+        **kwargs: Any,
+    ):
+        """
+        Initializes an ArpegeForecast object for accessing ARPEGE forecast data.
+
+        The `precision` of the forecast is inferred from the specified `territory`.
+
+        Args:
+            territory (str, optional): The ARPEGE territory to fetch. Defaults to "EUROPE".
+            api_key (str | None, optional): The API key for authentication. Defaults to None.
+            token (str | None, optional): The API token for authentication. Defaults to None.
+            application_id (str | None, optional): The Application ID for authentication. Defaults to None.
+            cache_dir (str | None, optional): Path to the cache directory. Defaults to None.
+                If not provided, the cache directory is set to "/tmp/cache".
+
+        Notes:
+            - See `MeteoFranceClient` for additional details on the parameters `api_key`, `token`,
+                and `application_id`.
+            - Available territories are listed in the `AVAILABLE_TERRITORY` constant.
+
+        """
+        super().__init__(
+            client=client,
+            territory=territory,
+            precision=self.RELATION_TERRITORY_TO_PREC_ARPEGE[territory],
+            **kwargs,
+        )
+
+    def _validate_parameters(self):
+        """Assert the parameters are valid."""
+        if self.territory not in AVAILABLE_ARPEGE_TERRITORY:
+            raise ValueError(f"The parameter precision must be in {AVAILABLE_ARPEGE_TERRITORY}")

meteole/_vigilance.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import logging
+from io import BytesIO
+from typing import Any, final
+
+import matplotlib.image as mpimg
+import matplotlib.pyplot as plt
+import pandas as pd
+from requests import Response
+
+from meteole.clients import BaseClient, MeteoFranceClient
+from meteole.errors import MissingDataError
+
+logger = logging.getLogger(__name__)
+
+
+@final
+class Vigilance:
+    """Wrapper around the meteo-France API for the vigilance data.
+    Ressources are:
+    - textesvigilance
+    - cartevigilance
+
+    Documentation
+    -------------
+    See:
+    - https://portail-api.meteofrance.fr/web/fr/api/DonneesPubliquesVigilance
+    - https://donneespubliques.meteofrance.fr/client/document/descriptiftechnique_vigilancemetropole_
+        donneespubliques_v4_20230911_307.pdf
+    """
+
+    API_VERSION: str = "v1"
+    VIGILANCE_BASE_PATH: str = "DPVigilance/"
+    PHENOMENO_IDS: dict[str, str] = {
+        "1": "wind",
+        "2": "rain",
+        "3": "storm",
+        "4": "flood",
+        "5": "snow_ice",
+        "6": "heat_wave",
+        "7": "extreme_cold",
+        "8": "avalanches",
+        "9": "waves_submergence",
+    }
+
+    def __init__(
+        self,
+        client: BaseClient | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """TODO"""
+        if client is not None:
+            self._client = client
+        else:
+            # Try to instantiate it (can be user friendly)
+            self._client = MeteoFranceClient(**kwargs)
+
+    def get_bulletin(self) -> dict[str, Any]:
+        """
+        Retrieve the vigilance bulletin.
+
+        Returns:
+            dict: a Dict representing the vigilance bulletin
+        """
+
+        path: str = self.VIGILANCE_BASE_PATH + self.API_VERSION + "/textesvigilance/encours"
+        logger.debug(f"GET {path}")
+
+        try:
+            resp: Response = self._client.get(path)
+            return resp.json()
+
+        except MissingDataError as e:
+            if "no matching blob" in e.message:
+                logger.warning("Ongoing vigilance requires no publication")
+            else:
+                logger.error(f"Unexpected error: {e}")
+            return {}
+        except Exception as e:
+            logger.error(f"Unexpected error: {e}")
+            return {}
+
+    def get_map(self) -> dict[str, Any]:
+        """
+        Get the vigilance map with predicted risk displayed.
+
+        Returns:
+            dict: a Dict with the predicted risk.
+        """
+        path: str = self.VIGILANCE_BASE_PATH + self.API_VERSION + "/cartevigilance/encours"
+        logger.debug(f"GET {path}")
+
+        resp: Response = self._client.get(path)
+
+        return resp.json()
+
+    def get_phenomenon(self) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Get risk prediction by phenomenon and by domain.
+
+        Returns:
+            pd.DataFrame: a DataFrame with phenomenon by id
+            pd.DataFrame: a DataFrame with phenomenon by domain
+        """
+        df_carte = pd.DataFrame(self.get_map())
+        periods_data = df_carte.loc["periods", "product"]
+        df_periods = pd.json_normalize(periods_data)
+
+        df_j = df_periods[df_periods["echeance"] == "J"]
+        df_j1 = df_periods[df_periods["echeance"] == "J1"]
+
+        df_phenomenon_j = pd.json_normalize(df_j["per_phenomenon_items"].explode())
+        df_phenomenon_j1 = pd.json_normalize(df_j1["per_phenomenon_items"].explode())
+        df_phenomenon_j["echeance"] = "J"
+        df_phenomenon_j1["echeance"] = "J1"
+
+        df_phenomenon = pd.concat([df_phenomenon_j, df_phenomenon_j1]).reset_index(drop=True)
+        df_phenomenon["phenomenon_libelle"] = df_phenomenon["phenomenon_id"].map(self.PHENOMENO_IDS)
+
+        df_timelaps_j = pd.json_normalize(df_j["timelaps.domain_ids"].explode())
+        df_timelaps_j1 = pd.json_normalize(df_j1["timelaps.domain_ids"].explode())
+        df_timelaps_j["echeance"] = "J"
+        df_timelaps_j1["echeance"] = "J1"
+
+        df_timelaps = pd.concat([df_timelaps_j, df_timelaps_j1]).reset_index(drop=True)
+
+        return df_phenomenon, df_timelaps
+
+    def get_vignette(self) -> None:
+        """
+        Get png.
+        """
+        path: str = self.VIGILANCE_BASE_PATH + self.API_VERSION + "/vignettenationale-J-et-J1/encours"
+
+        logger.debug(f"GET {path}")
+        resp: Response = self._client.get(path)
+
+        if resp.status_code == 200:
+            content: str | None = resp.headers.get("content-disposition")
+            if content is not None:
+                filename: str = content.split("filename=")[1]
+                filename = filename.strip('"')
+
+            with open(filename, "wb") as f:
+                f.write(resp.content)
+
+            img = mpimg.imread(BytesIO(resp.content), format="png")
+            plt.imshow(img)
+            plt.axis("off")
+            plt.show()
+        else:
+            resp.raise_for_status()

meteole/clients.py

@@ -0,0 +1,228 @@
+"""API client classes"""
+
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import requests
+from requests import Response, Session
+
+from meteole.errors import GenericMeteofranceApiError, MissingDataError
+
+logger = logging.getLogger(__name__)
+
+
+class HttpStatus(int, Enum):
+    """Http status codes"""
+
+    OK: int = 200
+    BAD_REQUEST: int = 400
+    UNAUTHORIZED: int = 401
+    FORBIDDEN: int = 403
+    NOT_FOUND: int = 404
+    TOO_MANY_REQUESTS: int = 429
+    INTERNAL_ERROR: int = 500
+    BAD_GATEWAY: int = 502
+    UNAVAILABLE: int = 503
+    GATEWAY_TIMEOUT: int = 504
+
+
+class BaseClient(ABC):
+    """TODO"""
+
+    @abstractmethod
+    def get(self, path: str, *, params: dict[str, Any] | None = None, max_retries: int = 5) -> Response:
+        """TODO"""
+        raise NotImplementedError
+
+
+class MeteoFranceClient(BaseClient):
+    """A client for interacting with the Meteo France API.
+
+    This class handles the connection setup and token refreshment required for
+    authenticating and making requests to the Meteo France API.
+
+    Attributes:
+        api_key (str | None): The API key for accessing the Meteo France API.
+        token (str | None): The authentication token for accessing the API.
+        application_id (str | None): The application ID used for identification.
+        verify (Path | None): The path to a file or directory of trusted CA certificates for SSL verification.
+    """
+
+    # Class constants
+    API_BASE_URL: str = "https://public-api.meteofrance.fr/public/"
+    TOKEN_URL: str = "https://portail-api.meteofrance.fr/token"
+    GET_TOKEN_TIMEOUT_SEC: int = 10
+    INVALID_JWT_ERROR_CODE: str = "900901"
+    RETRY_DELAY_SEC: int = 5
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        api_key: str | None = None,
+        application_id: str | None = None,
+        certs_path: Path | None = None,
+    ) -> None:
+        """
+        Initializes the MeteoFranceClient object.
+
+        Args:
+            api_key (str | None): The API key for accessing the Meteo France API.
+            token (str | None): The authentication token for accessing the API.
+            application_id (str | None): The application ID used for identification.
+            verify (Path | None): The path to a file or directory of trusted CA certificates for SSL verification.
+        """
+        self._token = token
+        self._api_key = api_key
+        self._application_id = application_id
+        self._verify: str | None = str(certs_path) if certs_path is not None else None
+
+        self._session = Session()
+
+        self._token_expired: bool = False
+
+        # Initialize the requests session object
+        self._connect()
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None, max_retries: int = 5) -> Response:
+        """
+        Makes a GET request to the API with optional retries.
+
+        Args:
+            url (str): The URL to send the GET request to.
+            params (dict, optional): The query parameters to include in the request. Defaults to None.
+            max_retries (int, optional): The maximum number of retry attempts in case of failure. Defaults to 5.
+
+        Returns:
+            requests.Response: The response returned by the API.
+
+        """
+        url: str = self.API_BASE_URL + path
+        attempt: int = 0
+        logger.debug(f"GET {url}")
+
+        while attempt < max_retries:
+            # HTTP GET request
+            resp: Response = self._session.get(url, params=params, verify=self._verify)
+
+            if resp.status_code == HttpStatus.OK:
+                logger.debug("Successful request")
+                return resp
+
+            elif self._is_token_expired(resp):
+                logger.info("Token expired, requesting a new one")
+
+                # Refresh the cached token
+                self._token = self._get_token()
+
+                # Reconnect with the new token
+                self._connect()
+
+            elif resp.status_code == HttpStatus.FORBIDDEN:
+                logger.error("Access forbidden")
+                raise GenericMeteofranceApiError(resp.text)
+
+            elif resp.status_code == HttpStatus.BAD_REQUEST:
+                logger.error("Parameter error")
+                raise GenericMeteofranceApiError(resp.text)
+
+            elif resp.status_code == HttpStatus.NOT_FOUND:
+                logger.error("Missing data")
+                raise MissingDataError(resp.text)
+
+            elif (
+                resp.status_code == HttpStatus.BAD_GATEWAY
+                or resp.status_code == HttpStatus.UNAVAILABLE
+                or resp.status_code == HttpStatus.GATEWAY_TIMEOUT
+            ):
+                logger.error("Service not available")
+                time.sleep(self.RETRY_DELAY_SEC)
+                attempt += 1
+                logger.info(f"Retrying... Attempt {attempt} of {max_retries}")
+                continue
+
+        raise GenericMeteofranceApiError(f"Failed to get a successful response from API after {attempt} retries")
+
+    def _connect(self):
+        """Connect to the MeteoFrance API.
+
+        If the API key is provided, it is used to authenticate the user.
+        If the token is provided, it is used to authenticate the user.
+        If the application ID is provided, a token is requested from the API.
+        """
+        if self._api_key is None and self._token is None:
+            if self._application_id is None:
+                raise ValueError("api_key or token or application_id must be provided")
+
+            # Connection with application_id
+            self._token = self._get_token()
+
+        if self._api_key is not None:
+            logger.debug("using api key")
+
+            # Connection with api_key
+            self._session.headers.update({"apikey": self._api_key})
+
+        else:
+            logger.debug("using token")
+
+            # Connection with token
+            self._session.headers.update({"Authorization": f"Bearer {self._token}"})
+
+    def _get_token(self) -> str:
+        """request a token from the meteo-France API.
+
+        The token lasts 1 hour, and is used to authenticate the user.
+        If a new token is requested before the previous one expires, the previous one is invalidated.
+        A local cache is used to avoid requesting a new token at each run of the script.
+        """
+        if self._token_expired is False and self._token is not None:
+            # Use cached token
+            token: str = self._token
+
+        elif self._token_expired is True and self._application_id is None:
+            # Can do nothing
+            raise ValueError("The 'application_id' is unknown, can't get a new token")
+
+        else:
+            # Retrieve a new token
+
+            # Seems useless (TODO remove if it's True):
+            # params: dict[str, str] = {"grant_type": "client_credentials"}
+            headers: dict[str, str] = {"Authorization": "Basic " + str(self._application_id)}
+
+            resp: Response = requests.post(
+                self.TOKEN_URL,
+                # params=params,
+                headers=headers,
+                timeout=self.GET_TOKEN_TIMEOUT_SEC,
+                verify=self._verify,
+            )
+            token = resp.json()["access_token"]
+
+        return token
+
+    def _is_token_expired(self, response: Response) -> bool:
+        """Check if the token is expired.
+
+        Returns
+        -------
+        bool
+            True if the token is expired, False otherwise.
+        """
+        result: bool = False
+
+        if response.status_code == HttpStatus.UNAUTHORIZED and "application/json" in response.headers["Content-Type"]:
+            error: str = response.json()["code"]
+
+            if error == self.INVALID_JWT_ERROR_CODE:
+                result = True
+                self._token_expired = True
+
+        return result

meteole/errors.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import xmltodict
+
+
+class GenericMeteofranceApiError(Exception):
+    """Exception raised errors in the input parameters where a required field is missing.
+
+    Args:
+        message (str): Human-readable string descipting the exceptetion.
+        description (str): More detailed description of the error."""
+
+    def init(self, text: str) -> None:
+        """Initialize the exception with an error message parsed from an XML
+        string.
+
+        Args:
+            text (str): XML string containing the error details,
+                expected to follow a specific schema with 'am:fault' as the root
+                element and 'am:message' and 'am:description' as child elements."""
+
+        # parse the error message with xmltodict
+        data = xmltodict.parse(text)
+        message = data["am:fault"]["am:message"]
+        description = data["am:fault"]["am:description"]
+        self.message = f"{message}\n {description}"
+        super().__init__(self.message)
+
+
+class MissingDataError(Exception):
+    """Exception raised errors in the input data is missing"""
+
+    def init(self, text: str) -> None:
+        """Initialize the exception with an error message parsed from an XML
+        string.
+
+        Args:
+            text (str): XML string containing the error details,
+                expected to follow a specific schema with 'am:fault' as the root
+                element and 'am:message' and 'am:description' as child elements."""
+
+        # parse the error message with xmltodict
+        try:
+            data = xmltodict.parse(text)
+            exception = data["mw:fault"]["mw:description"]["ns0:ExceptionReport"]["ns0:Exception"]
+            code = exception["@exceptionCode"]
+            locator = exception["@locator"]
+            exception_text = exception["ns0:ExceptionText"]
+            message = f"Error code: {code}\nLocator: {locator}\nText: {exception_text}"
+        except Exception:
+            message = text
+        self.message = message
+        super().__init__(self.message)