11 KiB
Data Export API — Proposal Summary
Date: April 7, 2026
Prepared by: AgMission Team
For: Customer Technical & Integration Team
1. Overview
Based on your requirements, we have analysed the current AgMission platform and designed an export API that will allow your team to pull mission data directly into your data infrastructure — data warehouse, Power BI, and ArcGIS — once per day or on demand.
The data available through this API is the same data currently displayed in the AgMission web application's Data Playback and Report screens.
2. What We Will Deliver
2.1 API Key Authentication
All API access will be secured using an API Key as requested. Keys will be managed from within the AgMission platform:
- Your applicator account can create and revoke keys independently (self-service)
- AgMission platform administrators can also manage keys on your behalf
- Each key is shown only once at creation and is stored securely
- All requests must include the key in the request header (
X-API-Key)
2.2 Job List Screen — Enhanced Filtering
The existing Job List screen in the AgMission web application will have its filter controls improved so users can quickly narrow the mission list before opening or exporting a specific job.
Filter controls that will be available:
| Filter | Description |
|---|---|
| Client | Dropdown selection |
| Id N° | Search by mission ID |
| Order Number | Full or partial match |
| Mission Name | Partial match |
| Start Date | From date (inclusive) |
| End Date | To date (inclusive) |
| Status | Mission status (e.g. Sprayed, Completed, etc.) |
2.3 Mission Session Summary
For each mission, one record per application session (uploaded data file). This covers the Coverage with application information requirement.
Each session record includes:
Session identification & timing
| Field | Description |
|---|---|
| Session ID | Unique session identifier |
| File Name | Original data file name |
| Start / End Date & Time | UTC |
| Total Flight Time | seconds |
| Total Spray Time | seconds |
| Total Turn Time | seconds |
Application results
| Field | Description |
|---|---|
| Total Sprayed Area | Hectares actually covered |
| Mapped Area | Planned area size from job definition (ha) |
| Over-Spray % | (Sprayed − Mapped) / Mapped × 100 |
| Material Sprayed | Total volume or mass applied (litres or kg, metric) |
| Material Type | Liquid (wet) or dry granular |
| Target Application Rate | Planned rate from mission file |
| Application Rate Unit | e.g. L/ha, Kg/ha |
| Flow Controller | Equipment type used |
| Average Spray Speed | Average ground speed during active spraying (m/s) |
| Spray Zone Name | Named area or zone (Ag-NAV missions only) |
| Spray Zone Area | Area size of the named zone (Ag-NAV only) |
| Auto Spray On / Off Lag | Spray system timing offsets (seconds) |
| Pulses per Litre | Flow calibration value (liquid Ag-NAV only) |
Confirmed / adjusted values
If the applicator has opened the Report Settings screen and confirmed the values, those confirmed values are returned. If they have not done so, the API automatically falls back to values calculated directly from the uploaded application data files — so this group is always populated.
A reportConfirmed flag indicates which case applies.
| Field | If report confirmed | If not confirmed (fallback) |
|---|---|---|
| Report Confirmed | true |
false |
| Area Size | Applicator-confirmed value (ha) | Calculated from planned spray area polygons |
| Spray Coverage | Applicator-confirmed value (ha) | Sum of sprayed area across all sessions from data files |
| Application Rate | Applicator-confirmed value | Target application rate from the data file |
| Estimated Spray Volume | Coverage × Application Rate | Same formula using fallback values |
| Actual Spray Volume | Manually entered by applicator (if provided) | Not available |
| Effective Volume | Actual volume if entered, otherwise Estimated | Estimated Spray Volume (fallback) |
Weather information (returned when manually entered by applicator in the absence of sensor data)
| Field | Unit |
|---|---|
| Wind Speed | knots |
| Wind Direction | Compass bearing (e.g. NE, SW) |
| Temperature | °C |
| Humidity | % |
Pilot traceability
| Field | Description |
|---|---|
| Pilot Name (assigned) | Pilot assigned to the mission |
| Pilot Name (from file) | Pilot name as recorded in the data file itself (may differ if pilot changed in the field) |
| Pilot ID | Stable unique identifier |
| Aircraft Tail Number | Registration number |
| Aircraft Name | |
| Assignment Date | Date the applicator officially assigned this pilot |
2.4 Raw GPS Trace Records — Applied Flow
The per-point GPS and application data that feeds the playback screen, returned as paginated records (up to 2,000 per request). This covers the Applied Flow requirement.
Each record corresponds to one GPS reading logged by the aircraft during the mission.
GPS Data
| Field | Unit | Description |
|---|---|---|
| Timestamp UTC | ISO 8601 | Local GPS time converted to UTC |
| GPS Time | seconds | Raw GPS epoch seconds |
| Latitude | decimal degrees | WGS84 |
| Longitude | decimal degrees | WGS84 |
| UTM X / Y | meters | UTM coordinates |
| Altitude | meters | Above sea level |
| Ground Speed | m/s | |
| Heading | degrees | Direction of travel |
| Cross-Track Error | meters | Deviation from planned line |
| Locked Line | integer | Spray line number (Ag-NAV only) |
| HDOP | — | GPS horizontal accuracy |
| Satellites in View | count | |
| Correction ID | — | GPS differential correction source |
| WAAS ID | — | When applicable |
| Spray Status | 0 / 1 | 0 = spray off, 1 = spray on |
Time interval filtering: When requesting raw trace records or exporting, a
intervalparameter can be specified (e.g. 0.2 s, 0.4 s, 1 s, 5 s, 10 s) to return only one record per interval rather than every logged GPS point. This significantly reduces payload size for overview queries and large-batch exports.
Application Info
| Field | Unit | Description |
|---|---|---|
| Flow Rate Applied | L/min | Actual flow rate measured |
| Flow Rate Required | L/min | Target flow rate |
| Application Rate Required | L/ha or Kg/ha | Target rate per point |
| Application Rate Applied | L/ha | Calculated from measured flow, speed, and swath |
| Swath Width | meters | |
| Boom Pressure | psi | Liquid Ag-NAV only |
| Auto Spray On Lag | seconds | Spray-on activation delay (session constant, repeated per record) |
| Auto Spray Off Lag | seconds | Spray-off deactivation delay (session constant, repeated per record) |
| Pulses per Litre | count | Flow meter calibration value — liquid Ag-NAV only (session constant) |
| RPM values | array | Up to 10 channels; semantics depend on material type (liquid vs. dry) |
Meteorological (MET)
| Field | Unit | Description |
|---|---|---|
| Wind Speed | m/s | Measured in-flight |
| Wind Direction | degrees | |
| Temperature | °C | |
| Humidity | % |
Note: All values are in metric units. Date/times are UTC. Coordinates are in WGS84 (EPSG:4326), which is numerically equivalent to SIRGAS 2000 used in Brazil.
2.5 Bulk Export (CSV / GeoJSON Download)
For the daily 17:00 Brasília batch pull and ArcGIS imports, a file-based export endpoint is available:
- Request export — call the export endpoint for a mission; the system generates the file asynchronously
- Poll for status — check whether the file is ready (typically seconds to a few minutes for large missions)
- Download — retrieve the file via the returned download link
Available formats: CSV (all raw trace data, one row per GPS record) and GeoJSON.
CSV files include job and session header columns repeated on every row for easy import directly into Power BI or a data warehouse without needing a separate join step.
2.6 Spray-Area Boundary Polygons (Pending confirmation — see Section 4)
An optional endpoint to retrieve the planned field boundary polygons as GeoJSON, for direct import as ArcGIS layers.
3. Data Units & Standards
| Aspect | Standard used |
|---|---|
| All measurements | Metric (ha, m/s, L/min, L/ha, Kg/ha, °C, meters) |
| Dates & times | ISO 8601 UTC strings |
| Coordinates | WGS84 decimal degrees (EPSG:4326 / numerically equivalent to SIRGAS 2000) |
| Volumes | Litres for liquid, Kg for dry granular |
| Speeds | m/s in raw records; km/h can be derived by consumer (× 3.6) |
4. Pending Confirmation — One Open Item
Spray-area boundary polygons for ArcGIS
Do you need the planned field boundary polygons (the area outlines drawn in the mission) exported as GeoJSON geometry, in addition to the numeric coverage statistics (hectares)?
- If yes — we will provide a dedicated endpoint returning the boundaries as GeoJSON features, suitable for direct layer import into ArcGIS.
- If no — the numeric coverage and session summary fields are sufficient and no additional endpoint is needed.
This is the only remaining item before implementation can begin.
5. Estimated Delivery Timeline
| Team size | Estimated duration | Target delivery |
|---|---|---|
| 1 developer | ~5 weeks | ~mid-May 2026 |
| 2 developers | ~3 weeks | ~end of April 2026 |
Includes development, testing, sandbox environment setup, and a review cycle.
A sandbox environment with sample missions will be made available for your team to validate the API responses before production go-live.
6. Summary of Requirements Confirmed
| Requirement | Status |
|---|---|
| API Key authentication | ✅ Confirmed — self-service key management for both the applicator account and AgMission admin |
| Applied Flow data (per GPS point) | ✅ Confirmed — all fields from GPS Data and Applic Info tabs included |
| Coverage with application info | ✅ Confirmed — session summaries include both raw aggregates and applicator-confirmed values |
| Pilot Traceability | ✅ Confirmed — pilot name, ID, tail number, assignment date, and in-file pilot name all included |
| Mission filtering (Client, Order No., Name, Dates) | ✅ Confirmed — UI enhancement to the existing Job List screen |
| Pull delivery (not push) | ✅ Confirmed — pull endpoints + async file download |
| Raw data (not calculated metrics) | ✅ Confirmed — all raw sensor values returned; calculated appRateApplied also included as it appears in the UI |
| Power BI integration | ✅ Supported — cursor-paginated JSON for incremental refresh |
| ArcGIS integration | ✅ Supported — GeoJSON export + boundary polygons (pending confirmation) |
| Data warehouse / bulk load | ✅ Supported — CSV export endpoint |
| Consumption once daily at 17:00 Brasília | ✅ Supported — async export endpoint designed for this pattern |
| Sandbox environment | ✅ Will be provided before production go-live |
| Spray-area boundary polygons | ⏳ Pending your confirmation (Section 4) |