Skip to content

Climate data

get_climate(api_key, start_date, end_date, uf=None, geocode=None)

Retrieve historical climate data from the Mosqlimate API for a specific region and date range.

Parameters

api_key : str
    API key used to authenticate with the Mosqlimate service.
start_date : date or str
    Start date of the data range (as a `datetime.date` or ISO format string).
end_date : date or str
    End date of the data range (as a `datetime.date` or ISO format string).
uf : types.UF, optional
    The Brazilian state abbreviation (e.g., 'SP', 'MG'). If provided and `geocode` is not, filters by state.
geocode : int, optional
    IBGE geocode of a municipality. If provided, overrides `uf`.

Returns

pandas.DataFrame
    DataFrame containing daily climate data. Detailed descriptions of each column in the DataFrame can be found in the official API documentation:
    https://api.mosqlimate.org/docs/datastore/GET/climate/#output_items

Notes

  • Either uf or geocode must be provided to define the target location.

Examples

get_climate( ... api_key="your_api_key", ... start_date="2023-01-01", ... end_date="2023-01-31", ... geocode=3550308 ... )

Source code in mosqlient/datastore/_climate_get_impl.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def get_climate(
    api_key: str,
    start_date: date | str,
    end_date: date | str,
    uf: Optional[types.UF] = None,
    geocode: Optional[int] = None,
) -> pd.DataFrame:
    """
    Retrieve historical climate data from the Mosqlimate API for a specific region and date range.

    Parameters
    ----------
        api_key : str
            API key used to authenticate with the Mosqlimate service.
        start_date : date or str
            Start date of the data range (as a `datetime.date` or ISO format string).
        end_date : date or str
            End date of the data range (as a `datetime.date` or ISO format string).
        uf : types.UF, optional
            The Brazilian state abbreviation (e.g., 'SP', 'MG'). If provided and `geocode` is not, filters by state.
        geocode : int, optional
            IBGE geocode of a municipality. If provided, overrides `uf`.

    Returns
    -------
        pandas.DataFrame
            DataFrame containing daily climate data. Detailed descriptions of each column in the DataFrame can be found in the official API documentation:
            https://api.mosqlimate.org/docs/datastore/GET/climate/#output_items

    Notes
    -----
    - Either `uf` or `geocode` must be provided to define the target location.

    Examples
    --------
    >>> get_climate(
    ...     api_key="your_api_key",
    ...     start_date="2023-01-01",
    ...     end_date="2023-01-31",
    ...     geocode=3550308
    ... )
    """

    return pd.DataFrame(
        Climate.get(
            api_key=api_key,
            start=start_date,
            end=end_date,
            uf=uf,
            geocode=geocode,
        )
    )

get_climate_weekly(api_key, start, end, uf=None, geocode=None, macro_health_code=None)

Retrieve historical climate data weekly aggregated

Parameters

api_key : str
    API key used to authenticate with the Mosqlimate service.
start : str
    Start epiweek in YYYYWW format (example: 202501).
end : str
    End epiweek in YYYYWW format (example: 202501).
uf : str, optional
    The Brazilian state abbreviation (e.g., 'SP', 'MG').
geocode : int, optional
    IBGE geocode of a municipality.
macro_health_code : int, optional
    Macro Health IBGE geocode. Example: 1101

Returns

pandas.DataFrame
    DataFrame containing daily climate data. Detailed descriptions of
    each column in the DataFrame can be found in the official API
    documentation:
    https://api.mosqlimate.org/docs/datastore/GET/climate-weekly/

Notes

  • Either uf or geocode or macro_health_code must be provided.

Examples

get_climate_weekly( ... api_key="your_api_key", ... start="202401", ... end="202402", ... geocode=3550308 ... )

Source code in mosqlient/datastore/_climate_get_impl.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def get_climate_weekly(
    api_key: str,
    start: str,
    end: str,
    uf: Optional[types.UF] = None,
    geocode: Optional[int] = None,
    macro_health_code: Optional[int] = None,
) -> pd.DataFrame:
    """
    Retrieve historical climate data weekly aggregated

    Parameters
    ----------
        api_key : str
            API key used to authenticate with the Mosqlimate service.
        start : str
            Start epiweek in YYYYWW format (example: 202501).
        end : str
            End epiweek in YYYYWW format (example: 202501).
        uf : str, optional
            The Brazilian state abbreviation (e.g., 'SP', 'MG').
        geocode : int, optional
            IBGE geocode of a municipality.
        macro_health_code : int, optional
            Macro Health IBGE geocode. Example: 1101

    Returns
    -------
        pandas.DataFrame
            DataFrame containing daily climate data. Detailed descriptions of
            each column in the DataFrame can be found in the official API
            documentation:
            https://api.mosqlimate.org/docs/datastore/GET/climate-weekly/

    Notes
    -----
    - Either `uf` or `geocode` or `macro_health_code` must be provided.

    Examples
    --------
    >>> get_climate_weekly(
    ...     api_key="your_api_key",
    ...     start="202401",
    ...     end="202402",
    ...     geocode=3550308
    ... )
    """

    return pd.DataFrame(
        ClimateWeekly.get(
            api_key=api_key,
            start=start,
            end=end,
            uf=uf,
            geocode=geocode,
            macro_health_code=macro_health_code,
        )
    )