Managing Properties 🏘️

Overview

Properties represent individual farming locations or land parcels within an organization. They serve as containers for fields and provide geographical and operational context for agricultural activities.

Core Concepts

What is a Property?

A property in Cropwise:

• Represents a physical farm, defined by geographical fields boundaries
• It is part of the farm-field tree structure
• Multiple farms can exist within an organization

Property Hierarchy

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

API Endpoints

All property endpoints are fully documented in our OpenAPI specification. For detailed information about request/response formats, authentication requirements, and interactive examples, please visit:

View Interactive Properties API Documentation →

Available Endpoints

• POST /v2/properties - Create a new property
• GET /v2/properties/{id} - Retrieve property details
• PUT /v2/properties/{id} - Update an existing property
• DELETE /v2/properties/{id} - Delete a property
• GET /v2/properties/{property_id}/fields - List fields for a property

Data Models

For complete data models and schema definitions, please refer to our OpenAPI specification.

Key Concepts

Property Object

Properties follow the PropertyDTO schema with fields including:

• id - Unique identifier
• org_id - Organization identifier
• name - Property name
• time_zone - Property timezone
• reference_point - GeoJSON Point coordinates
• Geographic information (country, state, city, address)
• Calculated fields (total_area, field_count)

Geographic Features

• All coordinates use WGS84 datum (EPSG:4326)
• GeoJSON format with coordinates as [longitude, latitude]
• Reference points represent the property's main location

Examples

For practical examples and step-by-step API usage, please refer to our interactive API documentation where you can test all endpoints directly:

Try Properties API Examples →

Best Practices

Field Requirements

• Always provide required fields: org_id, name and time_zone
• Use valid timezone identifiers: Follow IANA Time Zone Database format
• Validate coordinates: Ensure longitude/latitude are within valid ranges
• UUIDs format: Ensure organization IDs follow UUID v4 format

Naming and Organization

• Use descriptive names that reflect the property's location or characteristics
• Include relevant geographical or operational identifiers
• Maintain consistent naming conventions within your organization
• Property names should be unique within an organization

Geographic Data

• Always provide a reference point for accurate mapping and analysis
• Use GeoJSON Point format with [longitude, latitude] order
• Validate coordinate accuracy before creation
• Consider time zone implications for operational data

Performance Optimization

• Use pagination parameters for large property lists
• Request only needed attributes (e.g., total_area when required)
• Consider caching property data for frequently accessed information

Integration with Other Services

Field Management

Properties serve as containers for fields in the hierarchical structure:

• Create fields within properties using the Fields API
• Manage field boundaries and regions through the Geometry API
• Properties automatically calculate total areas from constituent fields

Satellite Services

Properties with defined reference points can receive:

• Satellite imagery analysis for all contained fields
• Vegetation indices aggregated at property level
• Weather data correlation for regional analysis

Property Creation Rules & Limitations

This section details the validation rules, business logic, and limitations for creating and updating properties in the Cropwise platform.

Property Attributes & Validation Rules

Business Logic & Constraints

Name Uniqueness

• name must be unique within the same organization
• If a property with the same name already exists for the organization, creation will fail

Region Management

• If root_region_id is provided, it must refer to a valid region
• If a property already has a root region, creation or update with a new root region will fail
• If root_region_id is omitted during creation, a root region will be created automatically

Geographic Validation

• reference_point, if provided, must be a valid geographic point (GeoJSON)
• Geometry type must be "Point" with valid [longitude, latitude] coordinates
• Coordinates must be within valid ranges (longitude: -180 to 180, latitude: -90 to 90)

Location Data Validation

• country, if provided, must be a valid country code
• state, if provided, must be a valid state code for the specified country
• city, if provided, must be a valid city name
• zip_code, if provided, must be a valid postal code format
• time_zone, if provided, must be a valid IANA timezone identifier

Detailed Error Codes

The API returns specific error codes when validation or business rules are violated:

Property Creation Flow

1. Attribute Validation: The API checks for required fields, value ranges, and formats
2. Business Validation: The API checks for name uniqueness and root region validity
3. Geographic Validation: The API validates coordinates and geometry types
4. Creation Process: If all validations pass, the property is created with associated resources

Next Steps

After creating your property, you can:

1. Working with Fields →
2. Set up Satellite Monitoring →