One agriculture API for satellite imagery, crop-health indices, field weather, PDF reports and AI farm advisory. Register a field boundary once, and every satellite visit after that arrives as JSON over HTTPS.
Get rendered PNGs and georeferenced GeoTIFFs of any registered field for each satellite visit. Choose from 20 image types: true color, NDVI, EVI, SAVI, NDRE, NDWI, NDMI, evapotranspiration, soil organic carbon, elevation, land use, and radar (RVI, RSM) for cloudy weeks. The same satellite data is also available as numbers: field-average index values, multi-date time series and area-by-index-range breakdowns. Archive coverage starts in 2017.
Get current conditions, 7-day daily forecasts and past daily weather for every field, or a forecast for any latitude and longitude without registering a field. Forecasts are delivered in the OpenWeather One Call 3.0 format or a Dark Sky-compatible format, so existing weather parsers work unchanged. A ready-made weather chart is available for farmer reports.
Generate a PDF field report for any visit date, in up to 9 languages, with your own logo on request. You can also request a structured JEEVN AI advisory with fertilizer, irrigation, pest, weed and soil recommendations, or an interactive advisory report you can share by link.
API access comes with every Farmonaut subscription. Plans run from Basic ($30/month for 30 ha and 21 land parcels) to Elite ($950/month for 1,500 ha and 1,050 land parcels), and the price per hectare falls from $1.00 to about $0.63 as plans grow. Test mode lets you build and check your integration without using your plan.
Go from no key to a field’s NDVI value in five steps. Step 2 runs in test mode, so it costs nothing.
Before you begin You need a Farmonaut account with an active subscription; API keys can be created once a plan is active. See Plans & billing. Use cURL, or any language with an HTTP client.
1. Get an API key
Create a key at sat.farmonaut.com/api. Keep it out of source code by putting it in an environment variable. Every example in these docs reads it from there.
export FARMONAUT_API_KEY="your_api_key"
2. Make a test call
Check that the key works by asking for your unit balance. "isTesting": true returns sample data and isn’t billed.
If you get {"error": "invalid api key"}, check that the header is Authorization: Bearer followed by your key.
3. Create a field
Send the boundary as [longitude, latitude] pairs, plus a crop code. This call creates a real field that counts toward your plan. Set isTesting to true if you only want to try it.
Save the FieldID from the response. Every other endpoint needs it.
4. Wait for the first satellite data
First results are usually ready within a few minutes. Poll the field’s sensed days until a date appears, or register a webhook so you don’t have to poll.
5. Read NDVI for that date
Use a date from step 4 to get the field-average NDVI and a rendered image.
Create and manage keys at sat.farmonaut.com/api. Keys can be created once your account has an active subscription. The same page also creates test keys, which let you build an integration without touching real data or your plan.
Test mode
Every endpoint accepts an optional isTesting boolean in the body:
true: returns a sample response. It isn’t billed and doesn’t count toward your plan.
false or omitted: runs the real request.
Use test mode in CI and while building your parser. Turn it off for production calls.
Keep keys safe
Call the API from your server only. Never ship a key inside a mobile app, a browser page or a public repository.
Store keys in environment variables or a secrets manager.
Regenerate a key at once if it may have leaked. You can create a new one at any time.
Iframe keys are different
The embeddable iframes use a separate key, passed in the URL. It is issued by Farmonaut support, not created on the API page.
Authentication errors
Status
Body
What to do
401
{"error": "invalid api key"}
The header is missing, misspelled or has the wrong key. Check the Bearer prefix.
403
{"error": "forbidden"}
The key may not perform this request. Contact support if you think it should.
Get started
Requests & responses
Conventions that apply to every endpoint. Read this once and the reference pages will make more sense.
Requests
Every endpoint is POST https://us-central1-farmbase-b2f7e.cloudfunctions.net/<endpointName>. The endpoint name is case-sensitive.
Every request sends two headers: Authorization: Bearer <API key> and Content-Type: application/json. See Authentication.
Parameters go in a JSON body. There are no query parameters.
IDs (FieldID, PolygonID) are strings of digits. Send them as strings.
Data formats
Value
Format
Example
Visit dates (SensedDay, history dates)
YYYYMMDD string
"20240825"
SowingDate in Create a field and Update sowing date
Unix timestamp in seconds, not in the future
"1734240752"
SowingDate in Generate AI advisory
YYYYMMDD string
"20250101"
Boundary input (Points)
Array of [longitude, latitude], at least 3 points
[[77.7635, 12.9794], …]
Boundary output (Coordinates)
Object of points a, P_1… (fields) or P_0, P_1… (polygons), each {Latitude, Longitude}
Successful responses come in three shapes. Each reference page says which one an endpoint returns.
Object: most read endpoints, for example {"url": "https://…"}.
String: most write endpoints return a JSON string confirmation, for example "Field Deleted Successfully!".
Array: for example List expired fields.
Check the body, not just the status A few endpoints report problems with HTTP 200, either as {"error": …} or as a plain string. Examples are an unknown field in Get current weather, or a paused field in Generate AI advisory. Treat any body with an error key as a failure. These cases are listed on each reference page.
Key names are not fully consistent, so match them exactly. For example, Get GeoTIFF returns URL while the other image endpoints return url.
Get started
Errors
Errors use standard HTTP status codes and a JSON body with a single error message.
{"error": "invalid api key"}
Common errors
Any endpoint can return these. Reference pages list them as chips and only spell out errors specific to that endpoint.
Status
Message
Cause
Fix
Retry?
400
undefined request. Please fix the JSON request.
The body is empty or not valid JSON.
Send a JSON object and set Content-Type: application/json.
No
400
invalid request
A required parameter is missing or has the wrong type.
Compare the body with the endpoint’s parameter table.
Check the field belongs to this account, or contact support.
No
403
units_exhausted (sometimes units exhausted)
Legacy API-unit accounts only: no units left.
Check Get API usage, then top up or move to a subscription plan.
After top-up
500
internal error
Something failed on Farmonaut’s side.
Retry with exponential backoff. If it continues, contact support with the endpoint, FieldID and time.
Yes
Handling errors in code
Because some failures arrive with HTTP 200, check both the status and the body:
import os, time, requests
BASE = "https://us-central1-farmbase-b2f7e.cloudfunctions.net"
HEADERS = {"Authorization": f"Bearer {os.environ['FARMONAUT_API_KEY']}"}
def call(endpoint, body, retries=3):
for attempt in range(retries):
r = requests.post(f"{BASE}/{endpoint}", json=body, headers=HEADERS, timeout=60)
if r.status_code >= 500 and attempt < retries - 1:
time.sleep(2 ** attempt) # back off and retry server errors only
continue
data = r.json()
if r.status_code >= 400 or (isinstance(data, dict) and "error" in data):
raise RuntimeError(f"{endpoint}: {r.status_code} {data}")
return data
Retry only 5xx errors, with backoff. Retrying a 4xx without changing the request returns the same error.
Log the endpoint, body (without the key) and response. That is what support needs to help you.
Concepts
Fields & polygons
A field is a boundary you ask Farmonaut to monitor. Everything else in the API hangs off its FieldID.
Boundaries
Send at least 3 points as [longitude, latitude], in clockwise or counter-clockwise order. Longitude comes first.
The area must be between 0.01 ha (100 m²) and 1,000 ha. Split larger estates into several fields.
The API does not detect duplicates. The same boundary sent twice becomes two fields, billed twice.
Crop and sowing date
The crop code and sowing date tell Farmonaut what is growing and at what stage. They feed yield estimates and advisory. Set them when you create the field. Update them each season with Update crop and Update sowing date, and new estimates start from the next satellite visit.
Paused and expired fields can’t request historical data or generate advisory. The field object exposes the state through Paused, Expired and Expiring.
Polygons
A polygon is a sub-area inside a field, for example one farmer’s plot in a cluster. Polygons have their own PolygonID, and several endpoints accept an optional PolygonID to scope results to it. Polygon endpoints are enabled only for selected enterprise accounts. Contact support to request access.
Concepts
Satellite visits
Data exists only for dates when a satellite passed over the field. Those dates are the field’s sensed days.
Sensed days
Optical satellites revisit a location every few days. Each visit that produces usable data is added to SensedDays as a YYYYMMDD key. Every date-based endpoint (images, index values, reports) needs one of these dates. Read them from List sensed days. Schedule polling around the revisit cycle, because calling daily mostly returns nothing new.
Clouds and radar
Clouds block optical sensors. A cloudy visit is recorded in FailedDays, or flagged with isCloudy. Radar (SAR) sees through cloud. Radar dates are listed by List radar days, and the radar indices rvi (vegetation) and rsm (soil moisture) are the fallback during monsoon or persistent cloud.
Zone alerts
For each sensed day, the field is split into a 3×3 grid. cropRedZones and irrigationRedZones list the zones that need attention.
1NW2N3NE4W5Center6E7SW8S9SE
Historical data
A field gets data from its creation date onwards. To go further back (to 2017), request it with Request historical data for one date, or in bulk for a range. Historical requests count toward your plan. One month typically covers 5–6 satellite visits. See Plans & billing.
Concepts
Image types & indices
An image type is a way of looking at a field. Each one is either a rendered image or a numeric index computed from satellite bands.
Raw indices range from −1 to 1. The API returns them as strings from "0" to "100":
Values from 0 to 1 are multiplied by 100. An NDVI of 0.45 is returned as "45".
Negative values (water, bare soil, cloud shadow) are returned as "0".
Divide by 100 to get the original value back. Field-average values (Get index value) and the Health map both use this scale.
Color maps
Rendered images color each pixel by its index value. Color map 1 suits tall vegetation and shows very low values as red. Color map 2 suits short vegetation and shows them as black. High values are green in both. Choose one with ColorMap in Get field image.
Color map 1Color map 2
Color legend
Use these colors to draw your own legend. Click a color to copy its hex code.
Ready-made legend images
Embed these scale images next to rendered field images in your UI. Each card shows the URL to use.
API access comes with a Farmonaut subscription. Your plan sets how many land parcels (fields) and how many hectares you can monitor.
Subscription plans
Plan
Price
Land parcels
Area
Satellite visits / month
Price per hectare
Basic
$30/month
21
30 ha
180
$1.00
Standard
$65/month
56
80 ha
480
$0.81
Premium
$225/month
210
300 ha
1,800
$0.75
Elite
$950/month
1,050
1,500 ha
9,000
$0.63
Satellite visits are the monitoring updates your plan includes each month. Each satellite pass that produces new data for one of your fields uses one visit, and the allowance is shared across all your fields. Historical data requests use visits too.
The number of land parcels in each plan is 70% of its hectare allowance, so a Basic plan covers up to 21 fields across 30 ha. Larger plans lower the price per hectare from $1.00 to about $0.63. For current offers and annual billing, see the pricing page. For larger areas or custom terms, contact [email protected].
Getting API access
API keys can be created at sat.farmonaut.com/api once your account has an active subscription.
Fields you create through the API count toward your plan’s land parcels and area, exactly like fields drawn in the app.
Requests sent with "isTesting": true return sample data. They aren’t billed and don’t count toward your plan.
Pause fields you don’t need right now, and delete fields you no longer monitor.
Historical data requests also count toward your plan. One month of history typically covers 5–6 satellite visits, so check your account before large backfills.
To monitor more land than your plan allows, upgrade. The new limits apply immediately.
Legacy billing: API units
Older accounts only Before subscriptions, API access was billed in prepaid API units. New accounts use the subscription plans above. This section applies only to accounts still on unit billing.
Check the unit balance with Get API usage: OrderedUnits, UsedUnits and remainingUnits.
When units run out, billable endpoints return 403 units_exhausted.
Each unit-billed field records the hectare units it uses in hUnits. Its monitoring period can be extended with Extend monitoring. Subscription fields (Subscription: true) follow the plan instead.
Unused units roll over to the next month if 1,000 hectares or more are under monthly monitoring. Otherwise they expire at the end of each month.
Guide
Monitor a field end to end
The core loop most integrations need: register fields, learn when new data arrives, store the indices, and act on alerts.
1. Register the field
Validate the drawn boundary first, then create the field and store its FieldID next to your own record.
2. Find out when new data arrives
Register a webhook once per account. Farmonaut then POSTs to it whenever new data is processed for a field. If you can’t expose a public endpoint, poll List sensed days on a schedule that matches the satellite revisit cycle (every few days, not every hour).
3. Pull the indices you care about
For a new date, fetch several indices in one call and store them for your own time series.
4. Act on zone alerts
Each sensed day can include cropRedZones and irrigationRedZones, which are grid zones needing attention. A common pattern is to notify the farmer or agronomist when a zone appears in two visits in a row, or when NDVI drops more than a set threshold from the previous visit.
5. Update the field each season
Keep each field’s settings in line with what is happening on the ground, so yield estimates and advisory stay accurate.
A new crop is sown: send the new crop with Update crop and the new sowing date with Update sowing date. Estimates use them from the next satellite visit.
The monitoring period is ending: the field object’s Expiring flag turns yes shortly before it ends, so check it and renew in time.
Guide
Satellite imagery API guide
Show a field on a map, chart its health over time, or take the data into GIS software.
Display an image in your app
Get a rendered PNG for one image type and date, and put a legend image beside it.
Chart health over time
One call returns every index for every visit since the field was created. Divide values by 100 to get raw index values.
Show how much of the field is healthy
The index breakdown gives the area (m²) in each 0.1-wide index range. Sum the top ranges to report, for example, “62% of the field has NDVI above 0.6”.
Use the data in GIS tools
Download a georeferenced GeoTIFF to open in QGIS, ArcGIS or your own pipeline.
Guide
Agriculture weather API guide
Weather is available for any registered field, and the forecast is also available for any coordinate.
Units Temperatures are in kelvin (subtract 273.15 for °C), wind speed in m/s, pressure in hPa. Forecasts follow the OpenWeather One Call 3.0 format, or a Dark Sky-compatible format with "DataFormat": "dark_sky_format".
Example: hold irrigation when heavy rain is forecast
Fetch the forecast and skip irrigation or spraying if a day’s expected rainfall exceeds a threshold, for example 40 mm.
In the normal format, read daily[i].rain (mm) and daily[i].pop (probability of precipitation).
Guide
Field reports & AI advisory API
Turn satellite data into documents and recommendations you can send to farmers.
PDF field report
Each sensed day can produce a PDF report covering weather, radar, crop health and irrigation indices. Set the report languages once per field, then fetch reports by date.
Generate structured, field-specific recommendations for fertilizer, irrigation, pests and diseases, weeds and soil. Pass the crop and sowing date for growth-stage-aware advice.
For a shareable, interactive version, generate an advisory report URL for one or more fields:
Crop-solution database
Look up treatments and doses for a crop’s known pests and diseases.
Guide
Receive webhooks
Instead of polling, let Farmonaut call you when new data has been processed for one of your fields.
1. Build a receiving endpoint
Expose a public HTTPS URL that accepts POST requests with a JSON body and returns a 2xx status quickly. Do slow work, such as fetching images, in a background job after you respond.
from flask import Flask, request
app = Flask(__name__)
@app.post("/farmonaut-webhook")
def farmonaut_webhook():
event = request.get_json(silent=True) or {}
queue_for_processing(event) # your background job
return "", 200
2. Register it
Registering sends a test request to your URL straight away. If your endpoint doesn’t answer with a success status, registration fails with Failed to trigger webhook.
3. Process events
Log the first test request your endpoint receives to see the exact payload your account gets.
Make processing idempotent. If the same event arrives twice, the result should be the same.
After an event, call List sensed days for the field to find the new date, then fetch the data you need.
Guide
Backfill historical data
Get satellite data for dates before a field was registered, from 2017 onwards, to compare seasons or train models.
Make sure the fields are active. Paused or expired fields are rejected.
Check your plan allowance. Each month of history typically covers 5–6 satellite visits. See Plans & billing.
Submit the request:
The response estimates the processing time in minutes. After that, the new dates appear in List sensed days. For a single date on one field, use Request historical data, which usually finishes within a few hours.
Guide
Embed with iframes
Drop Farmonaut’s field-drawing and field-viewing screens into your own web app without building map UI.
Add-on feature Iframes are available to API customers on request and use a separate iframe key. Contact [email protected] or +1 (669) 666-6882.
Add Field
Lets your user draw a boundary on a map and creates the field in your account. First results are usually ready within 5 minutes.
Yes. API keys can be created once your account has an active subscription, and fields created through the API count toward your plan. See Plans & billing.
Registers the URL that Farmonaut calls with a POST request whenever new data is processed for one of your fields.
Fields
Create a field
POST/submitField
Registers a new field (farm or plot) and starts satellite monitoring for it.
First results are usually ready within a few minutes. After that, data for each new satellite visit is generated automatically and can be read at any time.
The API does not check for duplicates. Submitting the same boundary twice creates (and bills) two fields.
Requires authentication: Authorization: Bearer <key> and Content-Type: application/json.
Requests satellite data for one date before the field was created.
Example: a field created on 15 June 2021 can request data for 5 June 2021. The field must not be paused or expired. Historical requests use satellite visits from your plan quota.
Requires authentication: Authorization: Bearer <key> and Content-Type: application/json.
A satellite visit date in YYYYMMDD format. Must be one of the field’s sensed days.
ColorMapstringoptional
1 for tall vegetation, 2 for short vegetation. Default: 1. Color map 2 is not available for TCI, ETCI, Hybrid, Colorblind and Evapotranspiration. See Color maps.
isTestingbooleanoptional
If true, returns a sample response that isn’t billed and doesn’t count toward your plan. Default: false.
Upload your area of interest and receive satellite-backed insights on mineral potential — fast, non-invasive, and research-backed.
33
Countries
23
Minerals
391,956
Acres Analysed
$1T+
Minerals Found
press Enter ↵
Satellite Mineral Intelligence
Find Valuable Minerals Using Satellite Technology
“
Farmonaut helped us identify locations to drill and find mineralisation which in turn saved our client $100,000-plus and 6 months of the project time. We would recommend their services to our clients at any given time.
NNTS Group (Pty) Ltd Exploration consultancy · South Africa · Gold
Area
131 acres
Delivered
Ranked drill targets
Outcome
Mineralisation found
The work carried out exceeded our expectations.Le travail effectué a dépassé nos attentes.
AAlmosi SARL Licence holder · Niger · Gold
Area
4,621 acres
Verified by
Laboratory assay
Outcome
Mineralisation confirmed
Farmonaut helped us identify and articulate key points of mining asset.
MMalik Licence holder · Nigeria · Gold + lithium
Area
741 acres
Minerals
Gold + lithium
Status
Drilling planned
33Countries
23Minerals
391,956Acres analysed
$1T+Minerals found
Delivered in
+23 more
press Enter ↵
Which of the following describes you the best?
Mining License Owner
Mining Consultant
Investor
Mining Company Employee
Other
Please select an option to continue.
First name is required.
A valid email is required.
Phone number is required.✓ Valid phone number
press Enter ↵
Mention Your Target Minerals *
This field is required.
press Enter ↵
Total Area *
This field is required.
press Enter ↵
Do you have enough funds to start this project? *
Yes
No
In Progress
Please select an option to continue.
When do you expect to have enough funds to begin the project? *
< 3 months
3-6 months
6+ months
Please select an option to continue.
By clicking Submit, you agree to receive texts, WhatsApp messages and calls from Farmonaut about your request (reports, follow-ups, scheduling). Consent is not a condition of purchase. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help. Privacy Policy · Terms.
press Ctrl + Enter ↵
Submitting… please wait
Thank You!
Your details have been saved successfully. We will get back to you shortly.
Farmonaut 
Coromandel International
Hayleys Agriculture
Linx Agritech
Adinet
Save Your Soils
GalaxEye Space
Grandstream Algérie
XOS Realty
Geospatial Lab Africa
Agro La Gándara
HIPSAC
ZOL Zimbabwe
Juligerm
AdBio
MISE Maroc
NWNS
Red August Group
Farm Inc
WeMe Global
Licence holder · Niger · Gold
