CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pyowm

A comprehensive Python wrapper around OpenWeatherMap web APIs providing weather data, forecasts, air pollution, UV index, and agricultural information

—

Pending
Overview
Eval results
Files

agro.mddocs/

Agricultural API

Satellite imagery, soil data, and agricultural information for polygonal areas. Provides access to NDVI, EVI vegetation indices, soil temperature and moisture data, and satellite image search and download capabilities for agricultural monitoring and analysis.

Capabilities

Polygon Management

Create and manage polygonal areas for agricultural monitoring.

class AgroManager:
    def agro_api_version(self) -> tuple:
        """
        Get Agro API version.
        
        Returns:
        Tuple representing the API version
        """
    
    def create_polygon(self, geopolygon: GeoPolygon, name: str = None) -> Polygon:
        """
        Create a new polygon for agricultural monitoring.
        
        Parameters:
        - geopolygon: GeoPolygon object defining the area
        - name: Optional name for the polygon
        
        Returns:
        Polygon object representing the created area
        """
    
    def get_polygons(self) -> List[Polygon]:
        """
        Get all user-created polygons.
        
        Returns:
        List of all Polygon objects owned by the user
        """
    
    def get_polygon(self, polygon_id: str) -> Polygon:
        """
        Get a specific polygon by ID.
        
        Parameters:
        - polygon_id: Unique polygon identifier
        
        Returns:
        Polygon object for the specified ID
        """
    
    def update_polygon(self, polygon: Polygon) -> None:
        """
        Update polygon name.
        
        Parameters:
        - polygon: Polygon object with updated information
        """
    
    def delete_polygon(self, polygon: Polygon) -> None:
        """
        Delete a polygon.
        
        Parameters:
        - polygon: Polygon object to delete
        """

Soil Data

Retrieve soil temperature and moisture data for agricultural areas.

class AgroManager:
    def soil_data(self, polygon_id: str) -> Soil:
        """
        Get soil data for a polygon.
        
        Parameters:
        - polygon_id: Polygon ID to get soil data for
        
        Returns:
        Soil object with temperature and moisture data
        """

Satellite Imagery

Search and download satellite imagery for agricultural analysis.

class AgroManager:
    def search_satellite_imagery(self, polygon_id: str, acquired_from: int, acquired_to: int, img_w: int = None, img_h: int = None) -> SatelliteImagerySearchResultSet:
        """
        Search for satellite imagery within date range.
        
        Parameters:
        - polygon_id: Polygon ID to search imagery for
        - acquired_from: Start date (UNIX timestamp)
        - acquired_to: End date (UNIX timestamp)
        - img_w: Image width in pixels (optional)
        - img_h: Image height in pixels (optional)
        
        Returns:
        SatelliteImagerySearchResultSet containing satellite imagery search results
        """
    
    def download_satellite_image(self, satellite_image: SatelliteImage, preset: str, palette: str = None):
        """
        Download satellite image data.
        
        Parameters:
        - metaimage: MetaImage object to download
        - x: Tile X coordinate (optional)
        - y: Tile Y coordinate (optional)
        - zoom: Zoom level (optional)
        - palette: Color palette (GREEN, BLACK_AND_WHITE, CONTRAST_SHIFTED, CONTRAST_CONTINUOUS)
        
        Returns:
        SatelliteImage object with downloaded data
        """
    
    def stats_for_satellite_image(self, metaimage: MetaImage) -> dict:
        """
        Get statistics for satellite image.
        
        Parameters:
        - metaimage: MetaImage object to get statistics for
        
        Returns:
        Dictionary with image statistics
        """

Usage Examples

Creating and Managing Polygons

from pyowm import OWM
from pyowm.utils.geo import Polygon as GeoPolygon

owm = OWM('your-api-key')
agro_mgr = owm.agro_manager()

# Define a polygon area (coordinates as [lon, lat] pairs)
coords = [
    [[-74.0, 40.7], [-74.0, 40.8], [-73.9, 40.8], [-73.9, 40.7], [-74.0, 40.7]]
]
geopolygon = GeoPolygon(coords)

# Create a polygon for monitoring
polygon = agro_mgr.create_polygon(geopolygon, name="Farm Field 1")
print(f"Created polygon: {polygon.name} (ID: {polygon.id})")
print(f"Area: {polygon.area} hectares ({polygon.area_km} km²)")

# List all polygons
polygons = agro_mgr.get_polygons()
for poly in polygons:
    print(f"Polygon: {poly.name}, Area: {poly.area} ha")

# Update polygon name
polygon.name = "Updated Farm Field 1"
agro_mgr.update_polygon(polygon)

Soil Data Analysis

# Get soil data for a polygon
soil = agro_mgr.soil_data(polygon)

print(f"Soil data timestamp: {soil.reference_time('iso')}")
print(f"Surface temperature: {soil.surface_temp('celsius')}°C")
print(f"10cm depth temperature: {soil.ten_cm_temp('celsius')}°C")
print(f"Soil moisture: {soil.moisture} m³/m³")

# Temperature comparison
surface_temp_c = soil.surface_temp('celsius')
deep_temp_c = soil.ten_cm_temp('celsius')
temp_diff = surface_temp_c - deep_temp_c
print(f"Temperature difference (surface - 10cm): {temp_diff:.2f}°C")

Satellite Imagery Search and Download

from datetime import datetime, timedelta
from pyowm.agroapi10.enums import PresetEnum, SatelliteEnum, PaletteEnum

# Search for NDVI imagery from the last 30 days
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

imagery = agro_mgr.search_satellite_imagery(
    polygon_id=polygon.id,
    acquired_from=int(start_date.timestamp()),
    acquired_to=int(end_date.timestamp()),
    preset=PresetEnum.NDVI,
    acquired_by=SatelliteEnum.SENTINEL_2,
    max_cloud_coverage=20  # Less than 20% cloud cover
)

print(f"Found {len(imagery)} NDVI images")

# Download the most recent image
if imagery:
    latest_image = imagery[0]  # Images are sorted by acquisition time
    print(f"Latest image: {latest_image.acquisition_time('iso')}")
    print(f"Cloud coverage: {latest_image.cloud_coverage_percentage}%")
    print(f"Valid data: {latest_image.valid_data_percentage}%")
    
    # Download with GREEN palette for visualization
    satellite_img = agro_mgr.download_satellite_image(
        latest_image, 
        palette=PaletteEnum.GREEN
    )
    
    print(f"Downloaded image: {satellite_img.downloaded_on('iso')}")
    
    # Save to disk
    satellite_img.persist('/path/to/save/ndvi_image.png')
    
    # Get image statistics
    stats = agro_mgr.stats_for_satellite_image(latest_image)
    print(f"Image statistics: {stats}")

Vegetation Index Analysis

# Search for different vegetation indices
ndvi_images = agro_mgr.search_satellite_imagery(
    polygon_id=polygon.id,
    acquired_from=int(start_date.timestamp()),
    acquired_to=int(end_date.timestamp()),
    preset=PresetEnum.NDVI,
    max_cloud_coverage=10
)

evi_images = agro_mgr.search_satellite_imagery(
    polygon_id=polygon.id,
    acquired_from=int(start_date.timestamp()),
    acquired_to=int(end_date.timestamp()),
    preset=PresetEnum.EVI,
    max_cloud_coverage=10
)

print(f"Available NDVI images: {len(ndvi_images)}")
print(f"Available EVI images: {len(evi_images)}")

# Compare vegetation health over time
for i, img in enumerate(ndvi_images[:5]):  # Last 5 NDVI images
    stats = agro_mgr.stats_for_satellite_image(img)
    print(f"NDVI {i+1} ({img.acquisition_time('iso')}): {stats}")

Data Types

class Polygon:
    def __init__(self, id: str, name: str = None, geopolygon: GeoPolygon = None, 
                 center: GeoPoint = None, area: Union[float, int] = None, user_id: str = None): ...
    
    @property
    def id(self) -> str: ...
    @property
    def name(self) -> str: ...
    @property
    def geopolygon(self) -> GeoPolygon: ...
    @property
    def center(self) -> GeoPoint: ...
    @property
    def area(self) -> Union[float, int, None]:  # Area in hectares
        """Area in hectares"""
    @property
    def area_km(self) -> Union[float, None]:  # Area in square kilometers
        """Area in square kilometers"""
    @property
    def user_id(self) -> str: ...

class Soil:
    def __init__(self, reference_time: int, surface_temp: float, ten_cm_temp: float, 
                 moisture: float, polygon_id: str = None): ...
    
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
        """
        Get measurement time.
        
        Parameters:
        - timeformat: 'unix', 'iso', or 'date'
        
        Returns:
        Timestamp in requested format
        """
    
    def surface_temp(self, unit: str = 'kelvin') -> float:
        """
        Get soil surface temperature.
        
        Parameters:
        - unit: 'kelvin', 'celsius', or 'fahrenheit'
        
        Returns:
        Temperature in requested unit
        """
    
    def ten_cm_temp(self, unit: str = 'kelvin') -> float:
        """
        Get soil temperature at 10cm depth.
        
        Parameters:
        - unit: 'kelvin', 'celsius', or 'fahrenheit'
        
        Returns:
        Temperature in requested unit
        """
    
    @property
    def moisture(self) -> float:  # Soil moisture in m³/m³
        """Soil moisture in m³/m³"""
    @property
    def polygon_id(self) -> str: ...
    
    def to_dict(self) -> dict: ...

class MetaImage:
    def __init__(self, url: str, preset: str, satellite_name: str, acquisition_time: int,
                 valid_data_percentage: float, cloud_coverage_percentage: float,
                 sun_azimuth: float, sun_elevation: float, polygon_id: str = None, stats_url: str = None): ...
    
    def acquisition_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
        """
        Get image acquisition time.
        
        Parameters:
        - timeformat: 'unix', 'iso', or 'date'
        
        Returns:
        Timestamp in requested format
        """
    
    @property
    def url(self) -> str: ...
    @property
    def preset(self) -> str: ...
    @property
    def satellite_name(self) -> str: ...
    @property
    def valid_data_percentage(self) -> float: ...
    @property
    def cloud_coverage_percentage(self) -> float: ...
    @property
    def sun_azimuth(self) -> float: ...
    @property
    def sun_elevation(self) -> float: ...
    @property
    def polygon_id(self) -> str: ...
    @property
    def stats_url(self) -> str: ...

class SatelliteImage:
    def __init__(self, metadata: MetaImage, data, downloaded_on: int = None, palette: str = None): ...
    
    def downloaded_on(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
        """
        Get download timestamp.
        
        Parameters:
        - timeformat: 'unix', 'iso', or 'date'
        
        Returns:
        Timestamp in requested format
        """
    
    def persist(self, path_to_file: str) -> None:
        """
        Save image to disk.
        
        Parameters:
        - path_to_file: File path to save the image
        """
    
    @property
    def metadata(self) -> MetaImage: ...
    @property
    def data(self):  # Image data
        """Image data"""
    @property
    def palette(self) -> str: ...

Agricultural Enums

# Image presets for different analysis types
class PresetEnum:
    TRUE_COLOR = "truecolor"      # Natural color composite
    FALSE_COLOR = "falsecolor"    # False color composite
    NDVI = "ndvi"                # Normalized Difference Vegetation Index
    EVI = "evi"                  # Enhanced Vegetation Index

# Color palettes for visualization
class PaletteEnum:
    GREEN = "green"
    BLACK_AND_WHITE = "bw"
    CONTRAST_SHIFTED = "contrast_shifted"
    CONTRAST_CONTINUOUS = "contrast_continuous"

# Supported satellites
class SatelliteEnum:
    LANDSAT_8 = "landsat-8"
    SENTINEL_2 = "sentinel-2"

Vegetation Indices

  • NDVI (Normalized Difference Vegetation Index): Measures vegetation health and density using red and near-infrared bands. Values range from -1 to 1, with higher values indicating healthier vegetation.

  • EVI (Enhanced Vegetation Index): Similar to NDVI but more sensitive to canopy structural variations and reduces atmospheric and soil background effects.

Satellite Information

  • Landsat 8: NASA/USGS satellite with 30m resolution, 16-day revisit cycle
  • Sentinel-2: ESA satellite constellation with 10-20m resolution, 5-day revisit cycle

Install with Tessl CLI

npx tessl i tessl/pypi-pyowm

docs

agro.md

air-pollution.md

alerts.md

geocoding.md

index.md

stations.md

tiles.md

uv-index.md

weather.md

tile.json