@spec get_airport_weather(String.t()) ::
  {:ok, Brasilapi.Cptec.AirportConditions.t()} | {:error, map()}

Fetches current weather conditions at a specific airport.

Returns meteorological data from the weather station at the specified airport.

Parameters

• icao_code: ICAO airport code (4 uppercase letters, e.g., "SBGR", "SBAR")

Examples

iex> Brasilapi.Cptec.API.get_airport_weather("SBGR")
{:ok, %Brasilapi.Cptec.AirportConditions{codigo_icao: "SBGR", temp: 28, ...}}

iex> Brasilapi.Cptec.API.get_airport_weather("invalid")
{:error, %{message: "ICAO code must be exactly 4 uppercase letters"}}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/airportcurrentcondicao(/cptec/v1/clima/aeroporto/:icaoCode)

@spec get_capitals_weather() ::
  {:ok, [Brasilapi.Cptec.AirportConditions.t()]} | {:error, map()}

Fetches current weather conditions for all Brazilian state capitals.

Returns meteorological data from airport weather stations in each capital city.

Examples

iex> Brasilapi.Cptec.API.get_capitals_weather()
{:ok, [%Brasilapi.Cptec.AirportConditions{codigo_icao: "SBGR", temp: 28, ...}, ...]}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/Condi%C3%A7%C3%B5esatuaisnascapitais(/cptec/v1/clima/capital)

@spec get_city_forecast(integer()) ::
  {:ok, Brasilapi.Cptec.CityForecast.t()} | {:error, map()}

Fetches weather forecast for a city (1 day by default).

Returns the weather forecast for the specified city code.

Parameters

• city_code: City code obtained from search_cities/1 (integer)

Examples

iex> Brasilapi.Cptec.API.get_city_forecast(244)
{:ok, %Brasilapi.Cptec.CityForecast{cidade: "São Paulo", estado: "SP", clima: [...]}}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/climapredictionwithoutdays(/cptec/v1/clima/previsao/:cityCode)

@spec get_city_forecast(integer(), integer()) ::
  {:ok, Brasilapi.Cptec.CityForecast.t()} | {:error, map()}

Fetches weather forecast for a city for multiple days (up to 6 days).

Returns the weather forecast for the specified city code for the given number of days.

Parameters

• city_code: City code obtained from search_cities/1 (integer)
• days: Number of days for the forecast (1-6)

Examples

iex> Brasilapi.Cptec.API.get_city_forecast(244, 3)
{:ok, %Brasilapi.Cptec.CityForecast{cidade: "São Paulo", estado: "SP", clima: [...]}}

iex> Brasilapi.Cptec.API.get_city_forecast(244, 7)
{:error, %{message: "Days parameter must be between 1 and 6"}}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/upto14daysprediction(/cptec/v1/clima/previsao/:cityCode/:days)

@spec get_ocean_forecast(integer()) ::
  {:ok, Brasilapi.Cptec.OceanForecast.t()} | {:error, map()}

Fetches ocean forecast for a coastal city (1 day by default).

Returns the ocean/wave forecast for the specified city code.

Parameters

• city_code: City code obtained from search_cities/1 (integer)

Examples

iex> Brasilapi.Cptec.API.get_ocean_forecast(241)
{:ok, %Brasilapi.Cptec.OceanForecast{cidade: "Rio de Janeiro", estado: "RJ", ondas: [...]}}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/ondaspredictionwithoutdays(/cptec/v1/ondas/:cityCode)

@spec get_ocean_forecast(integer(), integer()) ::
  {:ok, Brasilapi.Cptec.OceanForecast.t()} | {:error, map()}

Fetches ocean forecast for a coastal city for multiple days (up to 6 days).

Returns the ocean/wave forecast for the specified city code for the given number of days.

Parameters

• city_code: City code obtained from search_cities/1 (integer)
• days: Number of days for the forecast (1-6)

Examples

iex> Brasilapi.Cptec.API.get_ocean_forecast(241, 3)
{:ok, %Brasilapi.Cptec.OceanForecast{cidade: "Rio de Janeiro", estado: "RJ", ondas: [...]}}

iex> Brasilapi.Cptec.API.get_ocean_forecast(241, 7)
{:error, %{message: "Days parameter must be between 1 and 6"}}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/ondaspredictionupto6days(/cptec/v1/ondas/:cityCode/:days)

@spec list_cities() :: {:ok, [Brasilapi.Cptec.City.t()]} | {:error, map()}

Lists all cities available in CPTEC services.

Returns a complete listing of all cities with their CPTEC codes. The CPTEC code is used in other endpoints for weather and ocean forecasts.

Note: The CPTEC web service can be unstable. If you don't find a specific city in the complete listing, try searching by part of its name using search_cities/1.

Examples

iex> Brasilapi.Cptec.API.list_cities()
{:ok, [%Brasilapi.Cptec.City{nome: "São Paulo", estado: "SP", id: 244}, ...]}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/listcities(/cptec/v1/cidade)

@spec search_cities(String.t()) :: {:ok, [Brasilapi.Cptec.City.t()]} | {:error, map()}

Searches for cities by name.

Returns a list of cities matching the search term along with their CPTEC codes. The CPTEC code is used in other endpoints for weather and ocean forecasts.

Parameters

• city_name: Name or partial name of the city to search for (string)

Examples

iex> Brasilapi.Cptec.API.search_cities("São Paulo")
{:ok, [%Brasilapi.Cptec.City{nome: "São Paulo", estado: "SP", id: 244}]}

iex> Brasilapi.Cptec.API.search_cities("Chiforímpola")
{:ok, [%Brasilapi.Cptec.City{nome: "São Benedito", estado: "CE", id: 4750}]}

API Reference

https://brasilapi.com.br/docs#tag/CPTEC/operation/searchcities(/cptec/v1/cidade/:cityName)