API Reference

Crop Disease Image Analysis API

Send one photo of a crop and get back a structured JSON diagnosis: the crop, its health status, the likely disease, and what to do about it. Try it below with your own image. You don't need a key for that.

Try it live Get API Access
01 · Overview

One endpoint, one photo, one answer

The Image Analysis endpoint takes a single photo of a plant and returns a JSON object. The object says whether the image is usable, which crop it shows, whether the plant is healthy, and, if it isn't, the most likely disease with symptoms, preventive measures and treatment guidance.

POST https://healthygreens.co.in/api/v1/image-analysis

Single photo

Send one JPEG or PNG taken on a phone camera. No special hardware needed.

14 languages

Disease names, symptoms and treatments come back in your farmer's language.

Image feedback

If a photo is too blurry or too far away, the response says so, so users can retake it.

02 · Authentication

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Requests without a valid key get a 401 Unauthorized response.

Authorization: Bearer YOUR_API_KEY

Keep your key secret. Call the API from your own server, not from a mobile app or browser, so the key never ships to end users. Don't have a key yet? Request API access.

03 · Request

Request

Send the image as multipart/form-data.

Headers

HeaderDescription
AuthorizationRequired Bearer YOUR_API_KEY
Accept-LanguageOptional Language for the disease information, as a code such as en or hi. See supported languages. Unsupported or missing values fall back to en.

Body (multipart/form-data)

FieldTypeDescription
imageRequired file The plant photo. JPEG, PNG, WEBP or BMP, up to 10 MB.
application_used_image_galleryOptional boolean true if the user picked the image from their gallery, false if they took it with the camera.
application_idOptional string Your own identifier for the app or integration sending the request, e.g. my-farm-app-01. Up to 128 characters: letters, digits, . _ - :.
latitudeOptional number Where the photo was taken, in decimal degrees from -90 to 90, e.g. 12.9716. Send together with longitude.
longitudeOptional number Where the photo was taken, in decimal degrees from -180 to 180, e.g. 77.5946. Send together with latitude.

Tips for the best results

  • Photograph one affected leaf or plant part, filling most of the frame.
  • Hold the camera steady and tap to focus. Blurry photos are rejected.
  • Get close. Photos taken from too far away are rejected.
  • Use natural daylight and avoid harsh shadows or flash glare.
04 · Try it live

Upload a photo, see the JSON

This sandbox runs the same analysis as the API and shows the JSON response, so you can see the structure your integration will get. It's limited to a few requests per minute.

Sandbox preview. You'll see the crop, health status, diagnosis and image feedback. Detailed content (symptoms, triggers, preventive measures, treatments and reference images) shows as "Available with an API key". Request API access for complete responses.

No file selected

Try one of our sample photos

The sandbox responds in English. With an API key you can use any of the 14 supported languages.

Response

Waiting for image
// Choose a photo and press "Analyze image".
// The JSON response will appear here.
05 · Response

Response

A successfully processed image always returns 200 OK with the object below. If the photo can't be diagnosed (for example it's blurry or isn't a plant), you still get 200 OK, but crop_health is "unknown" and errors explains why. See Errors.

Fields

FieldTypeDescription
crop_healthstringhealthy, unhealthy or unknown.
cropsstring[]The detected crop, e.g. ["tomato"]. Empty if the crop couldn't be identified.
predicted_diagnosesobject[]The diagnosis. For a healthy plant this is [{"scientific_name": "Healthy"}]. For an unhealthy plant it holds the fields below.
common_namestringDisease name in the requested language.
scientific_namestringScientific or reference name of the disease.
pathogen_classstringThe type of cause, one of fungi, bacteria, virus, insect, mite, deficiency, additional or others.
eppo_codestringStandard EPPO code for the pest or disease, if one exists.
hostsstring[]The crop the diagnosis applies to.
triggerstringWhat causes the problem and the conditions that favour it.
symptomsstringA full description of the symptoms.
symptoms_shortstring[]Short symptom bullet points, for list views.
preventive_measuresstring[]Steps to stop the problem from spreading or coming back.
treatment_chemicalstringChemical control recommendations.
image_referencesstring[]URLs of reference photos showing the disease.
diagnosis_likelihoodstringHow confident the model is in this diagnosis: very_likely (90% or more), likely (75–90%) or possible (55–75%). Below 55% no diagnosis is returned.
treatment_organic
green_diagnosis_id
stringReserved for upcoming features. Don't rely on these values yet.
image_feedbackobjectQuality check of the photo.
focusstring | nullgood, mediocre or bad. null if not checked.
distancestring | nullgood, mediocre, bad or very_bad. null if not checked.
errorsobject[]Empty on success. Otherwise each item has a type and a human-readable message.
green_trace_idstringUnique ID of this request. Include it when you contact support.

Example responses

{
  "crop_health": "unhealthy",
  "crops": ["pepper"],
  "predicted_diagnoses": [
    {
      "common_name": "Chilli Leaf Curl Virus",
      "scientific_name": "CLCV",
      "diagnosis_likelihood": "likely",
      "hosts": ["pepper"],
      "pathogen_class": "virus",
      "eppo_code": "CHILCU",
      "trigger": "Symptoms are caused by begomovirus, which is primarily transmitted through whiteflies...",
      "symptoms": "Symptoms of Chilli Leaf Curl Virus are characterized by upward curling of leaf margins...",
      "symptoms_short": [
        "Upward curling of leaf margins.",
        "Yellowing of veins.",
        "Reduction of leaf size."
      ],
      "preventive_measures": [
        "Use the available plant-resistant species and extract seeds only from virus-free plants.",
        "Ensure a weed-free field and surroundings."
      ],
      "treatment_chemical": "Always consider an integrated approach with preventive measures...",
      "treatment_organic": "need to fix",
      "green_diagnosis_id": "need to fix",
      "image_references": [
        "https://storage.googleapis.com/hg-reference-images/reference/1a07d37f4e4ad24cbfdefa4836882f2c8812613e.jpg",
        "https://storage.googleapis.com/hg-reference-images/reference/b46e31c3e4e5c0104600d7080939fe1331592036.jpg"
      ]
    }
  ],
  "image_feedback": { "focus": "good", "distance": "good" },
  "errors": [],
  "green_trace_id": "8c1f4b3e-6a2d-4f7e-9b1a-2d5e7c9f0a13"
}
{
  "crop_health": "healthy",
  "crops": ["wheat"],
  "predicted_diagnoses": [
    { "scientific_name": "Healthy" }
  ],
  "image_feedback": { "focus": "good", "distance": "good" },
  "errors": [],
  "green_trace_id": "3f9a0c7d-51be-4c02-8e6f-7a4d2b1c9e55"
}
{
  "crop_health": "unknown",
  "crops": [],
  "predicted_diagnoses": [],
  "image_feedback": { "focus": "bad", "distance": "good" },
  "errors": [
    {
      "message": "Potential issues with the image were detected. Check the image_feedback object for more information.",
      "type": "image_blurry"
    }
  ],
  "green_trace_id": "b27e6d14-0f3a-4a8c-9d51-6c3e8f2a7b90"
}
06 · Errors

Errors

Image analysis errors (HTTP 200)

The request worked, but the photo couldn't be diagnosed. crop_health is "unknown" and errors[0].type is one of:

TypeMeaningWhat to show your user
non_plantNo plant was found in the image.Ask them to photograph the affected plant.
distance_too_farThe plant is too far away to see any symptoms.Ask them to move closer to the leaf.
image_blurryThe photo is out of focus.Ask them to hold steady, tap to focus and retake.
ornamental_plantThe plant is ornamental, not a crop.Say that only crops are supported.
crop_not_supportedA crop was detected, but it isn't supported yet.Show the supported crops.
unknown_diseaseThe crop was recognised, but the symptoms don't match a known problem.Suggest a clearer photo of the affected area, or expert advice.

HTTP errors

These come back with the same errors array, so you can handle every error the same way.

StatusTypeCause
400missing_image, invalid_imageNo image field was sent, the file is empty, or it isn't a readable image.
400invalid_parameterAn optional field has an invalid value: application_id has characters that aren't allowed or is too long, latitude/longitude isn't a number in range, or only one of the two was sent.
401unauthorizedThe API key is missing or invalid.
413payload_too_largeThe image is larger than 10 MB.
415unsupported_media_typeThe file isn't JPEG, PNG, WEBP or BMP.
429rate_limitedToo many requests. Wait and retry (sandbox only).
500internal_errorSomething went wrong on our side. Retry, and quote the green_trace_id if it keeps happening.
07 · Code samples

Code samples

Replace YOUR_API_KEY with your key and leaf.jpg with the path to your image.

curl -X POST "https://healthygreens.co.in/api/v1/image-analysis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Language: en" \
  -F "image=@leaf.jpg" \
  -F "application_used_image_gallery=false" \
  -F "application_id=my-farm-app-01" \
  -F "latitude=12.9716" \
  -F "longitude=77.5946"
import requests

url = "https://healthygreens.co.in/api/v1/image-analysis"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept-Language": "en",
}

with open("leaf.jpg", "rb") as f:
    response = requests.post(
        url,
        headers=headers,
        files={"image": ("leaf.jpg", f, "image/jpeg")},
        data={
            "application_used_image_gallery": "false",
            "application_id": "my-farm-app-01",   # optional
            "latitude": "12.9716",                 # optional, send with longitude
            "longitude": "77.5946",
        },
        timeout=30,
    )

result = response.json()
if result.get("errors"):
    print("Could not diagnose:", result["errors"][0]["type"])
else:
    print(result["crop_health"], result["crops"], result["predicted_diagnoses"][0]["scientific_name"])
// Node.js 18+ (run on your server, never expose the key in a browser)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("image", new Blob([await readFile("leaf.jpg")], { type: "image/jpeg" }), "leaf.jpg");
form.append("application_used_image_gallery", "false");
form.append("application_id", "my-farm-app-01");  // optional
form.append("latitude", "12.9716");               // optional, send with longitude
form.append("longitude", "77.5946");

const response = await fetch("https://healthygreens.co.in/api/v1/image-analysis", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept-Language": "en",
  },
  body: form,
});

const result = await response.json();
console.log(result.crop_health, result.crops, result.predicted_diagnoses);
08 · Languages

Supported languages

Pass one of these codes in the Accept-Language header. Disease names, symptoms, preventive measures and treatments are returned in that language.

CodeLanguageCodeLanguage
enEnglish hiHindi
bnBengali guGujarati
knKannada mlMalayalam
mrMarathi orOdia
paPunjabi taTamil
teTelugu urUrdu
ptPortuguese viVietnamese
09 · Coverage

Supported crops

The crops field returns one of these values. We add new crops regularly. Tell us which ones you need.

AppleBananaBeanBitter GourdCabbageCanolaCauliflowerChickpeaCitrusCottonCucumberEggplantGarlicGingerGramGuavaLentilMaizeMangoMelonMilletOkraOnionPapayaPeaPeanutPepperPigeonpeaPomegranatePotatoPumpkinRiceRoseSorghumSoybeanSugarcaneTobaccoTomatoTurmericWheat

Ready to plug diagnosis into your app?

Get an API key and start sending images in minutes.

Get API Access