Feature documentation

This section is a documentation of the weatherly API interface.

Version informations

You can gather version info in two ways:

weatherly.__version__

Version of the project following the PEP 440 standard.

For example, this can be 1.2.0a2

weatherly.version_info

A named tuple containing version informations. Similiar to sys.version_info

Clients

Client

Attributes

• aqi
• dt
• end_dt
• hour
• kwargs
• lang
• tides

Methods

• defbulk_request
• @event
• defget_astronomical_data
• defget_current_weather
• defget_forecast_data
• defget_future_data
• defget_historical_data
• defget_ip_data
• defget_locations
• defget_marine_data
• defget_sports_data
• defon_error
• defset_language

class weatherly.Client(api_key: str, lang: Optional[Union[str, Languages]] = None, dt: Optional[int] = None, end_dt: Optional[int] = None, hour: Optional[int] = None, aqi: bool = False, tides: bool = False, **kwargs: Dict[str, Any])

A WeatherAPI.com client for fetching various weather information

Parameters:

• api_key (str) – API Key used to authenticate when sending requests

• lang (Optional[ Union[str, Languages] ]) – Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages. If None then the default language is used (English)

• dt (Optional[int]) – Restrict date output for Forecast and History API method. (Required for History and Future API)

• end_dt (Optional[int]) – Restrict date output for History API method. Only works for API on Pro plan and above. (Available for History API)

• hour (Optional[int]) – Restricting forecast or history output to a specific hour in a given day.

• aqi (bool) – Enable/Disable Air Quality data in forecast API output. Defaults to “no”.

• tides (bool) – Enable/Disable Tide data in Marine API output. Defaults to “no”.

• kwargs (Dict[str, Any]) – Additional keyword arguments passed by default to requests made by the client

lang

Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages. If None then the default language is used (English)

Type:

Optional[Languages]

dt

Restricted date output for Forecast and History API method. (Required for History and Future API)

Type:

Optional[int]

end_dt

Restricted date output for History API method. Only works for API on Pro plan and above.

Type:

Optional[int]

hour

Restricted forecast or history output to a specific hour in a given day.

Type:

Optional[int]

aqi

Indicates if Air Quality data has been enabled

Type:

bool

tides

Indicates if tides data in the Marine API has been enabled

Type:

bool

kwargs

Additional keyword arguments passed by default to requests made by the client

Type:

Dict[str, Any]

@event

A decorator that turns a function into an event. For example

import weatherly
client = weatherly.Client(api_key=...)

@client.event
def on_error(func, exc):
    print(f"An error occured! Function: {func}, error: {str(exc)}")

In the example above, by adding @client.event the on_error function has turned into an error handler function

Important

The function SHOULD NOT be a coroutine function!

bulk_request(data: BulkRequest, **kwargs) → BulkResponse

A bulk request allowing you to retrieve data for multiple locations at once

Note

Bulk requests only work on one endpoint, so you cannot use it to get data from multiple endpoints e.g. forecast and current weather

Note

To do a bulk request you should build a BulkRequest object and pass it as a data parameter first

Parameters:

• data (BulkRequest) –

  Data for the bulk request. To build this class consider using two following methods:

  import weatherly
  
  # 1. by BulkRequest.build
  req = BulkRequest.build(("my-id", "London"), ("second", "Paris"), endpoint=weatherly.WeatherEndpoints.CURRENT_WEATHER)
  
  # 2. by manually setting bulk request params
  bulk = BulkRequest()
  bulk.set_endpoint(weatherly.WeatherEndpoints.FORECAST)
  bulk.add_query(id="my-id", location="Paris")
  bulk.add_query(id="second", location="London")
  

• kwargs (Dict[str, Any]) – Additional keyword arguments. You need to think of them manually, look for them in other methods and pass them in key=val schema. For example: client.bulk_request(req, aqi=True, days=7)

Returns:

BulkResponse – Results of the bulk request

Raises:

• NoLocationFound – Raised when no matching location was found.

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_astronomical_data(query: str, date: str, **kwargs: Dict[str, Any]) → AstronomicalData

Get astronomical data from Astronomy API

Parameters:

• query (str) – Query string, location you want to get forecast data for

• date (str) – Date in format yyyy-MM-dd and on or after 1st Jan, 2010 (2010-01-01)

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

AstronomicalData – Fetched astronomical data as a class.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_current_weather(query: str, *, lang: Optional[Union[str, Languages]] = None, aqi: Optional[bool] = None, **kwargs: Dict[str, Any]) → CurrentWeatherData

Get current weather data

Parameters:

• query (str) – Query string - location you want to get weather data for

• lang (Optional[Union[str, Languages]]) – Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages.

• aqi (Optional[bool]) – Enable/Disable Air Quality data in forecast API output. If nothing is passed, then it defaults to client default value.

• kwargs (Dict[str, Any]) – Additional keyword arguments to request

Returns:

CurrentWeatherData – Current weather data class

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_forecast_data(query: str, days: int, *, aqi: Optional[bool] = None, alerts: Optional[bool] = None, lang: Optional[Union[str, Languages]] = None, **kwargs: Dict[str, Any]) → ForecastData

Get forecast data from Forecast API

Parameters:

• query (str) – Query string, location you want to get forecast data for

• days (int) – Number of days of weather forecast. Value ranges from 1 to 10

• aqi (Optional[bool]) – Enable/Disable Air Quality data. Defaults to None (will use client’s default)

• alerts (Optional[bool]) – Enable/Disable alerts data. Defaults to None (will use client’s default)

• lang (Optional[Union[:class`str`, :class`Languages`]]) – Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages.

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

ForecastData – Fetched forecast data as a class.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_future_data(query: str, date: str, *, lang: Optional[Union[str, Languages]] = None, **kwargs: Dict[str, Any]) → FutureData

Retrieve future data for given day and query. Uses Future API.

Parameters:

• query (str) – Query string, location you want to get forecast data for

• date (str) – A date string in format yyyy-mm-dd representing the day you want to get data for

• lang (Optional[Union[:class`str`, :class`Languages`]]) – Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages.

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

FutureData – Future data for given day and query.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

• InvalidDate – Raised when the date parameter is invalid (doesn’t match the format or isn’t a date after today)

get_historical_data(query: str, date: str, *, aqi: Optional[bool] = None, alerts: Optional[bool] = None, lang: Optional[Union[str, Languages]] = None, **kwargs: Dict[str, Any]) → ForecastData

Retrieve historical data for given day and query. Uses History API.

Parameters:

• query (str) – Query string, location you want to get forecast data for

• date (str) – A date string in format yyyy-mm-dd representing the day you want to get data for

• aqi (Optional[bool]) – Enable/Disable Air Quality data. Defaults to None (will use client’s default)

• alerts (Optional[bool]) – Enable/Disable alerts data. Defaults to None (will use client’s default)

• lang (Optional[Union[:class`str`, :class`Languages`]]) – Language from the Languages enum or a string representing the language or language code (preferably). To get a list of languages visit Languages.

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

ForecastData – Forecast data for given day and query.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

• InvalidDate – Raised when the date parameter is invalid (doesn’t match the format or isn’t a date before (or) today)

get_ip_data(ip_address: str, **kwargs: Dict[str, Any]) → IPData

Look for data for the given IP address.

Parameters:

• ip_address (str) – IP address you want to get data for. Can be ipv4 or ipv6

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

IPData – Fetched IP data as a class.

Raises:

• NoLocationFound – Raised when either IP address was invalid or no matching location was found.

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_locations(query: str)

Get locations for given query

Parameters:

query (str) – Query string, a location you are searching for

Returns:

List[LocationData] – A list of LocationData classes.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_marine_data(query: str, *, tides: Optional[bool] = None, **kwargs: Dict[str, Any]) → MarineData

Get marine data from Marine API

Parameters:

• query (str) – Query string, location you want to get forecast data for

• tides (Optional[bool]) – Enable/disable tide data.

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

MarineData – Fetched marine data as a class.

Raises:

• NoLocationFound – Raised when no location for given query was found

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

get_sports_data(query: str, **kwargs: Dict[str, Any]) → SportsData

Get sports data for a given query. Uses Sports API.

Parameters:

• query (str) – Query string, location you want to get sports data for

• kwargs (Dict[str, Any]) – Additional keyword arguments that will be passed to the request.

Returns:

SportsData – Retrieved sports data as a class.

Raises:

• NoLocationFound – Raised when no matching location was found.

• InvalidAPIKey – Raised when the API key is invalid

• APILimitExceeded – Raised when API key calls limit was exceeded

• APIKeyDisabled – Raised when API key is disabled

• AccessDenied – Raised when access to given resource was denied

• InternalApplicationError – Raised when there was a very rare internal application error

• WeatherAPIException – Raised when something else went wrong, that does not have a specific exception class.

on_error(func: str, exc: Exception) → None

Default implementation of error handling in this client.

Parameters:

• func (str) – Name of function that raised an error

• exc (Exception) – Exception that was caught during func callback

set_language(lang: Union[str, Languages]) → Optional[Languages]

Set client’s language when requesting data.

Parameters:

lang (Union[str, Languages]) – Language to set. Can be either a string that is lanuage’s name or code or a Languages enum object.

Returns:

Optional[Languages] – An enum class representing the language of the client. Is None when something went wrong and the language was not set.

Event reference

Weatherly provides an easy to use event system. There are two ways to register an event function.

First method is to use Client.event() decorator.

import weatherly
client = weatherly.Client("your-api-key")

@client.event
def on_error(func_name, exception):
    print(f"Exception occured in {func_name}!")

Second way is to make a custom client class inheriting from Client.

import weatherly

class CustomClient(weatherly.Client):
    def __init__(self, api_key):
        super().__init__(api_key=api_key)

    def on_error(func_name, exception):
        print(f"Exception occured in {func_name}!")

Important

All event functions mustn’t be coroutines. A ValueError is raised when a function is a coroutine.

Error handling

weatherly.on_error(func, exc)

Called when an error occured during calling a client method

Parameters:

• func (str) – The function name where the exception occured.

• exc (Inherits from Exception) – The exception that occured

API calls

weatherly.on_api_call_successful(request, response)

Called when an API call (e.g. Client.get_current_weather()) was successfully done.

Parameters:

• request (str) – The request URL e.g. https://api.weatherapi.com/v1/endpoint?param=value

• response (requests.Response) – Response class

Enums

Languages

class weatherly.Languages

Languages - an enum representing languages available for use in the WeatherAPI requests.

Attributes are languages and language codes

Arabic

Language code: ar

Type:

str

Bengali

Language code: bn

Type:

str

Bulgarian

Language code: bg

Type:

str

ChineseSimplified

Language code: zh

Type:

str

ChineseTraditional

Language code: zh_tw

Type:

str

Czech

Language code: cs

Type:

str

Danish

Language code: da

Type:

str

Dutch

Language code: nl

Type:

str

Finnish

Language code: fi

Type:

str

French

Language code: fr

Type:

str

German

Language code: de

Type:

str

Greek

Language code: el

Type:

str

Hindi

Language code: hi

Type:

str

Hungarian

Language code: hu

Type:

str

Italian

Language code: it

Type:

str

Japanese

Language code: ja

Type:

str

Javanese

Language code: jv

Type:

str

Korean

Language code: ko

Type:

str

Mandarin

Language code: zh_cmn

Type:

str

Marathi

Language code: mr

Type:

str

Polish

Language code: pl

Type:

str

Portuguese

Language code: pt

Type:

str

Punjabi

Language code: pa

Type:

str

Romanian

Language code: ro

Type:

str

Russian

Language code: ru

Type:

str

Serbian

Language code: sr

Type:

str

Sinhalese

Language code: si

Type:

str

Slovak

Language code: sk

Type:

str

Spanish

Language code: es

Type:

str

Swedish

Language code: sv

Type:

str

Tamil

Language code: ta

Type:

str

Telugu

Language code: te

Type:

str

Turkish

Language code: tr

Type:

str

Ukrainian

Language code: uk

Type:

str

Urdu

Language code: ur

Type:

str

Vietnamese

Language code: vi

Type:

str

WuShanghainese

Language code: zh_wuu

Type:

str

Xiang

Language code: zh_hsn

Type:

str

YueCantonese

Language code: zh_yue

Type:

str

Zulu

Language code: zu

Type:

str

Sports event type

class weatherly.SportsEventType

An enum representing type of sports event

football

Football event

cricket

Cricket event

golf

Golf event

Tide height type

class weatherly.TideHeight

An enum representing tide height i.e. HIGH or LOW

HIGH

When the tide is high

LOW

When the tide is low

Endpoints

class weatherly.WeatherEndpoints

An enum representing WeatherAPI endpoint used for bulk requests

CURRENT_WEATHER

Current weather endpoint

ASTRO

Astronomical data enpoint

FORECAST

Forecast data enpoint

FUTURE

Future weather data endpoint

HISTORY

Historical weather data endpoint

IP_DATA

IP address info endpoint

LOCATIONS

Search/Autocomplete location endpoint

MARINE

Marine data endpoint

SPORTS

Sports data endpoint

Models

Warning

Those classes should not be created manually, instead they are returned from methods like get_current_weather of the Client class.

BulkRequest is the only object you should build / create, other classes should not even be modified

Note

When adding a lang parameter to the request only condition_text is translated into requested language.

Base model classes

Attributes

• raw

Methods

• defflatten

class weatherly.PartialAPIResponse

Represents a partial response, or a part of a response class from WeatherAPI

raw

A raw dictionary representing the partial response body

Type:

Dict[str, Any]

flatten() → Dict[str, str]

Converts a Dict[str, Any] into a flatten dictionary of type Dict[str, str]

For example, given a dictionary

{
    "body": {
        "tag": "p",
        "content": {
            "yes": "no"
        }
    },
    "other": {
        "one": "two",
        "three": "four"
    }
}

It will be turned into

{
    "body.tag": "p",
    "body.content.yes": "no",
    "other.one": "two",
    "other.three": "four"
}

Note

This function does not use recursion, so there won’t be any stack problems with long nested dictionaries

Attributes

• code
• raw
• status

class weatherly.APIResponse

Represents a basic response from Weather API. Inherits from PartialAPIResponse.

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

Current weather

Attributes

• aqi
• cloud
• code
• condition_code
• condition_icon
• condition_text
• feelslike_c
• feelslike_f
• humidity
• is_day
• last_updated_epoch
• location
• precip_in
• precip_mm
• pressure_in
• pressure_mb
• raw
• status
• temp_c
• temp_f
• uv
• wind_degree
• wind_dir
• wind_kph
• wind_mph

class weatherly.CurrentWeatherData

Current weather data, a common return type from methods that requests this from WeatherAPI.com.

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

location

Location of the requested weather data

Type:

LocationData

last_updated_epoch

The timestamp when the weather data was last updated.

Type:

int

temp_c

Weather temperature in Celsius

Type:

float

temp_f

Weather temperature in Fahrenheit

Type:

float

is_day

Wherever the current time is considered day time.

Type:

bool

condition_text

Weather condition text

Type:

str

condition_icon

Link to the weather condition icon

Type:

str

condition_code

Code of current weather condition

Type:

int

wind_mph

Current wind speed in miles per hour (mph)

Type:

float

wind_kph

Current wind speed in kilometers per hour (kph)

Type:

float

wind_degree

Direction of wind in degrees

Type:

int

wind_dir

Direction of wind as a string (e.g. “W”)

Type:

str

pressure_mb

Pressure in millibars (mb)

Type:

float

pressure_in

Pressure in inches (in)

Type:

float

precip_mm

Precipation (water that is falling out of the sky) in millimeters (mm)

Type:

float

precip_in

Precipation (water that is falling in the sky) in inches (in)

Type:

float

humidity

Humidity in integer percentage

Type:

int

cloud

Cloud cover as percentage

Type:

int

feelslike_c

Feels like temperature in Celsius

Type:

float

feelslike_f

Feels like temperature in Fahrenheit

Type:

float

uv

UV Index

Type:

float

aqi

Air quality data. Can be None (if this field of data was not requested)

Type:

Optional[AirQualityData]

Location

Attributes

• code
• country
• id
• latitude
• localtime_epoch
• localtime_formatted
• longitude
• name
• raw
• region
• status
• timezone_id

class weatherly.LocationData

Location data, returned with most requests.

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

id

A specific ID of the location. Can be None

Type:

Optional[int]

name

Name of the location (e.g. London)

Type:

str

region

A region of the location

Type:

str

country

Country where the location is

Type:

str

latitude

Latitude coordinate of the location

Type:

float

longitude

Longitude coordinate of the location

Type:

float

timezone_id

Timezone ID of the location (e.g. Europe/London). Could be None when using the Search/Autocomplete API.

Type:

Optional[str]

localtime_epoch

Local time of the location as a timestamp

Type:

Optional[int]

localtime_formatted

Formatted local time of the location

Type:

Optional[str]

Air Quality

Attributes

• co
• gb_defra_band
• gb_defra_index
• no2
• o3
• pm10
• pm2_5
• raw
• so2
• us_epa_band
• us_epa_index

class weatherly.AirQualityData

Air Quality data

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

co

Carbon Monoxide (μg/m3)

Type:

float

o3

Ozone (μg/m3)

Type:

float

no2

Nitrogen dioxide (μg/m3)

Type:

float

so2

Sulphur dioxide (μg/m3)

Type:

float

pm2_5

PM2.5 (μg/m3)

Type:

float

pm10

PM10 (μg/m3)

Type:

float

us_epa_index

US - EPA standard.

• 1 means Good

• 2 means Moderate

• 3 means Unhealthy for sensitive group

• 4 means Unhealthy

• 5 means Very Unhealthy

• 6 means Hazardous

Type:

int

gb_defra_index

UK Defra Index

Index	1	2	3	4	5	6	7	8	9	10
Band	Low	Low	Low	Moderate	Moderate	Moderate	High	High	High	Very High
µgm^-3	0-11	12-23	24-35	36-41	42-47	48-53	54-58	59-64	65-70	71 or more

Type:

int

gb_defra_band

A band corresponding to the gb_defra_index

Type:

str

us_epa_band

A band corresponding to the us_epa_index

Type:

str

Attributes

• areas
• category
• certainty
• description
• effective
• event
• expires
• headline
• instruction
• msg_type
• note
• raw
• severity
• urgency

class weatherly.AlertData

An alert from WeatherAPI

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

headline

Alert headline

Type:

str

msg_type

Type of alert

Type:

str

severity

Severity of alert

Type:

str

urgency

Urgency

Type:

str

areas

Areas covered

Type:

str

category

Category

Type:

str

certainty

Certainty

Type:

str

event

Event

Type:

str

note

Note

Type:

str

effective

Effective

Type:

str

expires

Expires

Type:

str

description

Description

Type:

str

instruction

Instruction

Type:

str

Forecast related

Attributes

• alerts
• code
• forecast_days
• location
• raw
• status

Methods

• defiter_hours

class weatherly.ForecastData

Forecast data returned from Forecast API

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

location

Location of the forecast data.

Type:

LocationData

forecast_days

A list of forecast days

Type:

List[ForecastDay]

alerts

A list of alerts, this list can be empty. List is also empty, when the user disabled alerts in the request.

Type:

List[AlertData]

for ... in iter_hours() → Iterator[ForecastHour]

Iterate over all possible hours from this class.

for x in y

Iterate over hour data from this instance.

Returns:

Iterator[ForecastHour] – A generator object you can iterate over made of ForecastHour

Attributes

• aqi
• astro
• avghumidity
• avgtemp_c
• avgtemp_f
• avgvis_km
• avgvis_miles
• condition_code
• condition_icon
• condition_text
• date
• date_epoch
• hour_data
• maxtemp_c
• maxtemp_f
• maxwind_kph
• maxwind_mph
• mintemp_c
• mintemp_f
• raw
• totalprecip_in
• totalprecip_mm
• uv

class weatherly.ForecastDay

A forecast day, element of ForecastData

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

date

Forecast date

Type:

str

date_epoch

Forecast date as unix time.

Type:

int

maxtemp_c

Maximum temperature in celsius for the day.

Type:

float

maxtemp_f

Maximum temperature in fahrenheit for the day

Type:

float

mintemp_c

Minimum temperature in celsius for the day

Type:

float

mintemp_f

Minimum temperature in fahrenheit for the day

Type:

float

avgtemp_c

Average temperature in celsius for the day

Type:

float

avgtemp_f

Average temperature in fahrenheit for the day

Type:

float

maxwind_mph

Maximum wind speed in miles per hour

Type:

float

maxwind_kph

Maximum wind speed in kilometer per hour

Type:

float

totalprecip_mm

Total precipitation in milimeter

Type:

float

totalprecip_in

Total precipitation in inches

Type:

float

avgvis_km

Average visibility in kilometer

Type:

float

avgvis_miles

Average visibility in miles

Type:

float

avghumidity

Average humidity as percentage

Type:

int

uv

UV Index. Can be None when this class is returned from Future API

Type:

Optional[float]

condition_text

Weather condition text

Type:

str

condition_icon

Weather condition icon

Type:

str

condition_code

Weather condition code

Type:

int

hour_data

A list of ForecastHour objects representing hourly weather data.

Type:

List[ForecastHour]

astro

Astronomical data object

Type:

AstronomicalData

aqi

Air Quality data as AirQualityData object. Can be None

Type:

Optional[AirQualityData]

Attributes

• aqi
• chance_of_rain
• chance_of_snow
• cloud
• condition_code
• condition_icon
• condition_text
• dewpoint_c
• dewpoint_f
• feelslike_c
• feelslike_f
• gust_kph
• gust_mph
• headindex_c
• headindex_f
• humidity
• is_day
• precip_in
• precip_mm
• pressure_in
• pressure_mb
• raw
• temp_c
• temp_f
• time
• time_epoch
• uv
• vis_km
• vis_miles
• will_it_rain
• will_it_snow
• wind_degree
• wind_dir
• wind_kph
• wind_mph
• windchill_c
• windchill_f

class weatherly.ForecastHour

Forecast hour, an element of ForecastDay

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

time_epoch

Time as epoch

Type:

int

time

Date and time

Type:

str

temp_c

Temperature in celsius

Type:

float

temp_f

Temperature in fahrenheit

Type:

float

condition_text

Weather condition text

Type:

str

condition_icon

Weather condition icons

Type:

str

condition_code

Weather condition code

Type:

int

wind_mph

Maximum wind speed in miles per hour

Type:

float

wind_kph

Maximum wind speed in kilometer per hour

Type:

float

wind_degree

Wind direction in degrees

Type:

int

wind_dir

Wind direction as 16 point compass. e.g.: NSW

Type:

str

pressure_mb

Pressure in millibars

Type:

float

pressure_in

Pressure in inches

Type:

float

precip_mm

Precipitation amount in millimeters

Type:

float

precip_in

Precipitation amount in inches

Type:

float

humidity

Humidity as percentage

Type:

int

cloud

Cloud cover as percentage

Type:

int

feelslike_c

Feels like temperature as celcius

Type:

float

feelslike_f

Feels like temperature as fahrenheit

Type:

float

windchill_c

Windchill temperature in celcius

Type:

float

windchill_f

Windchill temperature in fahrenheit

Type:

float

headindex_c

Heat index in celcius

Type:

float

headindex_f

Heat index in fahrenheit

Type:

float

dewpoint_c

Dew point in celcius

Type:

float

dewpoint_f

Dew point in fahrenheit

Type:

float

will_it_rain

Will it will rain or not

Type:

bool

will_it_snow

Will it will snow or not

Type:

bool

is_day

Whether to show day condition icon or night icon

Type:

bool

vis_km

Visibility in kilometer

Type:

float

vis_miles

Visibility in miles

Type:

float

chance_of_rain

Chance of rain as percentage

Type:

int

chance_of_snow

Chance of snow as percentage

Type:

int

gust_mph

Wind gust in miles per hour

Type:

float

gust_kph

Wind gust in kilometer per hour

Type:

float

uv

UV Index. Can be None when this class is returned from Future API

Type:

Optional[float]

aqi

Air Quality data. See AirQualityData for more info.

Type:

Optional[AirQualityData]

Future

Attributes

• code
• day
• location
• raw
• status

class weatherly.FutureData

Future data returned from Future API

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

location

Location of the forecast data.

Type:

LocationData

day

Day data for the requested future date.

Type:

ForecastDay

IP

Attributes

• city
• code
• continent_code
• continent_name
• country_code
• country_name
• geoname_id
• ip
• is_eu
• latitude
• localtime_epoch
• localtime_formatted
• longitude
• raw
• region
• status
• type
• tz_id

class weatherly.IPData

Represents IP Data retuned from IP Lookup API

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

ip

IP address

Type:

str

type

Type of the IP address

Type:

Literal[“ipv4”, “ipv6”]

continent_code

Continent code

Type:

str

continent_name

Continent name

Type:

str

country_code

Country code

Type:

str

country_name

Name of country

Type:

str

is_eu

Indicating if IP address is in Europe

Type:

bool

geoname_id

Geoname ID

Type:

int

city

City name

Type:

str

region

Region name

Type:

str

latitude

Latitude in decimal degree

Type:

float

longitude

Longitude in decimal degree

Type:

float

tz_id

Time zone

Type:

str

localtime_epoch

Local time epoch

Type:

int

localtime_formatted

Formatted local time string (e.g. 2023-04-30 17:54)

Type:

str

Astronomical

Attributes

• code
• location
• moon_illumination
• moon_phase
• moonrise
• moonset
• raw
• status
• sunrise
• sunset

class weatherly.AstronomicalData

Represents astronomical data as a response from WeatherAPI

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

location

Location of the requested data. Is not None only if this object is returned from astronomy.json endpoint.

Type:

Optional[LocationData]

sunrise

Sunrise local time

Type:

str

sunset

Sunset local time

Type:

str

moonrise

Moonrise local time

Type:

str

moonset

Moonset local time

Type:

str

moon_phase

Moon phases. Value returned:

• New Moon

• Waxing Crescent

• First Quarter

• Waxing Gibbous

• Full Moon

• Waning Gibbous

• Last Quarter

• Waning Crescent

Can be None

Type:

Optional[str]

moon_illumination

Moon illumination. Can be None

Type:

Optional[int]

Sports related

Attributes

• country
• event_type
• match
• raw
• region
• stadium
• start_time
• tournament

class weatherly.SportsEvent

Represents a single sports event from the Sports API

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

stadium

Name of stadium

Type:

str

country

Country

Type:

str

region

Region

Type:

str

tournament

Tournament name

Type:

str

start_time

Start local date and time for event in yyyy-MM-dd HH:mm format

Type:

str

match

Match name

Type:

str

event_type

An enum representing the type of event. Can be “golf”, football” or “cricket”

Type:

SportsEventType

Attributes

• categorized
• code
• events
• raw
• status

class weatherly.SportsData

Represents sports data returned from the Sports API

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

events

A list of sports

Type:

List[SportsEvent]

categorized

Dictionary of events, that are same as in events, but categorized. Category is the key, and value is a list of SportsEvent.

Type:

Dict[str, List[SportsEvent]]

Marine

Attributes

• cloud
• condition_code
• condition_icon
• condition_text
• dewpoint_c
• dewpoint_f
• feelslike_c
• feelslike_f
• gust_kph
• gust_mph
• headindex_c
• headindex_f
• humidity
• is_day
• precip_in
• precip_mm
• pressure_in
• pressure_mb
• raw
• sig_ht_mt
• swell_dir
• swell_dir_16_point
• swell_ht_ft
• swell_ht_mt
• swell_period_secs
• temp_c
• temp_f
• time
• time_epoch
• uv
• vis_km
• vis_miles
• water_temp_c
• water_temp_f
• wind_degree
• wind_dir
• wind_kph
• wind_mph
• windchill_c
• windchill_f

class weatherly.MarineHour

Marine hour, part of MarineDay, this class contains marine and forecast informations from a specific hour. Inherits from :class`ForecastData` to avoid more messy code

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

time_epoch

Time as epoch

Type:

int

time

Date and time

Type:

str

temp_c

Temperature in celsius

Type:

float

temp_f

Temperature in fahrenheit

Type:

float

condition_text

Weather condition text

Type:

str

condition_icon

Weather condition icons

Type:

str

condition_code

Weather condition code

Type:

int

wind_mph

Maximum wind speed in miles per hour

Type:

float

wind_kph

Maximum wind speed in kilometer per hour

Type:

float

wind_degree

Wind direction in degrees

Type:

int

wind_dir

Wind direction as 16 point compass. e.g.: NSW

Type:

str

pressure_mb

Pressure in millibars

Type:

float

pressure_in

Pressure in inches

Type:

float

precip_mm

Precipitation amount in millimeters

Type:

float

precip_in

Precipitation amount in inches

Type:

float

humidity

Humidity as percentage

Type:

int

cloud

Cloud cover as percentage

Type:

int

feelslike_c

Feels like temperature as celcius

Type:

float

feelslike_f

Feels like temperature as fahrenheit

Type:

float

windchill_c

Windchill temperature in celcius

Type:

float

windchill_f

Windchill temperature in fahrenheit

Type:

float

headindex_c

Heat index in celcius

Type:

float

headindex_f

Heat index in fahrenheit

Type:

float

dewpoint_c

Dew point in celcius

Type:

float

dewpoint_f

Dew point in fahrenheit

Type:

float

is_day

Whether to show day condition icon or night icon

Type:

bool

vis_km

Visibility in kilometer

Type:

float

vis_miles

Visibility in miles

Type:

float

gust_mph

Wind gust in miles per hour

Type:

float

gust_kph

Wind gust in kilometer per hour

Type:

float

uv

UV Index.

Type:

float

sig_ht_mt

Significant wave height in metres

Type:

float

swell_ht_mt

Swell wave height in metres

Type:

float

swell_ht_ft

Swell wave height in feet

Type:

float

swell_dir

Swell direction in degrees

Type:

float

swell_dir_16_point

Swell direction in 16 point compass e.g. NNW

Type:

str

swell_period_secs

Swell period in seconds

Type:

float

water_temp_c

Water temperature in Celcius

Type:

float

water_temp_f

Water temperature in Fahrenheit

Type:

float

Attributes

• astro
• avghumidity
• avgtemp_c
• avgtemp_f
• avgvis_km
• avgvis_miles
• condition_code
• condition_icon
• condition_text
• date
• date_epoch
• hour_data
• maxtemp_c
• maxtemp_f
• maxwind_kph
• maxwind_mph
• mintemp_c
• mintemp_f
• raw
• tide_data
• totalprecip_in
• totalprecip_mm
• uv

class weatherly.MarineDay

Marine day, part of MarineData, representing a single day with forecast information

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

date

Forecast date

Type:

str

date_epoch

Forecast date as unix time.

Type:

int

maxtemp_c

Maximum temperature in celsius for the day.

Type:

float

maxtemp_f

Maximum temperature in fahrenheit for the day

Type:

float

mintemp_c

Minimum temperature in celsius for the day

Type:

float

mintemp_f

Minimum temperature in fahrenheit for the day

Type:

float

avgtemp_c

Average temperature in celsius for the day

Type:

float

avgtemp_f

Average temperature in fahrenheit for the day

Type:

float

maxwind_mph

Maximum wind speed in miles per hour

Type:

float

maxwind_kph

Maximum wind speed in kilometer per hour

Type:

float

totalprecip_mm

Total precipitation in milimeter

Type:

float

totalprecip_in

Total precipitation in inches

Type:

float

avgvis_km

Average visibility in kilometer

Type:

float

avgvis_miles

Average visibility in miles

Type:

float

avghumidity

Average humidity as percentage

Type:

int

uv

UV Index

Type:

float

condition_text

Weather condition text

Type:

str

condition_icon

Weather condition icon

Type:

str

condition_code

Weather condition code

Type:

int

hour_data

A list of MarineHour objects representing hourly weather data.

Type:

List[MarineHour]

astro

Astronomical data object

Type:

AstronomicalData

tide_data

A list of issues tides

Type:

List[TideData]

Attributes

• code
• location
• marine_days
• raw
• status

Methods

• defiter_hours

class weatherly.MarineData

Marine data, response from Marine API as a class

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

location

Location of the requested marine data

Type:

LocationData

marine_days

A list of marine days for the requested period

Type:

List[MarineDay]

for ... in iter_hours() → Iterator[MarineHour]

Iterate over all possible hours from this class.

for x in y

Iterate over hour data from this instance.

Returns:

Iterator[MarineHour] – A generator object you can iterate over made of MarineHour

Attributes

• raw
• tide_height_mt
• tide_time
• tide_type

class weatherly.TideData

Represents tide data, part of Marine API response

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

tide_time

Local tide time

Type:

str

tide_height_mt

Tide height in meters

Type:

float

tide_type

Type of height of the tide represented as a TideHeight enum. Can be LOW or HIGH

Type:

TideHeight

Bulk requests

Attributes

• endpoint
• queries

Methods

• clsBulkRequest.build
• defadd_query
• defset_endpoint

class weatherly.BulkRequest

Represents a bulk request params

queries

Query data for the request

Type:

List[Tuple[str, str]]

endpoint

Enum representing the endpoint for the request

Type:

WeatherEndpoints

add_query(id: str, location: str) → List[Tuple[str, str]]

Add a query to the bulk request

Parameters:

• id (str) – Unique identifier for the query

• location (str) – Location you want to fetch data from

Returns:

List[Tuple[str, str]] – List of updated query parameters with the new query added

classmethod build(*queries: List[Tuple[str]], endpoint: WeatherEndpoints)

Build a bulk request

Note

This function is a class method i.e. does not require initialization. For example:

import weatherly
weatherly.BulkRequest.build(...) # <- no initialization needed (no parentheses after BulkRequest)

Parameters:

• queries (List[Tuple[str]]) – Query data for the request as a list of tuples (id, query)

• endpoint (WeatherEndpoints) – Enum representing the endpoint for the request

set_endpoint(endpoint: WeatherEndpoints) → None

Set the endpoint for the request

Parameters:

endpoint (WeatherEndpoints) – Endpoint for the request as an enum

Attributes

• code
• data
• endpoint
• raw
• status

class weatherly.BulkResponse

Represents bulk request response data

raw

Raw response in a JSON-like format (converted to a python dictionary)

Type:

Dict[str, Any]

status

HTTP status of the response. 200 is OK, and is the most common status.

Type:

int

code

Response code. In some cases this can be None

Type:

Optional[int]

endpoint

Enum representing the endpoint that was bulk-requested

Type:

WeatherEndpoints

data

A list containing responses with their IDs. For example this can be: [("London-ID", CurrentWeatherData), ("other-ID", CurrentWeatherData)]

Type:

List[Tuple[str, Any]]

Utility functions

This library also provides utility (aka helper) functions, that can be easily used.

Find language enum

weatherly.utils.find_language(lang: str, asobj: bool = False) → None

weatherly.utils.find_language(lang: str, asobj: bool = False) → Languages

Used to find language code from available languages.

Parameters:

lang (str) – A language you want to search for

Returns:

Union[str, Languages, None] – Language code, could be None, could be a Languages enum.

Convert a string to an enum

weatherly.utils.str_to_enum(query: str, target: Enum) → Enum

Find a corresponding enum class for the given string

Parameters:

• query (str) – Query string you want to get the enum class for

• target (Enum) – An enum class inheriting from Enum

Returns:

Enum – Found enum class for the given string

Exceptions

exception weatherly.WeatherlyException

A base class for all weatherly exceptions. Almost all exceptions of this module inherit from this class.

Inherits from Exception.

exception weatherly.InvalidDate

Raised when a date (for History/Future API) is invalid.

Inherits from WeatherlyException.

exception weatherly.WeatherAPIException(status: int, code: int, message: str, *args)

The base class for Client weather requests exceptions.

Parameters:

• status (int) – HTTP status code

• code (int) – Error code

• message (str) – Message provided with the error

exception weatherly.NoLocationFound(status: int, code: int, message: str, *args)

Exception like this is raised when no location was found when searching for weather data.

Usually has status code 400 and error code 1006.

Inherits from WeatherAPIException.

exception weatherly.InvalidAPIKey(status: int, code: int, message: str, *args)

Exception like this is raised when provided API key is invalid

Usually has status code 401 and error code 2006.

Inherits from WeatherAPIException.

exception weatherly.APILimitExceeded(status: int, code: int, message: str, *args)

Exception like this is raised when API key has exceeded monthly calls limit.

Usually has status code 400 and error code 2007.

Inherits from WeatherAPIException.

exception weatherly.APIKeyDisabled(status: int, code: int, message: str, *args)

Exception like this is raised when API key has been disabled.

Usually has status code 403 and error code 2008.

Inherits from WeatherAPIException.

exception weatherly.AccessDenied(status: int, code: int, message: str, *args)

Exception like this is raised when API key does not have access to requested resource.

Usually has status code 403 and error code 2009.

Inherits from WeatherAPIException.

exception weatherly.InternalApplicationError(status: int, code: int, message: str, *args)

Exception like this is raised when an internal application error occured. There is nothing to do about it.

Usually has status code 400 and error code 9999.

Inherits from WeatherAPIException.