Working with Fields 🌾

Overview

Fields are digital representations of your farming areas within the Cropwise platform, combining geographic data and seasonal context. Fields are essential for precise agricultural management, enabling you to store information and gain valuable insights about smaller, delimited portions of land throughout your farming operation.

Field Hierarchy

Workspace
└── Organization
    └── Property
        └── Field ← You are here

API Documentation

For complete API reference including request/response schemas, authentication, and interactive testing, visit:

📚 Fields API Documentation - Interactive API documentation with request/response examples

Available Endpoints

• POST /v2/fields - Create a new field
• GET /v2/fields/{id} - Get field by ID
• PUT /v2/fields/{id} - Update field information
• DELETE /v2/fields/{id} - Delete a field
• GET /v2/properties/{property_id}/fields - List fields by property

Field Attributes

Core Attributes

Read-only Attributes

Best Practices

Field Creation

• Ensure property_id exists before creating fields
• Use descriptive and consistent field names
• Provide accurate declared_area in hectares
• Set appropriate validity periods using event_date

Geometry Management

• Use valid GeoJSON Polygon format for field boundaries
• Ensure coordinates are in [longitude, latitude] format
• Close polygon boundaries (first and last coordinates must match)
• Use precise GPS coordinates for accuracy
• Include reference points for better field identification
• Coordinates should have 6 decimal places for optimal precision (10⁻⁶ degrees ≈ 0.11 meters at the equator)

Data Organization

• Apply consistent naming conventions (e.g., "Field 1A", "Field 1B")
• Keep field data updated when conditions change
• Monitor calculated vs declared area discrepancies

Performance Optimization

• Cache field data locally when possible
• Use reference_date parameter for historical queries
• Keep geometry complexity reasonable for performance, use the minimum coordinates as possible

Field Creation Rules & Limitations

Business Logic & Constraints

Name Uniqueness

• name must be unique within the same parent_region_id (case-insensitive)
• name cannot be null, blank, or exceed 255 characters

Area Constraints

• declared_area must be greater than or equal to 0
• The sum of all field areas may be limited by licensing or contract quotas

Region & Property

• parent_region_id must refer to an existing, non-deleted region
• The region must belong to the same property_id as the field
• The region must be a leaf region (cannot have sub-regions)

Geometry Constraints

• If geometry is provided, it must be a valid Polygon or MultiPolygon (GeoJSON)
• Geometry coordinates must be within allowed ranges (longitude ≤ 180, latitude ≤ 90)
• Geometry must not self-intersect
• Geometry must not overlap with other fields in the same period and Property
• If geometry is omitted, the region must still be a leaf and name must be unique

Date Constraints

• event_date must be in valid yyyy-MM-dd format
• event_date cannot be greater than 2038-01-19 (system limitation)
• valid_until cannot be before valid_since

Quota & Licensing

• If the workspace has limited field creation enabled, the total area of fields must not exceed the allowed quota for the contract or plan

Error Codes

Field Errors (Business/DTO)

Geometry Errors (Geometry/Spatial)

Common Error Categories

Common Use Cases

For complete implementation examples including API calls, authentication, and error handling, visit our interactive API documentation:

📚 Fields API Examples → - Interactive examples with code samples

Typical Workflows

Basic Field Management

1. Create Field - Set up new cultivation areas with boundaries and metadata
2. Update Field - Modify field properties like area, name, or geometry
3. Retrieve Field - Get field details for analysis or display
4. List Fields - Query fields by property or organization

Working with Geometry

• Field Boundaries - Define precise field boundaries using GeoJSON Polygon format
• Reference Points - Set center points for field identification and mapping
• Coordinate Systems - Use WGS84 datum with [longitude, latitude] format
• Area Calculation - Compare declared vs calculated areas for validation

Temporal Field Management

• Seasonal Fields - Create fields with specific validity periods
• Historical Queries - Retrieve field data as of specific dates
• Field Evolution - Track changes to field boundaries over time
• Event Dating - Associate field changes with specific agricultural events

Next Steps

After creating your fields, you can:

1. Managing Properties →
2. Working with Organizations →