0
# Agricultural API
1

2
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.
3

4
## Capabilities
5

6
### Polygon Management
7

8
Create and manage polygonal areas for agricultural monitoring.
9

10
```python { .api }
11
class AgroManager:
12
    def agro_api_version(self) -> tuple:
13
        """
14
        Get Agro API version.
15
        
16
        Returns:
17
        Tuple representing the API version
18
        """
19
    
20
    def create_polygon(self, geopolygon: GeoPolygon, name: str = None) -> Polygon:
21
        """
22
        Create a new polygon for agricultural monitoring.
23
        
24
        Parameters:
25
        - geopolygon: GeoPolygon object defining the area
26
        - name: Optional name for the polygon
27
        
28
        Returns:
29
        Polygon object representing the created area
30
        """
31
    
32
    def get_polygons(self) -> List[Polygon]:
33
        """
34
        Get all user-created polygons.
35
        
36
        Returns:
37
        List of all Polygon objects owned by the user
38
        """
39
    
40
    def get_polygon(self, polygon_id: str) -> Polygon:
41
        """
42
        Get a specific polygon by ID.
43
        
44
        Parameters:
45
        - polygon_id: Unique polygon identifier
46
        
47
        Returns:
48
        Polygon object for the specified ID
49
        """
50
    
51
    def update_polygon(self, polygon: Polygon) -> None:
52
        """
53
        Update polygon name.
54
        
55
        Parameters:
56
        - polygon: Polygon object with updated information
57
        """
58
    
59
    def delete_polygon(self, polygon: Polygon) -> None:
60
        """
61
        Delete a polygon.
62
        
63
        Parameters:
64
        - polygon: Polygon object to delete
65
        """
66
```
67

68
### Soil Data
69

70
Retrieve soil temperature and moisture data for agricultural areas.
71

72
```python { .api }
73
class AgroManager:
74
    def soil_data(self, polygon_id: str) -> Soil:
75
        """
76
        Get soil data for a polygon.
77
        
78
        Parameters:
79
        - polygon_id: Polygon ID to get soil data for
80
        
81
        Returns:
82
        Soil object with temperature and moisture data
83
        """
84
```
85

86
### Satellite Imagery
87

88
Search and download satellite imagery for agricultural analysis.
89

90
```python { .api }
91
class AgroManager:
92
    def search_satellite_imagery(self, polygon_id: str, acquired_from: int, acquired_to: int, img_w: int = None, img_h: int = None) -> SatelliteImagerySearchResultSet:
93
        """
94
        Search for satellite imagery within date range.
95
        
96
        Parameters:
97
        - polygon_id: Polygon ID to search imagery for
98
        - acquired_from: Start date (UNIX timestamp)
99
        - acquired_to: End date (UNIX timestamp)
100
        - img_w: Image width in pixels (optional)
101
        - img_h: Image height in pixels (optional)
102
        
103
        Returns:
104
        SatelliteImagerySearchResultSet containing satellite imagery search results
105
        """
106
    
107
    def download_satellite_image(self, satellite_image: SatelliteImage, preset: str, palette: str = None):
108
        """
109
        Download satellite image data.
110
        
111
        Parameters:
112
        - metaimage: MetaImage object to download
113
        - x: Tile X coordinate (optional)
114
        - y: Tile Y coordinate (optional)
115
        - zoom: Zoom level (optional)
116
        - palette: Color palette (GREEN, BLACK_AND_WHITE, CONTRAST_SHIFTED, CONTRAST_CONTINUOUS)
117
        
118
        Returns:
119
        SatelliteImage object with downloaded data
120
        """
121
    
122
    def stats_for_satellite_image(self, metaimage: MetaImage) -> dict:
123
        """
124
        Get statistics for satellite image.
125
        
126
        Parameters:
127
        - metaimage: MetaImage object to get statistics for
128
        
129
        Returns:
130
        Dictionary with image statistics
131
        """
132
```
133

134
## Usage Examples
135

136
### Creating and Managing Polygons
137

138
```python
139
from pyowm import OWM
140
from pyowm.utils.geo import Polygon as GeoPolygon
141

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

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

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

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

161
# Update polygon name
162
polygon.name = "Updated Farm Field 1"
163
agro_mgr.update_polygon(polygon)
164
```
165

166
### Soil Data Analysis
167

168
```python
169
# Get soil data for a polygon
170
soil = agro_mgr.soil_data(polygon)
171

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

177
# Temperature comparison
178
surface_temp_c = soil.surface_temp('celsius')
179
deep_temp_c = soil.ten_cm_temp('celsius')
180
temp_diff = surface_temp_c - deep_temp_c
181
print(f"Temperature difference (surface - 10cm): {temp_diff:.2f}°C")
182
```
183

184
### Satellite Imagery Search and Download
185

186
```python
187
from datetime import datetime, timedelta
188
from pyowm.agroapi10.enums import PresetEnum, SatelliteEnum, PaletteEnum
189

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

194
imagery = agro_mgr.search_satellite_imagery(
195
    polygon_id=polygon.id,
196
    acquired_from=int(start_date.timestamp()),
197
    acquired_to=int(end_date.timestamp()),
198
    preset=PresetEnum.NDVI,
199
    acquired_by=SatelliteEnum.SENTINEL_2,
200
    max_cloud_coverage=20  # Less than 20% cloud cover
201
)
202

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

205
# Download the most recent image
206
if imagery:
207
    latest_image = imagery[0]  # Images are sorted by acquisition time
208
    print(f"Latest image: {latest_image.acquisition_time('iso')}")
209
    print(f"Cloud coverage: {latest_image.cloud_coverage_percentage}%")
210
    print(f"Valid data: {latest_image.valid_data_percentage}%")
211
    
212
    # Download with GREEN palette for visualization
213
    satellite_img = agro_mgr.download_satellite_image(
214
        latest_image, 
215
        palette=PaletteEnum.GREEN
216
    )
217
    
218
    print(f"Downloaded image: {satellite_img.downloaded_on('iso')}")
219
    
220
    # Save to disk
221
    satellite_img.persist('/path/to/save/ndvi_image.png')
222
    
223
    # Get image statistics
224
    stats = agro_mgr.stats_for_satellite_image(latest_image)
225
    print(f"Image statistics: {stats}")
226
```
227

228
### Vegetation Index Analysis
229

230
```python
231
# Search for different vegetation indices
232
ndvi_images = agro_mgr.search_satellite_imagery(
233
    polygon_id=polygon.id,
234
    acquired_from=int(start_date.timestamp()),
235
    acquired_to=int(end_date.timestamp()),
236
    preset=PresetEnum.NDVI,
237
    max_cloud_coverage=10
238
)
239

240
evi_images = agro_mgr.search_satellite_imagery(
241
    polygon_id=polygon.id,
242
    acquired_from=int(start_date.timestamp()),
243
    acquired_to=int(end_date.timestamp()),
244
    preset=PresetEnum.EVI,
245
    max_cloud_coverage=10
246
)
247

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

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

257
## Data Types
258

259
```python { .api }
260
class Polygon:
261
    def __init__(self, id: str, name: str = None, geopolygon: GeoPolygon = None, 
262
                 center: GeoPoint = None, area: Union[float, int] = None, user_id: str = None): ...
263
    
264
    @property
265
    def id(self) -> str: ...
266
    @property
267
    def name(self) -> str: ...
268
    @property
269
    def geopolygon(self) -> GeoPolygon: ...
270
    @property
271
    def center(self) -> GeoPoint: ...
272
    @property
273
    def area(self) -> Union[float, int, None]:  # Area in hectares
274
        """Area in hectares"""
275
    @property
276
    def area_km(self) -> Union[float, None]:  # Area in square kilometers
277
        """Area in square kilometers"""
278
    @property
279
    def user_id(self) -> str: ...
280

281
class Soil:
282
    def __init__(self, reference_time: int, surface_temp: float, ten_cm_temp: float, 
283
                 moisture: float, polygon_id: str = None): ...
284
    
285
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
286
        """
287
        Get measurement time.
288
        
289
        Parameters:
290
        - timeformat: 'unix', 'iso', or 'date'
291
        
292
        Returns:
293
        Timestamp in requested format
294
        """
295
    
296
    def surface_temp(self, unit: str = 'kelvin') -> float:
297
        """
298
        Get soil surface temperature.
299
        
300
        Parameters:
301
        - unit: 'kelvin', 'celsius', or 'fahrenheit'
302
        
303
        Returns:
304
        Temperature in requested unit
305
        """
306
    
307
    def ten_cm_temp(self, unit: str = 'kelvin') -> float:
308
        """
309
        Get soil temperature at 10cm depth.
310
        
311
        Parameters:
312
        - unit: 'kelvin', 'celsius', or 'fahrenheit'
313
        
314
        Returns:
315
        Temperature in requested unit
316
        """
317
    
318
    @property
319
    def moisture(self) -> float:  # Soil moisture in m³/m³
320
        """Soil moisture in m³/m³"""
321
    @property
322
    def polygon_id(self) -> str: ...
323
    
324
    def to_dict(self) -> dict: ...
325

326
class MetaImage:
327
    def __init__(self, url: str, preset: str, satellite_name: str, acquisition_time: int,
328
                 valid_data_percentage: float, cloud_coverage_percentage: float,
329
                 sun_azimuth: float, sun_elevation: float, polygon_id: str = None, stats_url: str = None): ...
330
    
331
    def acquisition_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
332
        """
333
        Get image acquisition time.
334
        
335
        Parameters:
336
        - timeformat: 'unix', 'iso', or 'date'
337
        
338
        Returns:
339
        Timestamp in requested format
340
        """
341
    
342
    @property
343
    def url(self) -> str: ...
344
    @property
345
    def preset(self) -> str: ...
346
    @property
347
    def satellite_name(self) -> str: ...
348
    @property
349
    def valid_data_percentage(self) -> float: ...
350
    @property
351
    def cloud_coverage_percentage(self) -> float: ...
352
    @property
353
    def sun_azimuth(self) -> float: ...
354
    @property
355
    def sun_elevation(self) -> float: ...
356
    @property
357
    def polygon_id(self) -> str: ...
358
    @property
359
    def stats_url(self) -> str: ...
360

361
class SatelliteImage:
362
    def __init__(self, metadata: MetaImage, data, downloaded_on: int = None, palette: str = None): ...
363
    
364
    def downloaded_on(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
365
        """
366
        Get download timestamp.
367
        
368
        Parameters:
369
        - timeformat: 'unix', 'iso', or 'date'
370
        
371
        Returns:
372
        Timestamp in requested format
373
        """
374
    
375
    def persist(self, path_to_file: str) -> None:
376
        """
377
        Save image to disk.
378
        
379
        Parameters:
380
        - path_to_file: File path to save the image
381
        """
382
    
383
    @property
384
    def metadata(self) -> MetaImage: ...
385
    @property
386
    def data(self):  # Image data
387
        """Image data"""
388
    @property
389
    def palette(self) -> str: ...
390
```
391

392
## Agricultural Enums
393

394
```python { .api }
395
# Image presets for different analysis types
396
class PresetEnum:
397
    TRUE_COLOR = "truecolor"      # Natural color composite
398
    FALSE_COLOR = "falsecolor"    # False color composite
399
    NDVI = "ndvi"                # Normalized Difference Vegetation Index
400
    EVI = "evi"                  # Enhanced Vegetation Index
401

402
# Color palettes for visualization
403
class PaletteEnum:
404
    GREEN = "green"
405
    BLACK_AND_WHITE = "bw"
406
    CONTRAST_SHIFTED = "contrast_shifted"
407
    CONTRAST_CONTINUOUS = "contrast_continuous"
408

409
# Supported satellites
410
class SatelliteEnum:
411
    LANDSAT_8 = "landsat-8"
412
    SENTINEL_2 = "sentinel-2"
413
```
414

415
## Vegetation Indices
416

417
- **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.
418

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

421
## Satellite Information
422

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