# Transport API Reference The Transport API enables seed-to-seed tracking of all plant movement and transformation events within the LocalGreenChain ecosystem. ## Base URL ``` Development: http://localhost:3001/api/transport Production: https://api.localgreenchain.org/transport ``` ## Authentication All transport endpoints require authentication: ```http Authorization: Bearer X-Wallet-Address: ``` ## Endpoints ### Record Seed Acquisition Record the acquisition of seeds from any source. ```http POST /api/transport/seed-acquisition Content-Type: application/json { "seedBatchId": "batch-2025-001", "sourceType": "seed_bank", "species": "Solanum lycopersicum", "variety": "Cherokee Purple", "quantity": 50, "quantityUnit": "seeds", "geneticLineageId": "lineage-tomato-cp-001", "generation": 0, "fromLocation": { "latitude": 40.7128, "longitude": -74.0060, "locationType": "seed_bank", "facilityName": "Baker Creek Seeds" }, "toLocation": { "latitude": 40.7589, "longitude": -73.9851, "locationType": "farm", "facilityName": "Urban Farm NYC" }, "transportMethod": "local_delivery", "certifications": ["organic", "heirloom"] } ``` **Response:** ```json { "success": true, "event": { "id": "evt-seed-acq-123", "timestamp": "2025-01-15T10:30:00Z", "eventType": "seed_acquisition", "status": "verified" }, "block": { "index": 5, "hash": "0000abc123...", "carbonFootprintKg": 0.02, "foodMiles": 5.2 } } ``` --- ### Record Planting Record when seeds are planted. ```http POST /api/transport/planting Content-Type: application/json { "seedBatchId": "batch-2025-001", "plantIds": ["plant-001", "plant-002", "plant-003"], "plantingMethod": "transplant", "quantityPlanted": 25, "growingEnvironment": "vertical_farm", "location": { "latitude": 40.7589, "longitude": -73.9851, "locationType": "vertical_farm", "facilityName": "Urban Farm NYC" }, "expectedHarvestDate": "2025-03-15T00:00:00Z" } ``` **Response:** ```json { "success": true, "event": { "id": "evt-planting-124", "timestamp": "2025-01-20T08:00:00Z", "eventType": "planting", "plantIds": ["plant-001", "plant-002", "plant-003"] }, "block": { "index": 6, "hash": "0000def456..." } } ``` --- ### Record Growing Transport Record plant movement during growing (transplanting, relocating). ```http POST /api/transport/growing Content-Type: application/json { "plantIds": ["plant-001", "plant-002"], "reason": "transplant", "plantStage": "seedling", "handlingMethod": "potted", "fromLocation": { "latitude": 40.7589, "longitude": -73.9851, "locationType": "greenhouse", "facilityName": "Seedling House A" }, "toLocation": { "latitude": 40.7589, "longitude": -73.9852, "locationType": "vertical_farm", "facilityName": "Main Growing Tower" }, "transportMethod": "walking", "rootDisturbance": "minimal", "acclimatizationRequired": true, "acclimatizationDays": 3 } ``` --- ### Record Harvest Record harvest events with yield data. ```http POST /api/transport/harvest Content-Type: application/json { "plantIds": ["plant-001", "plant-002", "plant-003"], "harvestBatchId": "harvest-2025-050", "harvestType": "full", "produceType": "tomatoes", "grossWeight": 15.5, "netWeight": 14.2, "weightUnit": "kg", "qualityGrade": "A", "packagingType": "compostable_clamshell", "temperatureRequired": { "min": 10, "max": 15, "optimal": 12, "unit": "celsius" }, "shelfLifeHours": 168, "seedsSaved": true, "seedBatchIdCreated": "batch-2025-002" } ``` **Response:** ```json { "success": true, "event": { "id": "evt-harvest-125", "timestamp": "2025-03-15T06:00:00Z", "eventType": "harvest", "harvestBatchId": "harvest-2025-050", "netWeight": 14.2 }, "block": { "index": 25, "hash": "0000ghi789...", "carbonFootprintKg": 0.1 }, "seedBatch": { "id": "batch-2025-002", "parentPlants": ["plant-001", "plant-002", "plant-003"], "generation": 1 } } ``` --- ### Record Distribution Record movement through distribution chain. ```http POST /api/transport/distribution Content-Type: application/json { "batchIds": ["harvest-2025-050"], "destinationType": "consumer", "fromLocation": { "latitude": 40.7589, "longitude": -73.9851, "locationType": "vertical_farm" }, "toLocation": { "latitude": 40.7614, "longitude": -73.9776, "locationType": "consumer" }, "transportMethod": "bicycle", "orderId": "order-2025-1234", "customerType": "individual", "deliveryWindow": { "start": "2025-03-15T14:00:00Z", "end": "2025-03-15T18:00:00Z" } } ``` --- ### Record Seed Saving Record seed saving from harvested plants. ```http POST /api/transport/seed-saving Content-Type: application/json { "parentPlantIds": ["plant-001", "plant-002"], "newSeedBatchId": "batch-2025-003", "collectionMethod": "fermentation", "seedCount": 200, "seedWeight": 15, "seedWeightUnit": "grams", "storageConditions": { "temperature": 10, "humidity": 40, "lightExposure": "dark", "containerType": "vacuum_sealed", "desiccant": true, "estimatedViability": 5 }, "newGenerationNumber": 2, "availableForSharing": true, "sharingTerms": "trade" } ``` --- ### Record Seed Sharing Record when seeds are shared with others. ```http POST /api/transport/seed-sharing Content-Type: application/json { "seedBatchId": "batch-2025-003", "quantityShared": 25, "quantityUnit": "seeds", "sharingType": "trade", "tradeDetails": "Traded for 25 basil seeds", "recipientId": "user-xyz-456", "fromLocation": {...}, "toLocation": {...}, "recipientAgreement": true, "growingCommitment": "Will grow and report back", "reportBackRequired": true } ``` --- ## Query Endpoints ### Get Plant Journey Get complete transport history for a plant. ```http GET /api/transport/journey/:plantId ``` **Response:** ```json { "plantId": "plant-001", "seedBatchOrigin": "batch-2025-001", "currentCustodian": "user-abc-123", "currentLocation": { "latitude": 40.7614, "longitude": -73.9776, "locationType": "consumer" }, "currentStage": "post_harvest", "events": [ { "eventType": "seed_acquisition", "timestamp": "2025-01-15T10:30:00Z", "fromLocation": {...}, "toLocation": {...} }, { "eventType": "planting", "timestamp": "2025-01-20T08:00:00Z", ... }, ... ], "totalFoodMiles": 12.5, "totalCarbonKg": 0.35, "daysInTransit": 2, "daysGrowing": 54, "generation": 1, "ancestorPlantIds": ["parent-plant-001"], "descendantSeedBatches": ["batch-2025-003"] } ``` --- ### Get Environmental Impact Get carbon footprint and food miles for a user. ```http GET /api/transport/footprint/:userId ``` **Response:** ```json { "totalCarbonKg": 15.5, "totalFoodMiles": 250, "carbonPerKgProduce": 0.25, "milesPerKgProduce": 4.0, "breakdownByMethod": { "bicycle": { "distance": 50, "carbon": 0 }, "electric_vehicle": { "distance": 150, "carbon": 3.0 }, "walking": { "distance": 50, "carbon": 0 } }, "breakdownByEventType": { "seed_acquisition": { "count": 5, "carbon": 0.5 }, "distribution": { "count": 50, "carbon": 10.0 }, ... }, "comparisonToConventional": { "carbonSaved": 140.5, "milesSaved": 74750, "percentageReduction": 90 } } ``` --- ### Verify Block Verify a transport block's integrity. ```http GET /api/transport/verify/:blockHash ``` **Response:** ```json { "valid": true, "block": { "index": 25, "hash": "0000ghi789...", "previousHash": "0000fgh678...", "timestamp": "2025-03-15T06:00:00Z" }, "chainValid": true, "crossReferences": [ { "userId": "user-xyz-456", "blockIndex": 12, "type": "receiver", "verified": true } ] } ``` --- ### Generate QR Code Generate QR code data for a plant or batch. ```http GET /api/transport/qr/:plantId ``` **Response:** ```json { "plantId": "plant-001", "blockchainAddress": "0x1234567890abcdef...", "quickLookupUrl": "https://localgreenchain.org/track/plant-001", "lineageHash": "a1b2c3d4e5f6...", "currentCustodian": "user-abc-123", "lastEventType": "distribution", "lastEventTimestamp": "2025-03-15T14:30:00Z", "verificationCode": "A1B2C3D4", "qrCodeImage": "data:image/png;base64,..." } ``` --- ## Error Codes | Code | Message | Description | |------|---------|-------------| | 400 | Invalid request | Missing or invalid parameters | | 401 | Unauthorized | Invalid or missing auth token | | 403 | Forbidden | Not authorized for this resource | | 404 | Not found | Plant/batch/block not found | | 409 | Conflict | Duplicate event or chain conflict | | 422 | Validation error | Data validation failed | | 500 | Server error | Internal server error | ## Rate Limits | Endpoint Type | Limit | Window | |---------------|-------|--------| | Read (GET) | 100 | per minute | | Write (POST) | 20 | per minute | | Batch operations | 5 | per minute | ## Webhooks Subscribe to transport events: ```http POST /api/transport/webhooks Content-Type: application/json { "url": "https://your-server.com/webhook", "events": ["seed_acquisition", "harvest", "distribution"], "filters": { "plantIds": ["plant-001", "plant-002"], "userId": "user-abc-123" } } ```