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, and forage suitability assessments. All endpoints return JSON responses with location metadata and advisory recommendations.

Base URL

https://api.agwise.org

Authentication

Public point endpoints do not require authentication. They are freely accessible for integration with external applications.

Response Format

All endpoints return JSON format with location metadata and advisory-specific data. Error responses include an error field with descriptive messages.

Public API Endpoints

These point-based advisory endpoints are publicly accessible and accept parameters via both JSON body and URL query parameters. No authentication required.

POST/advisory/yield/point

Get yield predictions for a specific point location and crop.

Parameters:
  • lat (required): Latitude (decimal degrees)
  • lng (required): Longitude (decimal degrees)
  • crop (optional): Crop name (default: "wheat")
  • country_code (optional): Country code - eth, rwa, ken, gha (default: "eth")
  • name (optional): Location name (default: "Point")
Example Request (JSON Body):
POST /advisory/yield/point
{"lat": 9.5, "lng": 40.5, "crop": "wheat", "country_code": "eth", "name": "My Farm"}
Example Request (Query Parameters):
POST /advisory/yield/point?lat=9.5&lng=40.5&crop=wheat&country_code=eth&name=My%20Farm
Example Response:
{"location": {"name": "My Farm", "lat": 9.5, "lng": 40.5, "type": "point"}, "forecast_period": "July 2022", "yield_data": [{"scenario": "Above Normal", "yield_kg_ha": 4500}, {"scenario": "Normal", "yield_kg_ha": 4000}, {"scenario": "Below Normal", "yield_kg_ha": 3500}, {"scenario": "Dominant", "yield_kg_ha": 4200}]}

POST/advisory/fertilizer/point

Get fertilizer recommendations for a specific point location and crop.

Parameters:
  • lat (required): Latitude (decimal degrees)
  • lng (required): Longitude (decimal degrees)
  • crop (optional): Crop name (default: "wheat")
  • country_code (optional): Country code - eth, rwa, ken, gha (default: "eth")
  • name (optional): Location name (default: "Point")
Example Request (JSON Body):
POST /advisory/fertilizer/point
{"lat": 9.5, "lng": 40.5, "crop": "wheat", "country_code": "eth"}
Example Request (Query Parameters):
POST /advisory/fertilizer/point?lat=9.5&lng=40.5&crop=wheat&country_code=eth
Example Response:
{"location": {"name": "Point", "lat": 9.5, "lng": 40.5, "type": "point"}, "forecast_period": "July 2022", "fertilizer_data": [{"fertilizer_type": "Urea", "scenario": "Above Normal", "rate_kg_ha": 150}, {"fertilizer_type": "Urea", "scenario": "Normal", "rate_kg_ha": 130}, {"fertilizer_type": "DAP", "scenario": "Above Normal", "rate_kg_ha": 100}]}

POST/advisory/isfm/point

Get Integrated Soil Fertility Management recommendations for a specific point location and crop.

Parameters:
  • lat (required): Latitude (decimal degrees)
  • lng (required): Longitude (decimal degrees)
  • crop (optional): Crop name (default: "wheat")
  • country_code (optional): Country code - eth, rwa, ken, gha (default: "eth")
  • name (optional): Location name (default: "Point")
Example Request (JSON Body):
POST /advisory/isfm/point
{"lat": 9.5, "lng": 40.5, "crop": "wheat", "country_code": "eth"}
Example Request (Query Parameters):
POST /advisory/isfm/point?lat=9.5&lng=40.5&crop=wheat&country_code=eth
Example Response:
{"location": {"name": "Point", "lat": 9.5, "lng": 40.5, "type": "point"}, "forecast_period": "July 2022", "isfm_data": [{"isfm_type": "Compost", "scenario": "Above Normal", "rate_tons_ha": 5.5}, {"isfm_type": "Compost", "scenario": "Normal", "rate_tons_ha": 5.0}, {"isfm_type": "Vermicompost", "scenario": "Above Normal", "rate_tons_ha": 3.0}]}

POST/advisory/forage/point

Get forage suitability recommendations for a specific point location.

Parameters:
  • lat (required): Latitude (decimal degrees)
  • lng (required): Longitude (decimal degrees)
  • country_code (optional): Country code - eth, rwa, ken, gha (default: "eth")
  • name (optional): Location name (default: "Point")
Example Request (JSON Body):
POST /advisory/forage/point
{"lat": 9.5, "lng": 40.5, "country_code": "eth"}
Example Request (Query Parameters):
POST /advisory/forage/point?lat=9.5&lng=40.5&country_code=eth
Example Response:
{"location": {"name": "Point", "lat": 9.5, "lng": 40.5, "type": "point"}, "forage_data": [{"forage_variety": "Avena sativa", "suitability_score": 85.5}, {"forage_variety": "Chloris gayana", "suitability_score": 78.2}, {"forage_variety": "Pennisetum purpureum", "suitability_score": 72.0}]}

Available Crops by Country

  • Ethiopia (eth): wheat
  • Rwanda (rwa): potato
  • Kenya (ken): forage only
  • Ghana (gha): forage only

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

Currently no rate limits are enforced. Please use the API responsibly.

Support

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