API Documentation

The AgWise API provides programmatic access to agricultural advisory data and recommendations. This RESTful API enables partners to integrate location-specific crop and livestock advisory services into their own applications and platforms.

Overview

The AgWise API is built on R Plumber and provides endpoints for accessing agricultural advisory data including yield predictions, fertilizer recommendations, integrated soil fertility management (ISFM) advice, optimal planting dates, suitable crop cultivars, forage suitability assessments, and livestock feed recommendations. All endpoints return JSON responses with location metadata and advisory recommendations.

Note: The Base URL shown below reflects your current configuration. For local development, use http://localhost:8000. For production deployment, configure your server's IP address or domain name.

Base URL

http://localhost:8000

Authentication

The API requires token-based authentication for all advisory endpoints. Users must register and login to obtain an authentication token. Include the token in the request header as X-Auth-Token: YOUR_TOKEN. Tokens expire after 24 hours.

Authentication Endpoints

  • POST /auth/register - Register a new user account (requires: first_name, last_name, username, password, email, organisation)
  • POST /auth/login - Login and receive authentication token (24-hour validity)
  • POST /auth/validate - Validate an existing token

Response Format

Advisory endpoints return JSON format with location metadata and advisory-specific data. Map endpoints return HTML content for iframe embedding. Error responses include an error field with descriptive messages.

Advisory Service Endpoints

These endpoints provide agricultural advisory recommendations based on location and advisory type. All advisory endpoints use POST method and return detailed recommendations with statistical analysis.

POST/advisory/yield

Provides optimal yield predictions across different rainfall scenarios (above normal, normal, below normal). Returns yield estimates in kg/ha with location metadata and forecast period.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name for more specific recommendations
  • admin3 (optional): District name for most specific recommendations
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "forecast_period": "July 2022", "yield_data": [{"scenario": "above normal", "mean_yield": 8500}, {"scenario": "normal", "mean_yield": 8000}, {"scenario": "below normal", "mean_yield": 7500}]}

POST/advisory/fertilizer

Provides fertilizer application recommendations for Urea and NPS (Nitrogen-Phosphorus-Sulfur) across different rainfall scenarios. Returns rates in kg/ha optimized for local soil conditions and forecasted rainfall patterns.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "forecast_period": "July 2022", "fertilizer_data": [{"fertilizer_type": "urea", "scenario": "above normal", "mean_rate": 250}, {"fertilizer_type": "urea", "scenario": "normal", "mean_rate": 230}, {"fertilizer_type": "urea", "scenario": "below normal", "mean_rate": 210}, {"fertilizer_type": "nps", "scenario": "above normal", "mean_rate": 180}, {"fertilizer_type": "nps", "scenario": "normal", "mean_rate": 170}, {"fertilizer_type": "nps", "scenario": "below normal", "mean_rate": 160}]}

POST/advisory/isfm

Provides Integrated Soil Fertility Management recommendations including organic amendments (compost and vermi-compost) application rates. Returns recommendations in tons/ha for sustainable soil health improvement.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "forecast_period": "July 2022", "isfm_data": [{"isfm_type": "compost", "scenario": "above normal", "mean_rate": 20}, {"isfm_type": "compost", "scenario": "normal", "mean_rate": 18}, {"isfm_type": "compost", "scenario": "below normal", "mean_rate": 16}, {"isfm_type": "vcompost", "scenario": "above normal", "mean_rate": 15}, {"isfm_type": "vcompost", "scenario": "normal", "mean_rate": 14}, {"isfm_type": "vcompost", "scenario": "below normal", "mean_rate": 12}]}

POST/advisory/planting Coming Soon

Provides optimal planting date recommendations based on seasonal climate forecasts. Returns planting windows with start/end dates and associated risk levels for different planting periods. This endpoint is currently under development and will be available in a future release.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
  • crop (optional): Crop name (default: "wheat")
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "planting_data": [{"window": "Early", "start_date": "June 1", "end_date": "June 14", "risk_level": "Medium"}, {"window": "Optimal", "start_date": "June 15", "end_date": "June 30", "risk_level": "Low"}, {"window": "Late", "start_date": "July 1", "end_date": "July 15", "risk_level": "High"}]}

POST/advisory/cultivar Coming Soon

Provides suitable crop cultivar recommendations based on local agro-ecological conditions. Returns cultivar names with suitability scores, maturity periods, and yield potential ratings. This endpoint is currently under development and will be available in a future release.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
  • crop (optional): Crop name (default: "wheat")
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "cultivar_data": [{"cultivar_name": "Variety A", "suitability_score": 90, "maturity_days": 120, "yield_potential": "High"}, {"cultivar_name": "Variety B", "suitability_score": 85, "maturity_days": 130, "yield_potential": "Medium"}, {"cultivar_name": "Variety C", "suitability_score": 75, "maturity_days": 110, "yield_potential": "Medium"}]}

POST/advisory/forage Coming Soon

Provides forage variety suitability assessments for livestock feed production. Returns suitability scores (0-100) for different forage varieties based on local climate and soil conditions. This endpoint is currently under development and will be available in a future release.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "forage_data": [{"forage_variety": "Napier Grass", "suitability_score": 85}, {"forage_variety": "Rhodes Grass", "suitability_score": 75}, {"forage_variety": "Desho Grass", "suitability_score": 90}]}

POST/advisory/feed Coming Soon

Provides livestock feed recommendations including daily feed requirements and nutritional balance for optimal animal health and productivity. Returns feed amounts in kg/day per animal. This endpoint is currently under development and will be available in a future release.

Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
Example Response:
{"location": {"admin0": "Ethiopia", "admin1": "Oromia", "admin2": null, "admin3": null, "center": {"lat": 14.0, "lon": 38.0}}, "feed_data": [{"feed_type": "Concentrate", "recommended_amount": 2.5}, {"feed_type": "Hay", "recommended_amount": 8.0}, {"feed_type": "Silage", "recommended_amount": 12.0}]}

Map Visualization Endpoints

These endpoints generate interactive maps showing spatial distribution of advisory recommendations across the selected geographic area.

GET/maps/{type}

Generates interactive maps for visualizing advisory data spatially. The {type} parameter specifies the advisory type (yield, fertilizer, isfm, forage, feed). Returns HTML content for iframe embedding.

URL Parameters:
  • type (required): Advisory type - one of: yield, fertilizer, isfm
Query Parameters:
  • admin0 (required): Country name
  • admin1 (required): Region name
  • admin2 (optional): Zone name
  • admin3 (optional): District name
Example Request:
GET /maps/yield?admin0=Ethiopia&admin1=Oromia&admin2=Arsi

Note: Map endpoints are available for yield, fertilizer, isfm, and forage advisory types. Feed map visualizations are not yet implemented.

Error Handling

The API uses standard HTTP status codes and returns error information in JSON format:

  • 200 OK: Successful request
  • 400 Bad Request: Missing or invalid parameters
  • 404 Not Found: Requested resource not found
  • 500 Internal Server Error: Server processing error
Error Response Format:
{"error": "Invalid admin0 parameter. Country not found in database."}

Rate Limiting

The API implements rate limiting of 100 requests per minute per IP address to ensure optimal performance for all users. If you exceed this limit, you will receive a 429 (Too Many Requests) response. Please implement appropriate request throttling in your applications.

Support

For technical support, questions about the API, or to report issues, please contact our development team through the Contact Us page.