Working with Crops 🌾
Overview
The Crops domain provides a hierarchical catalog system for managing agricultural crop species and their localized configurations.
Cardinality summary
- Crop ➜ 0..1 Parent Crop (hierarchical structure)
- Crop ➜ 1..* Crop Names (multilingual support)
- Crop ➜ 1..* Localized Crops (country-specific configurations)
Crop (Species Level)
├── Crop Names 1..*
└── Localized Crops 1..*
Key Concepts
| Concept | Description |
|---|---|
| Crop | agricultural species entity with global properties |
| Crop Names | Multilingual name translations |
| Localized Crop | Country/region-specific crop configuration with local parameters |
| EPPO Code | Unique taxonomic identifier from the EPPO Global Database (European and Mediterranean Plant Protection Organization). These standardized codes ensure consistent plant species identification across agricultural systems and countries. |
API Documentation
For complete API reference including request/response schemas, authentication, and interactive testing, visit:
📚 Crops API Documentation - Interactive API documentation with request/response examples
Available Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /v2/catalog/crops | Create a new crop |
| GET | /v2/catalog/crops/{id} | Get crop by ID |
| PUT | /v2/catalog/crops/{id} | Update crop information |
| DELETE | /v2/catalog/crops/{id} | Delete a crop |
| GET | /v2/catalog/crops | List crops with filtering and pagination |
| GET | /v2/catalog/crops/localized/{id} | Get crop by localized crop ID |
| POST | /v2/catalog/crops/{cropId}/image | Upload an image to a crop |
Business Rules
Name Uniqueness
Each crop must have unique language codes across its names. A crop cannot have multiple names in the same language.
Location Uniqueness
Each crop must have unique locations across its localized crop configurations. A crop cannot have multiple localized configurations for the same country.
EPPO Code Validation
When associating a crop with an EPPO taxonomic code:
- EPPO codes are standardized plant identifiers from the EPPO Global Database
- If
eppo_codeis provided, it must exist in the EPPO database - Invalid EPPO codes will result in an error
- EPPO codes ensure interoperability with international phytosanitary and agricultural systems
- Examples:
ZEAMX(Zea mays - Maize),TRZAX(Triticum aestivum - Wheat),HORVX(Hordeum vulgare - Barley)
Error Codes
| Code | Message | HTTP Status | When Triggered |
|---|---|---|---|
| ECRP001 | Parent crop does not exist | 404 NOT_FOUND | parent_id references a non-existent crop during CREATE or UPDATE |
| ECRP002 | Crop does not exist | 404 NOT_FOUND | Requested crop ID not found during GET, UPDATE, or DELETE operations |
| ECRP003 | The crop cannot be its parent id | 400 BAD_REQUEST | parent_id equals crop ID during UPDATE operation |
| ECRP004 | The crop can not have more than 1 name for the same language | 400 BAD_REQUEST | Duplicate language values in name array during CREATE or UPDATE |
| ELCR001 | The same crop can not have duplicated countries | 400 BAD_REQUEST | Duplicate location values in localized_crops array during CREATE or UPDATE |
| ELCR002 | This location does not exist for this crop | 404 NOT_FOUND | Querying a location that doesn't exist for the specified crop |
| ELCR003 | The localized id does not exist | 404 NOT_FOUND | Localized crop ID not found in database |
| ELCR004 | One or more of the localized crops Ids does not exist | 404 NOT_FOUND | One or more IDs in a localized crops list don't exist |
| ELCR005 | Crop not found | 404 NOT_FOUND | Crop not found through adapter/external service lookup |
Typical Workflows
Basic Crop Management
- Create Crop - Set up new crop species with multilingual names and localized configurations
- Update Crop - Modify crop properties like names, images, or localized settings
- Retrieve Crop - Get crop details for display or analysis
- List Crops - Query crops by filters like specialization type or parent relationship
- Delete Crop - Soft delete crops no longer in use
Next Steps
After creating your crops, you can: