ambee_sdk package

The examples mentioned in the documentation is also part of examples jupyter notebook present in the github repo, So feel free to download it and play with it.

Submodules

ambee_sdk.ambee_sdk module

class ambee_sdk.ambee_sdk.InvalidInputError(message)

Bases: Exception Executes when there is an invalid input

Parameters:

message (str) – Message to be displayed

ambee_sdk.ambee_sdk.ambee(x_api_key)**

Bases: object

Base class to initialize credentials

multiple_calls(func, by, lat_lngs=None, postalCodes=None, countryCodes=None, cities=None, places=None, **func_kwargs)

Function to make multiple api calls for a list of inputs.

Parameters:

  • func (function) – Function to make multiple calls on.

  • by (str) – by value to be passed to the function

  • lat_lngs (list) – list of pairs of latitudes and longitudes. Defaults to None.

  • postalCodes (list) – list of postal codes and corresponding country codes. Defaults to None.

  • countryCodes (list) – list of country codes for by country-code api call. Defaults to None.

  • cities (list) – list of cities. Defaults to None.

  • places (list) – list of places. Defaults to None.

  • parallel (bool) – Makes requests in parallel if True. Defaults to False.

  • **func_kwargs –

Returns:

list of api responses in dictionary or pandas DataFrame format

Return type:

outputs

Raises:

InvalidInputError – Executes when there is an invalid input

to_geodataframe(df, x='lng', y='lat')

Utility function to convert to GeoDataFrame

Parameters:

  • df (DataFrame) – Pandas DataFrame

  • x (str) – Name of longitude column. Defaults to ‘lng’.

  • y (str) – Name of latitude column. Defaults to ‘lat’.

Returns:

geopandas GeoDataFrame

Return type:

GeoDataFrame

ambee_sdk.ambee_sdk.air_quality(x_api_key)**

Bases: ambee

Contains methods to fetch data from Air Quality API

get_analytics(by='order', order='worst', return_df=False)

Get Air Quality Analytics

Parameters:

  • by – str (Default value = “order”)

  • order – str (Default value = “worst”)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_historical(by, from_val, to_val, lat=None, lng=None, postalCode=None, countryCode=None, return_df=False)

Retrives historical Air Quality data for a given location

Parameters:

  • by – str

  • from_val – str

  • to_val – _type_

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • postalCode – int (Default value = None)

  • countryCode – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_latest(by, lat=None, lng=None, postalCode=None, countryCode=None, city=None, limit=None, return_df=False)

Retrives latest Air Quality data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • postalCode – int (Default value = None)

  • countryCode – str (Default value = None)

  • city – str (Default value = None)

  • limit – int (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

class ambee_sdk.ambee_sdk.fire(x_api_key)

Bases: ambee

Contains methods to fetch data from Fire API

get_latest(self, by, lat=None, lng=None, place=None, coordinates=None, burnedAreaLoc=False, type=None, return_df=False)

Retrives latest fire data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • place – str (Default value = None)

  • coordinates – list (Default value = None)

  • burnedAreaLoc – bool (Default value = False)

  • type – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_forcast(self, by, lat=None, lng=None, return_df=False)

Retrives latest fire data for a given location

Parameters:

  • by – _type_

  • lat – _type_ (Default value = None)

  • lng – _type_ (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

class ambee_sdk.ambee_sdk.ndvi(x_api_key)

Bases: ambee

Contains methods to fetch data from NDVI API

get_latest(by, lat=None, lng=None, return_df=False)

Retrives latest ndvi data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

class ambee_sdk.ambee_sdk.pollen(x_api_key)

Bases: ambee

Contains methods to fetch data from Pollen API

get_forecast(by, lat=None, lng=None, place=None, return_df=False)

Retrives forecasted pollen data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • place – str (Default value = None)

  • return_df – bool (Default value = False)

  • speciesRisk – (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_historical(by, from_val, to_val, lat=None, lng=None, place=None, return_df=False)

Retrives historical pollen data for a given location

Parameters:

  • by – str

  • from_val – str

  • to_val – _type_

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • place – str (Default value = None)

  • return_df – bool (Default value = False)

  • speciesRisk – (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_latest(by, lat=None, lng=None, place=None, return_df=False)

Retrives latest pollen data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • place – str (Default value = None)

  • speciesRisk – bool (Default value = False)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

ambee_sdk.ambee_sdk.weather(x_api_key)**

Bases: ambee

Contains methods to fetch data from Weather API

get_forecast(by, lat=None, lng=None, daily=False, units=None, return_df=False)

Retrives forecasted weather data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • daily – bool (Default value = False)

  • units – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_historical(by, from_val, to_val, lat=None, lng=None, daily=False, units=None, return_df=False)

Retrives historical weather data for a given location

Parameters:

  • by – str

  • from_val – str

  • to_val – _type_

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • daily – bool (Default value = False)

  • units – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_latest(by, lat=None, lng=None, units=None, return_df=False)

Retrives latest weather data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • units – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_severe_weather(by, lat=None, lng=None, place=None, units=None, return_df=False)

Gets severe weather data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • place – str (Default value = None)

  • units – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

class ambee_sdk.ambee_sdk.natural_disaster(x_api_key)

Bases: ambee

Contains methods to fetch data from Disasters API

get_latest(self, by, lat=None, lng=None, alertLevel=None, continent=None, eventType=None, return_df=False)

Retrives latest disasters data for a given location

Parameters:

  • by – str

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • alertLevel – str (Default value = None)

  • continent – str (Default value = None)

  • eventType – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing

get_historical(self, by, from_val, to_val, lat=None, lng=None, alertLevel=None, continent=None, eventType=None, return_df=False)

Retrives historical disasters data for a given location

Parameters:

  • by – str

  • from_val – str

  • to_val – _type_

  • lat – float (Default value = None)

  • lng – float (Default value = None)

  • alertLevel – str (Default value = None)

  • continent – str (Default value = None)

  • eventType – str (Default value = None)

  • return_df – bool (Default value = False)

Returns:

dict: API response in dictionary format

Raises:

  • InvalidInputError – Raised when the input to query is invalid

  • e – Any exception that occurs during api call and data parsing