pyowm.agroapi10 package

Submodules

pyowm.agroapi10.agro_manager module

class pyowm.agroapi10.agro_manager.AgroManager(API_key, config)

Bases: object

A manager objects that provides a full interface to OWM Agro API.

Parameters:

• API_key (str) – the OWM Weather API key

• config (dict) – the configuration dictionary

Returns:

an AgroManager instance

Raises:

AssertionError when no API Key is provided

agro_api_version()

create_polygon(geopolygon, name=None)

Create a new polygon on the Agro API with the given parameters

Parameters:

• geopolygon (pyowm.utils.geo.Polygon instance) – the geopolygon representing the new polygon

• name (str) – optional mnemonic name for the new polygon

Returns:

a pyowm.agro10.polygon.Polygon instance

delete_polygon(polygon)

Deletes on the Agro API the Polygon identified by the ID of the provided polygon object.

Parameters:

polygon (pyowm.agro10.polygon.Polygon instance) – the pyowm.agro10.polygon.Polygon object to be deleted

Returns:

None if deletion is successful, an exception otherwise

download_satellite_image(metaimage, x=None, y=None, zoom=None, palette=None)

Downloads the satellite image described by the provided metadata. In case the satellite image is a tile, then tile coordinates and zoom must be provided. An optional palette ID can be provided, if supported by the downloaded preset (currently only NDVI is supported)

Parameters:

• metaimage (a pyowm.agroapi10.imagery.MetaImage subtype) – the satellite image’s metadata, in the form of a MetaImage subtype instance

• x (int or None) – x tile coordinate (only needed in case you are downloading a tile image)

• y (int or None) – y tile coordinate (only needed in case you are downloading a tile image)

• zoom (int or None) – zoom level (only needed in case you are downloading a tile image)

• palette (str or None) – ID of the color palette of the downloaded images. Values are provided by pyowm.agroapi10.enums.PaletteEnum

Returns:

a pyowm.agroapi10.imagery.SatelliteImage instance containing both image’s metadata and data

get_polygon(polygon_id)

Retrieves a named polygon registered on the Agro API.

Parameters:

id (str) – the ID of the polygon

Returns:

a pyowm.agro10.polygon.Polygon object

get_polygons()

Retrieves all of the user’s polygons registered on the Agro API.

Returns:

list of pyowm.agro10.polygon.Polygon objects

search_satellite_imagery(polygon_id, acquired_from, acquired_to, img_type=None, preset=None, min_resolution=None, max_resolution=None, acquired_by=None, min_cloud_coverage=None, max_cloud_coverage=None, min_valid_data_coverage=None, max_valid_data_coverage=None)

Searches on the Agro API the metadata for all available satellite images that contain the specified polygon and acquired during the specified time interval; and optionally matching the specified set of filters: - image type (eg. GeoTIF) - image preset (eg. false color, NDVI, …) - min/max acquisition resolution - acquiring satellite - min/max cloud coverage on acquired scene - min/max valid data coverage on acquired scene

Parameters:

• polygon_id (str) – the ID of the reference polygon

• acquired_from (int) – lower edge of acquisition interval, UNIX timestamp

• acquired_to (int) – upper edge of acquisition interval, UNIX timestamp

• img_type (pyowm.commons.databoxes.ImageType) – the desired file format type of the images. Allowed values are given by pyowm.commons.enums.ImageTypeEnum

• preset (str) – the desired preset of the images. Allowed values are given by pyowm.agroapi10.enums.PresetEnum

• min_resolution (int) – minimum resolution for images, px/meters

• max_resolution (int) – maximum resolution for images, px/meters

• acquired_by (str) – short symbol of the satellite that acquired the image (eg. “l8”)

• min_cloud_coverage (int) – minimum cloud coverage percentage on acquired images

• max_cloud_coverage (int) – maximum cloud coverage percentage on acquired images

• min_valid_data_coverage (int) – minimum valid data coverage percentage on acquired images

• max_valid_data_coverage (int) – maximum valid data coverage percentage on acquired images

Returns:

a list of pyowm.agro10.imagery.MetaImage subtypes instances

soil_data(polygon)

Retrieves the latest soil data on the specified polygon

Parameters:

polygon (pyowm.agro10.polygon.Polygon instance) – the reference polygon you want soil data for

Returns:

a pyowm.agro10.soil.Soil instance

stats_for_satellite_image(metaimage)

Retrieves statistics for the satellite image described by the provided metadata. This is currently only supported ‘EVI’ and ‘NDVI’ presets

Parameters:

metaimage (a pyowm.agroapi10.imagery.MetaImage subtype) – the satellite image’s metadata, in the form of a MetaImage subtype instance

Returns:

dict

update_polygon(polygon)

Updates on the Agro API the Polygon identified by the ID of the provided polygon object. Currently this only changes the mnemonic name of the remote polygon

Parameters:

polygon (pyowm.agro10.polygon.Polygon instance) – the pyowm.agro10.polygon.Polygon object to be updated

Returns:

None if update is successful, an exception otherwise

pyowm.agroapi10.enums module

class pyowm.agroapi10.enums.PaletteEnum

Bases: object

Allowed color palettes for satellite images on Agro API 1.0

BLACK_AND_WHITE = '2'

CONTRAST_CONTINUOUS = '4'

CONTRAST_SHIFTED = '3'

GREEN = '1'

classmethod items()

All values for this enum :return: list of str

class pyowm.agroapi10.enums.PresetEnum

Bases: object

Allowed presets for satellite images on Agro API 1.0

EVI = 'evi'

FALSE_COLOR = 'falsecolor'

NDVI = 'ndvi'

TRUE_COLOR = 'truecolor'

classmethod items()

All values for this enum :return: list of str

class pyowm.agroapi10.enums.SatelliteEnum

Bases: object

Allowed presets for satellite names on Agro API 1.0

LANDSAT_8 = <pyowm.commons.databoxes.Satellite - name=Landsat 8 symbol=l8>

SENTINEL_2 = <pyowm.commons.databoxes.Satellite - name=Sentinel-2 symbol=s2>

classmethod items()

All values for this enum :return: list of str

pyowm.agroapi10.imagery module

class pyowm.agroapi10.imagery.MetaGeoTiffImage(url, preset, satellite_name, acquisition_time, valid_data_percentage, cloud_coverage_percentage, sun_azimuth, sun_elevation, polygon_id=None, stats_url=None)

Bases: MetaImage

Class representing metadata for a satellite image of a polygon in GeoTiff format

image_type = <pyowm.commons.databoxes.ImageType - name=GEOTIFF mime=image/tiff>

class pyowm.agroapi10.imagery.MetaImage(url, preset, satellite_name, acquisition_time, valid_data_percentage, cloud_coverage_percentage, sun_azimuth, sun_elevation, polygon_id=None, stats_url=None)

Bases: object

A class representing metadata for a satellite-acquired image

Parameters:

• url (str) – the public URL of the image

• preset (str) – the preset of the image (supported values are listed by pyowm.agroapi10.enums.PresetEnum)

• satellite_name (str) – the name of the satellite that acquired the image (supported values are listed by pyowm.agroapi10.enums.SatelliteEnum)

• acquisition_time (int) – the UTC Unix epoch when the image was acquired

• valid_data_percentage (float) – approximate percentage of valid data coverage

• cloud_coverage_percentage (float) – approximate percentage of cloud coverage on the scene

• sun_azimuth (float) – sun azimuth angle at scene acquisition time

• sun_elevation (float) – sun zenith angle at scene acquisition time

• polygon_id (str) – optional id of the polygon the image refers to

• stats_url (str or None) – the public URL of the image statistics, if available

Returns:

an MetaImage object

acquisition_time(timeformat='unix')

Returns the UTC time telling when the image data was acquired by the satellite

Parameters:

timeformat (str) – the format for the time value. May be: ‘unix’ (default) for UNIX time ‘iso’ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00 ‘date for datetime.datetime object instance

Returns:

an int or a str

image_type = None

class pyowm.agroapi10.imagery.MetaPNGImage(url, preset, satellite_name, acquisition_time, valid_data_percentage, cloud_coverage_percentage, sun_azimuth, sun_elevation, polygon_id=None, stats_url=None)

Bases: MetaImage

Class representing metadata for a satellite image of a polygon in PNG format

image_type = <pyowm.commons.databoxes.ImageType - name=PNG mime=image/png>

class pyowm.agroapi10.imagery.MetaTile(url, preset, satellite_name, acquisition_time, valid_data_percentage, cloud_coverage_percentage, sun_azimuth, sun_elevation, polygon_id=None, stats_url=None)

Bases: MetaImage

Class representing metadata for a tile in PNG format

image_type = <pyowm.commons.databoxes.ImageType - name=PNG mime=image/png>

class pyowm.agroapi10.imagery.SatelliteImage(metadata, data, downloaded_on=None, palette=None)

Bases: object

Class representing a downloaded satellite image, featuring both metadata and data

Parameters:

• metadata (a pyowm.agro10.imagery.MetaImage subtype instance) – the metadata for this satellite image

• data (either pyowm.commons.image.Image or pyowm.commons.tile.Tile object) – the actual data for this satellite image

• downloaded_on (int or None) – the UNIX epoch this satellite image was downloaded at

• palette (str or None) – ID of the color palette of the downloaded images. Values are provided by pyowm.agroapi10.enums.PaletteEnum

Returns:

a pyowm.agroapi10.imagery.SatelliteImage instance

downloaded_on(timeformat='unix')

Returns the UTC time telling when the satellite image was downloaded from the OWM Agro API

Parameters:

timeformat (str) – the format for the time value. May be: ‘unix’ (default) for UNIX time ‘iso’ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00 ‘date for datetime.datetime object instance

Returns:

an int or a str

persist(path_to_file)

Saves the satellite image to disk on a file

Parameters:

path_to_file (str) – path to the target file

Returns:

None

pyowm.agroapi10.polygon module

class pyowm.agroapi10.polygon.Polygon(id, name=None, geopolygon=None, center=None, area=None, user_id=None)

Bases: object

A Polygon feature, foundational element for all Agro API operations

Parameters:

• id (str) – the polygon’s ID

• name – the polygon’s name

• geopolygon (pyowm.utils.geo.Polygon) – the pyowm.utils.geo.Polygon instance that represents this polygon

• center (pyowm.utils.geo.Point) – the pyowm.utils.geo.Point instance that represents the central point of the polygon

• area (float or int) – the area of the polygon in hectares

• user_id (str) – the ID of the user owning this polygon

Returns:

a Polygon instance

Raises:

AssertionError when either id is None or geopolygon, center or area have wrong type

property area_km

classmethod from_dict(the_dict)

pyowm.agroapi10.search module

class pyowm.agroapi10.search.SatelliteImagerySearchResultSet(polygon_id, list_of_dict, query_timestamp)

Bases: object

Class representing a filterable result set by a satellite imagery search against the Agro API 1.0. Each result is a pyowm.agroapi10.imagery.MetaImage subtype instance

all()

Returns all search results

Returns:

a list of pyowm.agroapi10.imagery.MetaImage instances

issued_on(timeformat='unix')

Returns the UTC time telling when the query was performed against the OWM Agro API

Parameters:

timeformat (str) – the format for the time value. May be: ‘unix’ (default) for UNIX time ‘iso’ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00 ‘date for datetime.datetime object instance

Returns:

an int or a str

with_img_type(image_type)

Returns the search results having the specified image type

Parameters:

image_type (pyowm.commons.databoxes.ImageType instance) – the desired image type (valid values are provided by the pyowm.commons.enums.ImageTypeEnum enum)

Returns:

a list of pyowm.agroapi10.imagery.MetaImage instances

with_img_type_and_preset(image_type, preset)

Returns the search results having both the specified image type and preset

Parameters:

• image_type (pyowm.commons.databoxes.ImageType instance) – the desired image type (valid values are provided by the pyowm.commons.enums.ImageTypeEnum enum)

• preset (str) – the desired image preset (valid values are provided by the pyowm.agroapi10.enums.PresetEnum enum)

Returns:

a list of pyowm.agroapi10.imagery.MetaImage instances

with_preset(preset)

Returns the search results having the specified preset

Parameters:

preset (str) – the desired image preset (valid values are provided by the pyowm.agroapi10.enums.PresetEnum enum)

Returns:

a list of pyowm.agroapi10.imagery.MetaImage instances

pyowm.agroapi10.soil module

class pyowm.agroapi10.soil.Soil(reference_time, surface_temp, ten_cm_temp, moisture, polygon_id=None)

Bases: object

Soil data over a specific Polygon

Parameters:

• reference_time (int) – UTC UNIX time of soil data measurement

• surface_temp (float) – soil surface temperature in Kelvin degrees

• ten_cm_temp (float) – soil temperature at 10 cm depth in Kelvin degrees

• moisture (float) – soil moisture in m^3/m^3

• polygon_id (str) – ID of the polygon this soil data was measured upon

Returns:

a Soil instance

Raises:

AssertionError when any of the mandatory fields is None or has wrong type

classmethod from_dict(the_dict)

reference_time(timeformat='unix')

Returns the UTC time telling when the soil data was measured

Parameters:

timeformat (str) – the format for the time value. May be: ‘unix’ (default) for UNIX time ‘iso’ for ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00 ‘date for datetime.datetime object instance

Returns:

an int or a str

surface_temp(unit='kelvin')

Returns the soil surface temperature

Parameters:

unit (str) – the unit of measure for the temperature value. May be: ‘kelvin’ (default), ‘celsius’ or ‘fahrenheit’

Returns:

a float

Raises:

ValueError when unknown temperature units are provided

ten_cm_temp(unit='kelvin')

Returns the soil temperature measured 10 cm below surface

Parameters:

unit (str) – the unit of measure for the temperature value. May be: ‘kelvin’ (default), ‘celsius’ or ‘fahrenheit’

Returns:

a float

Raises:

ValueError when unknown temperature units are provided

to_dict()

pyowm.agroapi10.uris module

Module contents