252 lines
11 KiB
Markdown
252 lines
11 KiB
Markdown
# 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 `interval` parameter 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:
|
||
|
||
1. **Request export** — call the export endpoint for a mission; the system generates the file asynchronously
|
||
2. **Poll for status** — check whether the file is ready (typically seconds to a few minutes for large missions)
|
||
3. **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
|
||
|
||
| Phase | Estimated duration | Target delivery |
|
||
|---|---|---|
|
||
| 1 | ~4 weeks | ~mid-May 2026 |
|
||
| 2 | ~2 weeks | ~end of May 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)** |
|