Skip to the main content
John Deere Logo

Develop with Deere


Operations Center - Field Operations

Click here for more information on how to get started.

Overview

A Field Operation represents data collected while working in a field - primarily tillage, seeding, application, and harvest layers. The Field Operations APIs allow you to access much of the same information that is available via the Field Analyzer screen in MyJohnDeere Operations Center.


Using the Field Operations APIs, you can access:

  • Metadata about each Field Operation.

  • Totals showing the area worked and the total amount planted, applied, or harvested.

  • Map images, including legends, that show what happened in each part of the field.

  • Point-level data, available via a shapefile export.

fieldOperation overview

Webhooks

New operational data can appear quickly, and Field Operations can contain a large amount of data. If you are planning to make frequent requests to the Field Operations API, please consider our Data Subscription Service. It can alert your application via webhook when new Field Operations are available.

Field Operations vs Map Layers

While you can access map images using either the Field Operations API or the Map Layers API, the two represent different types of data. Field Operations represent data that was processed internally by Field Analyzer, while Map Layers represent data that was contributed into John Deere Operations Center by another tool.

Endpoints Overview

List Field OperationsList all Field Operations for the given organization and field.Get by IDRetrieve metadata describing a specific Field Operation. If you are using webhooks, the webhook notification will contain a link to this endpoint.Export a shapefileIf you need to process point-level data (as opposed to simply displaying a map image), this endpoint allows you to download a shapefile representation of the Field Operation. Visit the overview page for details on the shapefile format.List a Field Operation's Measurement TypesDiscover what measurement types are available for a specific Field Operation.Get details about a Measurement TypeRetrieve details about a specific Measurement Type, including the total aggregated value for this measurement.Extract a Measurement Type's map imageCalling this endpoint will give you a map image for a specific measurement type, along with legends and a geotagged extent.

Shapefiles Overview

A shapefile is an industry-standard format for storing geospatial data. For a deep technical description, see the ESRI whitepaper that describes the file formats. Shapefiles exported from MyJohnDeere are always MultiPoint or MultiPolygon shapes. We recommend using standard GIS libraries to read shapefiles.

We have examples of shapefiles available on github for Harvest, Seeding, and Application operations.

Shapefiles exported from MyJohnDeere will include the following files:

  • .dbf

    Data attributes for each shape, in dBase IV format. Each shape in a shapefile will have one row of attributes in the DBF file. DBF files can also be opened by Microsoft Excel and Microsoft Access. The data columns included in a .dbf file will depend on operation type. See below for a chart of standard data columns.

  • .prj

    Geospatial projection information. Shapefiles exported from MyJohnDeere always use WGS84 (wkid:4326).

  • .shp

    Feature geometry. This contains the actual points or polygons.

  • .shx

    Positional index of feature geometry. Most GIS libraries use this file to speed the process of reading a shapefile.

  • .json

    The included .json file is not part of the official ESRI spec. It contains extra metadata, including the units of measure associated with each column of the DBF.

Standard Data Columns

Note that the units of measure listed here include both metric and imperial. The unit system is determined by a Accept-UOM-System header on the shapefile export request, if available, or by the user's organization preferences. The .json file bundled with the shapefile contains the exact units of measure used.

Harvest Data Columns

Name

Description

Column Type

Units of Measure

Example

TimeUTC timestampCharacter(23)UTC"4/9/2012 1:45:35 PM"
HeadingDirection of travelNumber(18,8)deg (0 being magnetic north)179.999
DistanceDistance travelled since the last recorded pointNumber(18,8)meters or feet3.1
SwathwidthWidth of the implement sectionNumber(18,8)meters or feet3.5
VRYieldVolVolumetric yield (Note this column is only generated for volumetric crops)Number(18,8)liters per hectare, or bushels per acre10403.33
VrYieldMasYield by mass (Note this column is only generated for mass-based crops)Number(18,8)kg per hectare, or pounds per acre32000
VrYieldBalYield in bales (Note this column is only generated for cotton)Number(18,8)bales per hectare, or bales per acre10.6
SectionIDThe implement section id for this sampleNumber(5,0)---135
CropThe crop idNumber(5,0)---173
MoistureThe crop moisture readingNumber(18,8)percent10.25
VarietyWhich seed variety or hybrid was planted hereCharacter(23)---MYCOGEN 2A787
ElevationElevation from the GPS receiver, adjusted for the receiver's vertical offsetDoublemeters or feet793.73737646
IsoTimeISO-formatted UTC timestampCharacter(23)---2014-10-03T16:13:27.000Z
MachineIndex identifying which machine usage is currently active. The .json file contains machine and operator ID's for each index value. Note that a different machine ID may indicate either a different machine or a change in machine configuration.Number(5,0)---1
PRODUCTHASHUnique IdentifierCharacter(35)---1418b89d7f859a2344d95dd035f28ced

Optional Harvest Data Columns

Some of the below columns may be present in addition to the other operation data columns described in the “Standard Data Columns” section

Name

Description

Column Type

Units of Measure

Example

FuelFuel ConsumedNumber(18,8)liters, gallons0.00341322
VEHICLSPEEDVehicle SpeedNumber(18,8)kilometers per hour, miles per hour3.25
AIRTEMPAir TemperatureNumber(18,8)Fahrenheit, Celsius24
WINDDRCTNWind DirectionCharacter(2)---SE
WINDSPEEDWind SpeedNumber(18,8)m/hr1.6
SKYCNDTNSky ConditionsCharacter(23)---Sunny
HUMIDITYHumidityNumber(18,8)---23
SOILMOISTSoil MoistureCharacter(23)---Dry
SOILTEMPSoil TemperaturNumber(18,8)Fahrenheit, Celsius24
DELTATTemperature Variation During OperationNumber(18,8)Fahrenheit, Celsius6.5

Additional Harvest Data Columns

Based on the type of harvest operation, some of these may be present in addition to the harvest data columns described above.

Name

Description

Column Type

Units of Measure

Example

GrossYldAGross Yield per AreaNumber(18,8)kg/ha or lb/ac7048.77
GrossYldGross YieldNumber(18,8)kg or lb80.234
NetYldNet YieldNumber(18,8)kg or lb80.234
TrashOut the back mass measurementNumber(18,8)percent9.56
ADFPrcntAcid Detergent Fiber PercentageNumber(18,8)percent9.56
NDFPrcntNeutral Detergent Fiber PercentageNumber(18,8)percent9.56
StrchPrcntStarch PercentageNumber(18,8)percent9.56
CrdPrPrcntCrude Protein PercentageNumber(18,8)percent9.56
SugarPrcntSugar PercentageNumber(18,8)percent9.56
GINTURNOUTGin TurnoutNumber(18,8)percent10.25
CRUDEASHConstituent Crude AshNumber(18,8)percent9.3
CRUDEFIBERConstituent Crude FiberNumber(18,8)percent29.3
CRUDEFATConstituent Crude FatNumber(18,8)percent2.2
OILConstituent OilNumber(18,8)percent3.1
METABENERGYConstituent Metabolizable EnergyNumber(18,8)mcal/lb, mj/kg0.9
LENGTHOFCUTLength of CutNumber(18,8)inches0.01000000
IDHIGHRATEInoculant Dosing High RateNumber(18,8)floz/ton37.3
IDHIGHTOTALInoculant Dosing High TotalNumber(18,8)floz/ton37.3
IDLOWRATEInoculant Dosing Low RateNumber(18,8)floz/ton37.3
IDLOWTOTALInoculant Dosing Low TotalNumber(18,8)floz/ton37.3

Seeding Data Columns

Name

Description

Column Type

Units of Measure

Example

TimeUTC timestampCharacter(23)UTC"4/9/2012 1:45:35 PM"
HeadingDirection of travelNumber(18,8)deg (0 being magnetic north)179.999
DistanceDistance travelled since the last recorded pointNumber(18,8)meters or feet3.1
SwathwidthWidth of the implement sectionNumber(18,8)meters or feet3.5
CropThe crop idNumber(5,0)---173
SectionIDThe implement section id for this sampleNumber(5,0)---135
AppliedRateThe measured seeding rateNumber(18,8)kg per hectare, lb per acre, seeds per hectare, or seeds per acre32005.6
ControlRateThe prescribed seeding rate that was sent to the planterNumber(18,8)kg per hectare, lb per acre, seeds per hectare, or seeds per acre32000
TargetRateThe prescribed seeding rate in the absence of a control rateNumber(18,8)kg per hectare, lb per acre, seeds per hectare, or seeds per acre32000
ElevationElevation from the GPS receiver, adjusted for the receiver's vertical offsetDoublemeters or feet793.73737646
IsoTimeISO-formatted UTC timestampCharacter(23)---2014-10-03T16:13:27.000Z
MachineIndex identifying which machine usage is currently active. The .json file contains machine and operator ID's for each index value. Note that a different machine ID may indicate either a different machine or a change in machine configuration.Number(5,0)---1
PRODUCTHASHUnique IdentifierCharacter(35)---1418b89d7f859a2344d95dd035f28ced

Optional Seeding Data Columns

Some of the below columns may be present in addition to the other operation data columns described in the “Standard Data Columns” section

Name

Description

Column Type

Units of Measure

Example

FuelFuel ConsumedNumber(18,8)liters, gallons0.00341322
VEHICLSPEEDVehicle SpeedNumber(18,8)kilometers per hour, miles per hour3.25
AIRTEMPAir TemperatureNumber(18,8)Fahrenheit, Celsius24
WINDDRCTNWind DirectionCharacter(2)---SE
WINDSPEEDWind SpeedNumber(18,8)m/hr1.6
SKYCNDTNSky ConditionsCharacter(23)---Sunny
HUMIDITYHumidityNumber(18,8)---23
SOILMOISTSoil MoistureCharacter(23)---Dry
SOILTEMPSoil TemperaturNumber(18,8)Fahrenheit, Celsius24
DELTATTemperature Variation During OperationNumber(18,8)Fahrenheit, Celsius6.5

Application Data Columns

Name

Description

Column Type

Units of Measure

Example

TimeUTC timestampCharacter(23)UTC"4/9/2012 1:45:35 PM"
HeadingDirection of travelNumber(18,8)deg (0 being magnetic north)179.999
DistanceDistance travelled since the last recorded pointNumber(18,8)meters or feet3.1
SwathwidthWidth of the implement sectionNumber(18,8)meters or feet3.5
ProductThe product applied for this sampleCharacter(23)---Authority First DF
SectionIDThe implement section id for this sampleNumber(5,0)---135
AppliedRateThe measured application rateNumber(18,8)kg per hectare, lb per acre, liters per hectare, or gal per acre32005.6
ControlRateThe prescribed application rate that was sent to the implementNumber(18,8)kg per hectare, lb per acre, liters per hectare, or gal per acre32000
TargetRateThe prescribed application rate in the absence of a control rateNumber(18,8)kg per hectare, lb per acre, liters per hectare, or gal per acre32000
ElevationElevation from the GPS receiver, adjusted for the receiver's vertical offsetDoublemeters or feet793.73737646
IsoTimeISO-formatted UTC timestampCharacter(23)---2014-10-03T16:13:27.000Z
MachineIndex identifying which machine usage is currently active. The .json file contains machine and operator ID's for each index value. Note that a different machine ID may indicate either a different machine or a change in machine configuration.Number(5,0)---1

Optional Application Data Columns

Some of the below columns may be present in addition to the other operation data columns described in the “Standard Data Columns” section

Name

Description

Column Type

Units of Measure

Example

FuelFuel ConsumedNumber(18,8)liters, gallons0.00341322
VEHICLSPEEDVehicle SpeedNumber(18,8)kilometers per hour, miles per hour3.25
AIRTEMPAir TemperatureNumber(18,8)Fahrenheit, Celsius24
WINDDRCTNWind DirectionCharacter(2)---SE
WINDSPEEDWind SpeedNumber(18,8)m/hr1.6
SKYCNDTNSky ConditionsCharacter(23)---Sunny
HUMIDITYHumidityNumber(18,8)---23
SOILMOISTSoil MoistureCharacter(23)---Dry
SOILTEMPSoil TemperaturNumber(18,8)Fahrenheit, Celsius24
DELTATTemperature Variation During OperationNumber(18,8)Fahrenheit, Celsius6.5
PRODUCTHASHUnique IdentifierCharacter(35)---1418b89d7f859a2344d95dd035f28ced

Additional Application Data Columns

Based on the type of application operation, some of these may be present in addition to the application data columns described above.

Name

Description

Column Type

Units of Measure

Example

APLDRTNApplied Rate NitrogenNumber(18,8)kg per hectare, lb per acre78.3
APLDRTP2O5Applied Rate PhosphorusNumber(18,8)kg per hectare, lb per acre78.3
APLDRTK2OApplied Rate PotassiumNumber(18,8)kg per hectare, lb per acre78.3
APLDRTNH4NApplied Rate AmmoniumNumber(18,8)kg per hectare, lb per acre78.3
APLDTLNApplied Total NitrogenNumber(18,8)kg, lb19.2
APLDTLP2O5Applied Total PhosphorusNumber(18,8)kg, lb19.2
APLDTLK2OApplied Total PotassiumNumber(18,8)kg, lb19.2
APLDTLNH4NApplied Total AmmoniumNumber(18,8)kg, lb19.2
TRGTRTNTarget Rate NitrogenNumber(18,8)kg per hectare, lb per acre9.56
TRGTRTP2O5Target Rate PhosphorusNumber(18,8)kg per hectare, lb per acre9.56
TRGTRTK2OTarget Rate PotassiumNumber(18,8)kg per hectare, lb per acre9.56
TRGTRTNH4NTarget Rate AmmoniumNumber(18,8)kg per hectare, lb per acre9.56
RXRATENPrescription Rate NitrogenNumber(18,8)kg per hectare, lb per acre9.56
RXRATEP2O5Prescription Rate PhosphorusNumber(18,8)kg per hectare, lb per acre9.56
RXRATEK2OPrescription Rate PotassiumNumber(18,8)kg per hectare, lb per acre9.56
RXRATENH4NPrescription Rate AmmoniumNumber(18,8)kg per hectare, lb per acre9.56
NCNCNTRNNitrogen ConcentrationNumber(18,8)kg per thousand gallon, lb per thousand gallon40.6
P2O5CNCNTRNPhosphorus ConcentrationNumber(18,8)kg per thousand gallon, lb per thousand gallon40.6
K2OCNCNTRNPotassium ConcentrationNumber(18,8)kg per thousand gallon, lb per thousand gallon40.6
NH4NCNCNTRNAmmonium ConcentrationNumber(18,8)kg per thousand gallon, lb per thousand gallon40.6
DRYMATTERDry MatterNumber(18,8)percent2.56

Tillage Data Columns

Name

Description

Column Type

Units of Measure

Example

TimeUTC timestampCharacter(23)UTC"4/9/2012 1:45:35 PM"
HeadingDirection of travelNumber(18,8)deg (0 being magnetic north)179.999
DistanceDistance travelled since the last recorded pointNumber(18,8)meters or feet3.1
SwathwidthWidth of the implement sectionNumber(18,8)meters or feet3.5
TillTypeTillage typeCharacter(23)---Disk
SectionIDThe implement section id for this sampleNumber(5,0)---135
ApplDepthThe measured Applied DepthNumber(18,8)inches0.00000000
CtrlDepthThe measured ControlDepthNumber(18,8)inches0.00000000
TrgtDepthThe measured Target DepthNumber(18,8)inches16.00000000
ApplPressThe measured applied pressureNumber(18,8)Pound-force per square inch (PSI)274.00964526
CtrlPressThe measured control pressureNumber(18,8)Pound-force per square inch (PSI)350.00000000
TrgtPressThe measured target PressureNumber(18,8)Pound-force per square inch (PSI)349.01228538
ElevationElevation from the GPS receiver, adjusted for the receiver's vertical offsetDoublemeters or feet793.73737646
IsoTimeISO-formatted UTC timestampCharacter(23)---2014-10-03T16:13:27.000Z
MachineIndex identifying which machine usage is currently active. The .json file contains machine and operator ID's for each index value. Note that a different machine ID may indicate either a different machine or a change in machine configuration.Number(5,0)---1

Optional Tillage Data Columns

Some of the below columns may be present in addition to the other operation data columns described in the “Standard Data Columns” section

Name

Description

Column Type

Units of Measure

Example

FuelFuel ConsumedNumber(18,8)liters, gallons0.00341322
VEHICLSPEEDVehicle SpeedNumber(18,8)kilometers per hour, miles per hour3.25
AIRTEMPAir TemperatureNumber(18,8)Fahrenheit, Celsius24
WINDDRCTNWind DirectionCharacter(2)---SE
WINDSPEEDWind SpeedNumber(18,8)m/hr1.6
SKYCNDTNSky ConditionsCharacter(23)---Sunny
HUMIDITYHumidityNumber(18,8)---23
SOILMOISTSoil MoistureCharacter(23)---Dry
SOILTEMPSoil TemperaturNumber(18,8)Fahrenheit, Celsius24
DELTATTemperature Variation During OperationNumber(18,8)Fahrenheit, Celsius6.5

Endpoints

List Field Operations

GET

/organizations/{orgId}/fields/{fieldId}/fieldOperations
This resource returns logical data structures representing the agronomic operations performed in a field. Supported field operation types include Seeding, Application, and Harvest. A single field operation may potentially span consecutive days depending on the type of operation. Each field operation may have one or more measurements, listed as links from the field operation itself. Each field operation will include links to:
  • organization: The organization which owns this data.
  • field: The field in which this operation was performed.
  • self: The field operation.

OAuth Scope Required: ag2

Request URI

GET https://sandboxapi.deere.com/platform/organizations/{orgId}/fields/{fieldId}/fieldOperations

Accept: application/vnd.deere.axiom.v3+json

ParameterTypeDescription & ExampleIn
orgId

Required

string

Owning Organization ID

Example: 12345

path

fieldId

Required

GUID

Field ID

Example: d01111d6-1fa4-4659-943a-3df4a6b7933c

path

cropSeason

integer

Retrieve operations for a specific crop season (year).

Example: 2016

query

fieldOperationType

string

Filter results by field operation type. Takes the values "APPLICATION", "HARVEST", "SEEDING", and "TILLAGE".

Example: HARVEST

query

embed

array

List available operation measurement types and totals.

Allowed Values: measurementTypes

query

workPlanIds

List Of GUID

Query by one or more workPlanIds(comma separated)

Example: ["d6166574-4ede-404e-8a68-85d4284b869d"]

query

x-deere-signature

string

x-deere-signature should be managed by the client per user per API. For a new user/new API, the first request will have a blank value for x-deere-signature. Changes can be tracked with the x-deere-signature returned in the response. If the response has not changed since the last API call, the value of x-deere-signature is not changed and the client should use the same String Token next time.

Example: 520122365ebb4870a344784570d202c7

header

FieldTypeDescription & Example
id
string
Field Operation ID
Example: MjkyMDdfNT
x-deere-signature
string
A new x-deere-signature response header will be included if the response has changed since last api call.
Example: 520122365ebb4870a344784570d202c7
fieldOperationType1
string
Field Operation type.
Example: application
cropSeason
string
Crop season year.
Example: 2015
adaptMachineType
string
The type of machine that generated the field operation. This may be "unknown".
Example: unknown
startDate
datetime
Starting date and time of this field operation..
Example: 2015-05-29T22:00:19.200Z
endDate
datetime
Ending date and time of this field operation.
Example: 2015-05-29T22:23:53.746Z
modifiedTime
datetime
Last time that anything was modified on this field operation.
Example: 2016-04-29T22:12:53.446Z
cropName
string
Crop Name.
Example: CORN_WET
varieties
array
List of seed varieties. Only available on harvest and seeding operation types. May contain guid, productType, name, brand, agencyRegistrationNumber, and tankMix
Example: [ { "@type": "Product", "productType": "SEED", "name": "aa1", "tankMix": false } ]
products

---

Details of the product applied during this field operation. Includes name, tankmix, rate, carrier, and components data.
Example: See sample response below.
name
string
Name of the tank mix
Example: Tank Mix Use 1
tankMix
boolean
Boolean flag as to whether the application operation was for a tank mix or not.
Example: true
rate

---

Rate of the application. Includes value and unitId2 data.
Example: See sample response below.
value
number
Numeric value.
Example: 10
unitId2
string
Unit of value.
Example: gal1ac-1
carrier

---

Data on the product carrier. Includes name and rate.
Example: See sample response below.
components

---

Data on the product component. Includes name and rate.
Example: See sample response below.
fieldOperationMachines
object
Machines utilized during this operation
erid
string
Doc File based Field Operation Machine erid.
Example: t48a7dd0-as35-44e1-81b4-435d494f7cd5
Operators
object
Operators that performed work using this machine
operatorId
string
Unique identifier for this operator
Example: 657b4391-79b3-4012-a617-7ceba7111ad0
name
string
Name of the operator
Example: John Doe
license
string
Operator license number
Example: ABC123
machineId
integer
PrincipalId of the machine
Example: 637795
vin
string
VIN of the machine
Example: WXYEJKB73894JE3
200 OK
Content-Type: application/vnd.deere.axiom.v3+json
x-deere-signature: 520122365ebb4870a344784570d202c7
{
  "links": [
    {
      "rel": "self",
      "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27/fieldOperations"
    }
  ],
  "total": 2,
  "values": [
    {
      "@type": "FieldOperation",
      "fieldOperationType": "Tillage",
      "adaptMachineType": "unknown",
      "cropSeason": "2012",
      "modifiedTime": "2018-05-16T15:04:24.787Z",
      "startDate": "2012-04-03T14:12:13.000Z",
      "endDate": "2012-04-06T15:53:37.408Z",
      "fieldOperationMachines": [
        {
          "@type": "FieldOperationMachine",
          "erid": "t48a7dd0-as35-44e1-81b4-435d494f7cd5",
          "machineId": 637795,
          "operators": [
            {
              "@type": "Operator",
              "operatorId": "OPERATOR_ID",
              "license": "OPERATOR_LICENSE",
              "name": "OPERATOR_NAME"
            }
          ],
          "vin": "WXYEJKB73894JE3"
        }
      ],
      "id": "MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw",
      "links": [
        {
          "@type": "Link",
          "rel": "organization",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456"
        },
        {
          "@type": "Link",
          "rel": "field",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27"
        },
        {
          "@type": "Link",
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw"
        },
        {
          "@type": "Link",
          "rel": "measurementTypes",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes"
        },
        {
          "@type": "Link",
          "rel": "client",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/clients/46234f43-0000-1000-4014-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "farm",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/farms/4641d448-0000-1000-4033-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "workPlans",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/workPlans/2fac815e-5696-4ff6-86a0-39093b7dbf7e"
        }
      ]
    },
    {
      "@type": "FieldOperation",
      "fieldOperationType": "application",
      "adaptMachineType": "unknown",
      "cropSeason": "2013",
      "modifiedTime": "2014-03-16T15:04:24.797Z",
      "startDate": "2013-07-03T16:36:08.000Z",
      "endDate": "2013-07-03T16:47:23.013Z",
      "products": {
        "@type": "Product",
        "name": "Tank Mix",
        "tankMix": true,
        "rate": {
          "@type": "EventMeasurement",
          "value": 12.5,
          "unitId": "gal1ac-1"
        },
        "carrier": {
          "@type": "Component",
          "name": "Water",
          "rate": {
            "@type": "EventMeasurement",
            "value": 12.5,
            "unitId": "gal1ac-1"
          }
        },
        "components": [
          {
            "@type": "Component",
            "name": "Touchdown Total",
            "rate": {
              "@type": "EventMeasurement",
              "value": 48,
              "unitId": "floz1ac-1"
            }
          },
          {
            "@type": "Component",
            "name": "FS MaxSupreme",
            "rate": {
              "@type": "EventMeasurement",
              "value": 32,
              "unitId": "floz1ac-1"
            }
          }
        ]
      },
      "id": "MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNg",
      "links": [
        {
          "@type": "Link",
          "rel": "organization",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456"
        },
        {
          "@type": "Link",
          "rel": "field",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27"
        },
        {
          "@type": "Link",
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNg"
        },
        {
          "@type": "Link",
          "rel": "measurementTypes",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNg/measurementTypes"
        },
        {
          "@type": "Link",
          "rel": "client",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/clients/46234f43-0000-1000-4014-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "farm",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/farms/4641d448-0000-1000-4033-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "shapeFile",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNg"
        },
        {
          "@type": "Link",
          "rel": "shapeFileAsync",
          "uri": "https://sandboxapi.deere.com/platform/fieldOps/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNg"
        },
        {
          "@type": "Link",
          "rel": "workPlans",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/workPlans/2fac815e-5696-4ff6-86a0-39093b7dbf7e"
        }
      ]
    }
  ]
}


View a Field Operation

GET

/fieldOperations/{operationId}
View a single field operation. The response will include links to:
  • organization: The organization which owns this data.
  • field: The field in which this operation was performed.
  • self: The field operation.

    OAuth Scope Required: ag2

    Request URI

    GET https://sandboxapi.deere.com/platform/fieldOperations/{operationId}

    Accept: application/vnd.deere.axiom.v3+json

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MTIzNF81NjFiZGY1

    path

    embed

    array

    List available operation measurement types and totals.

    Allowed Values: measurementTypes

    query

    FieldTypeDescription & Example
    orgId
    string
    The organization ID.
    Example: 1234
    cropSeason
    string
    The year in which the grower logically assigned this operation. Note that operational activity may occur outside this calendar year.
    Example: 2015
    fieldOperationType1
    string
    A string indicating the type of operation (valid values include: seeding, application, harvest, or tillage).
    Example: Harvest
    cropName
    string
    A string indicating the type of crop used during this operation. Can be omitted based on operation type and original data source. Only available on harvest and seeding operation types.
    Example: CORN_WET
    modifiedTime
    datetime
    Last time that anything was modified on this field operation.
    Example: 2018-11-17T11:53:00.000Z
    varieties
    array
    List of seed varieties. Only available on harvest and seeding operation types. May contain guid, productType, name, brand, agencyRegistrationNumber, and tankMix
    Example: [ { "@type": "Product", "productType": "SEED", "name": "aa1", "tankMix": false } ]
    adaptMachineType
    string
    The type of machine that generated the field operation. This may be "unknown".
    Example: unknown
    fieldOperationMachines
    object
    Machines utilized during this operation
    erid
    string
    Doc File based Field Operation Machine erid.
    Example: t48a7dd0-as35-44e1-81b4-435d494f7cd5
    Operators
    object
    Operators that performed work using this machine
    operatorId
    string
    Unique identifier for this operator
    Example: 657b4391-79b3-4012-a617-7ceba7111ad0
    name
    string
    Name of the operator
    Example: John Doe
    license
    string
    Operator license number
    Example: ABC123
    machineId
    integer
    PrincipalId of the machine
    Example: 637795
    vin
    string
    VIN of the machine
    Example: WXYEJKB73894JE3
    200 OK
    Content-Type: application/vnd.deere.axiom.v3+json
    {
      "@type": "FieldOperation",
      "fieldOperationType": "tillage",
      "adaptMachineType": "unknown",
      "cropSeason": "2012",
      "modifiedTime": "2018-05-16T15:04:24.787Z",
      "fieldOperationMachines": [
        {
          "@type": "FieldOperationMachine",
          "GUID": "t48a7dd0-as35-44e1-81b4-435d494f7cd5",
          "erid": "t48a7dd0-as35-44e1-81b4-435d494f7cd5",
          "machineId": 637795,
          "operators": [
            {
              "@type": "Operator",
              "operatorId": "OPERATOR_ID",
              "license": "OPERATOR_LICENSE",
              "name": "OPERATOR_NAME"
            }
          ],
          "vin": "WXYEJKB73894JE3"
        }
      ],
      "id": "MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw",
      "links": [
        {
          "@type": "Link",
          "rel": "organization",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456"
        },
        {
          "@type": "Link",
          "rel": "field",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27"
        },
        {
          "@type": "Link",
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw"
        },
        {
          "@type": "Link",
          "rel": "measurementTypes",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes"
        },
        {
          "@type": "Link",
          "rel": "tillageDepthTarget",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes/TillageDepthTarget"
        },
        {
          "@type": "Link",
          "rel": "tillageDepthResult",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes/TillageDepthResult"
        },
        {
          "@type": "Link",
          "rel": "tillagePressureTarget",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes/TillagePressureTarget"
        },
        {
          "@type": "Link",
          "rel": "tillagePressureResult",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes/TillagePressureResult"
        },
        {
          "@type": "Link",
          "rel": "tillageSpeedResult",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkMw/measurementTypes/TillageSpeedResult"
        },
        {
          "@type": "Link",
          "rel": "client",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/clients/46234f43-0000-1000-4014-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "farm",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/farms/4641d448-0000-1000-4033-e1e1e11124e0"
        },
        {
          "@type": "Link",
          "rel": "workPlans",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/workPlans/2fac815e-5696-4ff6-86a0-39093b7dbf7e"
        }
      ]
    }


    Asynchronous Shapefile Download

    GET

    /fieldOps/{operationId}
    An ESRI Shapefile is available for each Field Operation. Please see the shapefiles overview for details on the shapefile format and how to consume it.

    The expected response codes are:

    • 202 Accepted – The request was received and is being processed. Call back later to check for completion.
      • This API does not currently support webhooks. To check for completion, repeat the same API call until you get an HTTP 307.
      • Processing may take up to 30 minutes, depending on the size of data. Applications should poll the API using a backoff loop. Polling intervals should start at 5 seconds and double with each attempt: secondsToWait = 5 * 2 ^ (numberOfAttempts - 1)
    • 307 Temporary Redirect – The shapefile is ready to download. This response contains a location header. The location is a pre-signed URL that is valid for no less than one hour. To download the file, perform a GET request to the URL in the location header. Do not apply OAuth signing or other authorization to this request - it will cause the call to fail.
    • 406 Not Acceptable - A shapefile cannot be generated.
    Note the initial call for a shapefile may receive either a 202 or a 307 response, depending upon whether an up-to-date file already exists for the specified field operation.

    For a sample integration, see our Java sample code.

    OAuth Scope Required: ag2

    Request URI

    GET https://sandboxapi.deere.com/platform/fieldOps/{operationId}

    Accept: application/vnd.deere.axiom.v3+json

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MTIzNF81NjFiZGY1

    path

    splitShapeFile

    boolean

    If true, this will download the shapefile in small 20MB pieces

    Example: false

    query

    shapeType

    string

    Choose between point-based and polygon-based shapefiles. Accepted values are "Point" and "Polygon".

    Example: Polygon

    Allowed Values: Point,Polygon

    query

    resolution

    string

    Choose a data resolution for the shapefile. Accepted values are "EachSection", "EachSensor", and "OneHertz".

    Example: EachSensor

    Allowed Values: EachSection,EachSensor,OneHertz

    query

    Accept-UOM-System

    string

    Unit of measure system to use for numeric values in the shapefiles. Accepted values are "METRIC", "ENGLISH", and "MIXED".If this header is not specified, the unit system will be determined by the organization preference of the owning organization.For all unit systems, the units are consistent with ADAPT's unit system.

    Example: METRIC

    header

    Accept-Yield-Preference

    string

    Desired yield representation (unit) type. Accepted values are VOLUME or MASS.

    Example: VOLUME

    header


    vrTillageDepthTarget

    This representation defines units allowed to specify target tillage depth for tillage operation

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    in31-100.0100.0English
    cm31-254.0254.0Metric
    in31-100.0100.0Mixed

    vrSeedRateMassTarget

    This representation defines units allowed to specify target seed mass per area for seeding operation

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    lb1ac-1510.099999.9English
    ton1ac-1510.099999.9English
    lb1[ft2]-1510.099999.9English
    kg1ha-1510.099999.9Metric
    t1ha-1510.099999.9Metric
    kg1[m2]-1510.099999.9Metric
    lb1ac-1510.099999.9Mixed
    kg1[ft2]-1510.099999.9Mixed
    kg1ac-1510.099999.9Mixed

    vrSeedRateSeedsTarget

    This representation defines units allowed to specify seeds per area for seeding operation

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    seeds1ac-180099999999English
    thndSeeds1ac-1610.0100000.0English
    seeds1[ft2]-1410.09999.9English
    seeds1ha-180099999999Metric
    thndSeeds1ha-1610.0100000.0Metric
    seeds1[m2]-1410.09999.9Metric
    seeds1ac-180099999999Mixed
    seeds1[ft2]-1410.09999.9Mixed

    vrAppRateMassTarget

    This representation defines units allowed to specify average target application mass rate per area

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    lb1ac-1520.0099999.99English
    ton1ac-1520.0099999.99English
    ozm1ac-1520.0099999.99English
    ozm1[ft2]-1420.009999.99English
    kg1ha-1520.0099999.99Metric
    t1ha-1520.0099999.99Metric
    g1ha-1520.0099999.99Metric
    mg1ha-1520.0099999.99Metric
    dg1ha-1520.0099999.99Metric
    dg1[mm2]-1510.099999.9Metric
    mg1[m2]-14009999Metric
    g1[m2]-14009999Metric
    kg1[m2]-1520.0099999.99Metric
    lb1ac-1520.0099999.99Mixed
    kg1ac-1520.0099999.99Mixed
    ton1ac-1520.0099999.99Mixed
    ozm1ac-1520.0099999.99Mixed
    t1ac-1520.0099999.99Mixed
    g1ac-1520.0099999.99Mixed
    mg1ac-1520.0099999.99Mixed
    dg1ac-1520.0099999.99Mixed

    vrAppRateVolumeTarget

    This representation defines units allowed to specify average target application volume rate per area

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    gal1ac-1520.0099999.99English
    qt1ac-1520.0099999.99English
    pt1ac-1520.0099999.99English
    floz1ac-1520.0099999.99English
    l1ha-1620.00935395.53Metric
    ml1ha-1520.0099999.99Metric
    kl1ha-1520.0099999.99Metric
    ul1ha-1520.0099999.99Metric
    dl1ha-1520.0099999.99Metric
    [m3]1ha-1520.0099999.99Metric
    gal1ac-1520.0099999.99Mixed
    kl1ac-1520.0099999.99Mixed
    qt1ac-1520.0099999.99Mixed
    pt1ac-1520.0099999.99Mixed
    floz1ac-1520.0099999.99Mixed
    ul1ac-1520.0099999.99Mixed
    ml1ac-1520.0099999.99Mixed
    l1ac-1520.0099999.99Mixed
    dl1ac-1520.0099999.99Mixed

    vrSolutionRateLiquid

    This representation defines units allowed to specify liquid solution rate per area

    Units

    Unit Of MeasureDigitsDecimalMin ValueMax ValueMeasurement System
    gal1ac-1530.00099999.999English
    qt1ac-1520.0099999.99English
    pt1ac-1520.0099999.99English
    floz1ac-1520.0099999.99English
    l1ha-1530.00099999.999Metric
    ml1ha-1520.0099999.99Metric
    kl1ha-1520.0099999.99Metric
    ul1ha-1520.0099999.99Metric
    dl1ha-1520.0099999.99Metric
    [m3]1ha-1520.0099999.99Metric
    gal1ac-1530.00099999.999Mixed
    kl1ac-1520.0099999.99Mixed
    qt1ac-1520.0099999.99Mixed
    pt1ac-1520.0099999.99Mixed
    floz1ac-1520.0099999.99Mixed
    ul1ac-1520.0099999.99Mixed
    ml1ac-1520.0099999.99Mixed
    l1ac-1520.0099999.99Mixed
    dl1ac-1520.0099999.99Mixed

    dtProjectionType

    This type defines the allowed values used to specify coordinate system for a guidance line

    Values

    Defined type valueCalculation Method
    dtiProjectionDeereDeere
    dtiNonJohnDeere1BeeLine
    dtiNonJohnDeere2Trimble

    dtSignalType

    This type defines allowed values to specify signal type used for boundary data

    Values

    dtiSignalTypeUnknown
    dtiSignalTypeDigitized
    dtiSignalTypeNoDiff
    dtiSignalTypeUnknownDiff
    dtiSignalTypeWAAS
    dtiSignalTypeSF1
    dtiSignalTypeSF2
    dtiSignalTypeRTKX
    dtiSignalTypeRTK
    dtiSignalTypeSF3
    dtiSignalTypeSFRTK
    dtiSignalTypeNonJdDiff
    dtiSignalTypeJdDiff


    Shape Type and Resolution

    While the shapeType and resolution parameters are optional, we strongly recommend providing a value. These parameters dramatically affect the file size of the resulting shapefile. The file sizes in the table below are approximate guidelines and will vary considerably.

    ShapeTypeResolutionDescriptionFile Size
    PointEachSectionThis is the default value, provided for backwards compatibility. Since our newer displays divide farm implements into ~6 inch virtual sections, these files are very large and contain a dramatic amount of duplicate data.Up to 65GB
    PointEachSensorThe shapefile contains a point for each sensor reading, centered in the area represented by that sensor. This matches the default shapefile format, but will not contain duplicate data.Up to 250MB
    PointOneHertzThe shapefile contains a point for each sensor reading, with approximately one sensor reading per second. Up to 75MB
    PolygonEachSectionNot supported.---
    PolygonEachSensorThe shapefile contains a polygon for each sensor reading. Note the polygon connects the current and previous locations of the implement. Due to irregular shapes during turns, the area covered by the polygon may not match the result of multiplying the SwathWidth and Distance values. The latter will more closely represent Area Worked as displayed in Operations Center.Up to 350MB
    PolygonOneHertzThe shapefile contains a polygon for each sensor reading, with approximately one sensor reading per second. See the note above regarding area calculations.Up to 120MB

    Sample API interaction Flow:

    GET https://sandboxapi.deere.com/platform/fieldOps/MjI0NzY0XzU3MDQyMjNmMmE1YjBlMDUwOGJjYjY5MA
    Accept: application/vnd.deere.axiom.v3+json
    Authorization: OAuth realm="",oauth_timestamp="1476218511",oauth_nonce="TOaKbf",oauth_consumer_key=
    "com.deere.example",oauth_token="5a787695-14a7-484b-815b-4d42b51757ab",oauth_version="1.0",oauth_signature_method=
    "HMAC-SHA1",oauth_signature="vKvV4t%2BjAC1E07IhNazB9C601os%3D"
    202 Accepted
    GET https://sandboxapi.deere.com/platform/fieldOps/MjI0NzY0XzU3MDQyMjNmMmE1YjBlMDUwOGJjYjY5MA
    Accept: application/vnd.deere.axiom.v3+json
    Authorization: OAuth realm="",oauth_timestamp="1476218511",oauth_nonce="TOaKbf",oauth_consumer_key=
    "com.deere.example",oauth_token="5a787695-14a7-484b-815b-4d42b51757ab",oauth_version="1.0",oauth_signature_method=
    "HMAC-SHA1",oauth_signature="vKvV4t%2BjAC1E07IhNazB9C601os%3D"
    307 Temporary Redirect
    Location: https://jd-us01-isg-prod-system.s3.amazonaws.com/ShapefileExport/df711460-71e7-4429-a4df-67b1a19d3b48.zip?
    x-amz-security-token=FQoDYXdzEGUaDGt6%2F%2BGNitPEbwVfwiLnAQG1UvviHnQoEkQArJXffEFLU1p%2Fh6vhmMIFwp%2BFihHgBafXGH8UGsSo
    miTi4YSp1MZkKJMFQFpmn2ELv3mDyJJ77tN10dRTakYoHCviiW0Bwzm9AUHsATmix8nkE7d5QE7UG%2BGCy3z0wfqwaEpaXWsisCK%2BFHbgJ%2BvTRO%
    2BOoNCS5W%2FuJXSt0EYjWU92RQqhQNliID0jz4SY%2BDFISmOdLRoDuopvo2IlvGwZzipvHFZQ4%2BOPi8t3JEntth5ZAVl3jFDSl5Ht%2FxEHGI5A00
    XQjPNzjCPIM%2F4on%2FSXn676Bp344o3Y47%2BrOyi%2Fk%2FW%2FBQ%3D%3D&AWSAccessKeyId=ASIAJI3QZ3SUCORJR2IQ&Expires=1476220879
    &Signature=REYgo2KLAOMQZFP1iqe0XVaWAfg%3D
    GET https://jd-us01-isg-prod-system.s3.amazonaws.com/ShapefileExport/df711460-71e7-4429-a4df-67b1a19d3b48.zip?x-amz
    -security-token=FQoDYXdzEGUaDGt6%2F%2BGNitPEbwVfwiLnAQG1UvviHnQoEkQArJXffEFLU1p%2Fh6vhmMIFwp%2BFihHgBafXGH8UGsSomiT
    i4YSp1MZkKJMFQFpmn2ELv3mDyJJ77tN10dRTakYoHCviiW0Bwzm9AUHsATmix8nkE7d5QE7UG%2BGCy3z0wfqwaEpaXWsisCK%2BFHbgJ%2BvTRO%2
    BOoNCS5W%2FuJXSt0EYjWU92RQqhQNliID0jz4SY%2BDFISmOdLRoDuopvo2IlvGwZzipvHFZQ4%2BOPi8t3JEntth5ZAVl3jFDSl5Ht%2FxEHGI5A0
    0XQjPNzjCPIM%2F4on%2FSXn676Bp344o3Y47%2BrOyi%2Fk%2FW%2FBQ%3D%3D&AWSAccessKeyId=ASIAJI3QZ3SUCORJR2IQ&Expires=1476220
    879&Signature=REYgo2KLAOMQZFP1iqe0XVaWAfg%3D
    Accept: application/vnd.deere.axiom.v3+json
    200 OK
    Content-Type: application/zip
    Content-Length: 1162659

    Please Note: If you try this request from Postman, you must turn off the "Automatically follow redirects" option.


    Additional Information

    1. Field Operation Types: seeding; application; harvest; tillage

    2. Units: The unit format that looks like [floz1ac-2] is from ADAPT. Positive numbers follow the unit in the numerator, whereas negative numbers follow the denominator. The value of the positive or negative numbers in the unit indicate the power. floz1ac-2 = fluid ounces per acre squared; gal1ac-1 = gallons per acre.

    3. Web Mercator Projections: Please note that the Web Mercator projection differs from other projections like WGS 84. The images retrieved from this endpoint will not align with background imagery unless overlaid on a Web Mercator projected background. The National Geospatial Intelligence Agency (NGA) has a technical document describing the Web Mercator projection.

    4. These values are only included in responses for Harvest Yield Contour or Harvest Yield Results field operation types.

    5. These values are only included in responses for Application Tank Mix, Application Single Solution, or Seeding field operation types.


    Field Operation Measurements

    GET

    /fieldOperations/{operationId}/measurementTypes
    Field Operations include a variety of measurements collected when the operation is performed in the field. This endpoint returns an array of measurement types available for a given field operation. Two categories of measurements are available today:
    • Target: Target measurements refer to what the machine or implement attempted to perform in the field.
    • Result: Result measurements refer to what the machine or implement actually accomplished in the field.
    For example, the SeedingRateTarget measurement describes the rate at which the equipment attempted to plant seeds, while the SeedingRateResult measurement describes the rate at which seeds were actually planted by the equipment. Target measurements may be consistent throughout the entire operation (the operator may have applied a single rate across an entire field) but result measurements will vary during the operation as they account for machine error, operator error, and environmental factors. The difference in rate and location are easily visible in the associated map image.

    Note: The values included in the responses will depend on their availability as well as the field operation type (Seeding, Application Tank Mix, Application Single Product, Harvest Yield Contour, or Harvest Yield Result). Please refer measurement types

    OAuth Scope Required: ag2

    Request URI

    GET https://sandboxapi.deere.com/platform/fieldOperations/{operationId}/measurementTypes

    Accept: application/vnd.deere.axiom.v3+json

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MTIzNF81NjFiZGY1

    path

    measurementType

    string

    Measurement Type

    Example: HarvestYield

    path

    KeyTypeDescription & ExampleIn / Defaults

    Accept-UOM-System

    string

    Desired unit system. Takes ENGLISH or METRIC.

    Example: ENGLISH

    path

    Accept-Yield-Preference

    string

    Desired yield representation (unit) type. Takes VOLUME or MASS.

    Example: MASS

    path

    Seeding Operation

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MzA0Nl81Njg0Z

    path

    measurementType

    Required

    string

    Measurement Type

    Example: SeedingVarietiesResult

    path

    FieldTypeDescription & Example
    measurementName
    string
    Measurement Name.
    Example: SeedingVarietiesResult
    measurementCategory
    string
    Measurement Category.
    Example: Result
    area

    ---

    The area covered for this measurement. Includes value, and unitId2.
    Example: See "Seeding" sample responses below.
    totalMaterial

    ---

    The total amount of seeds applied during the operation. Includes value and unitId2.
    Example: See "Seeding" sample responses below.
    averageMaterial

    ---

    The average amount of seeds applied during the operation. Includes value and unitId2.
    Example: See "Seeding" sample responses below.
    varietyTotals

    ---

    An array of the same measurements, broken down by variety. See the table below for details.
    Example: See "Seeding" sample responses below.
    FieldTypeDescription & Example
    name

    string

    Variety name.
    Example: 33B54
    area

    ---

    The area covered for this measurement. Includes value and unitId2.
    Example: See "Seeding" sample response below.
    totalMaterial

    ---

    The total amount of seeds applied during the operation. Includes value and unitId2.
    Example: See "Seeding" sample response below.
    averageMaterial

    ---

    The average amount of seeds applied during the operation. Includes value and unitId2.
    Example: See sample responses below.
    FieldTypeDescription & Example
    value

    int

    Numeric measurement value.
    Example: 333178
    unitId2

    string

    Unit of measurement.
    Example: seeds1ha-1
    200 OK
    Content-Type: application/vnd.deere.axiom.v3+json
    {
      "@type": "FieldOperationMeasurement",
      "measurementName": "SeedingVarietiesResult",
      "measurementCategory": "Result",
      "area": {
        "@type": "EventMeasurement",
        "value": 38.07,
        "unitId": "ha"
      },
      "totalMaterial": {
        "@type": "EventMeasurement",
        "value": 12016203,
        "unitId": "seeds"
      },
      "averageMaterial": {
        "@type": "EventMeasurement",
        "value": 315631,
        "unitId": "seeds1ha-1"
      },
      "varietyTotals": [
        {
          "@type": "VarietyTotal",
          "name": "4204",
          "area": {
            "@type": "EventMeasurement",
            "value": 24.24,
            "unitId": "ha"
          },
          "totalMaterial": {
            "@type": "EventMeasurement",
            "value": 7408062,
            "unitId": "seeds"
          },
          "averageMaterial": {
            "@type": "EventMeasurement",
            "value": 305619,
            "unitId": "seeds1ha-1"
          }
        },
        {
          "@type": "VarietyTotal",
          "name": "4302",
          "area": {
            "@type": "EventMeasurement",
            "value": 13.83,
            "unitId": "ha"
          },
          "totalMaterial": {
            "@type": "EventMeasurement",
            "value": 4608141,
            "unitId": "seeds"
          },
          "averageMaterial": {
            "@type": "EventMeasurement",
            "value": 333178,
            "unitId": "seeds1ha-1"
          }
        }
      ],
      "links": [
        {
          "@type": "Link",
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MzA0Nl81Njg0Z/measurementTypes/SeedingVarietiesResult"
        },
        {
          "@type": "Link",
          "rel": "mapImage",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MzA0Nl81Njg0Z/measurementTypes/SeedingVarietiesResult"
        },
        {
          "@type": "Link",
          "rel": "organization",
          "uri": "https://sandboxapi.deere.com/platform/organizations/1234"
        },
        {
          "@type": "Link",
          "rel": "field",
          "uri": "https://sandboxapi.deere.com/platform/organizations/1234/fields/c95d5d46-1ce7-4e6b-ac8f-f5ff67324f14"
        },
        {
          "@type": "Link",
          "rel": "fieldOperation",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MzA0Nl81Njg0Z"
        }
      ]
    }

    FieldTypeDescription & Example
    total
    integer
    Number of results in the list
    Example: 70

    Field Operation Map Image

    GET

    /fieldOperations/{operationId}/measurementTypes/{measurementType}
    A map image is available for each measurement, offering a visual depiction of the data. Agronomic data points are grouped either by label (such as variety name) or numerical range, and this information is provided in the JSON response as a map legend.

    Each measurement includes the following links:
    • organization: The organization that owns this data.
    • field: The field where this operation took place.
    • fieldOperation: This field operation.
    • measurementType: The corresponding measurement type.
    • self: The map image.

    OAuth Scope Required: ag2

    Request URI

    GET https://sandboxapi.deere.com/platform/fieldOperations/{operationId}/measurementTypes/{measurementType}

    Accept: application/vnd.deere.axiom.v3.image+json

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MTIzNF81NjFiZGY1

    path

    measurementType

    string

    Measurement Type

    Example: HarvestYield

    path

    KeyTypeDescription & ExampleIn / Defaults

    Accept-UOM-System

    string

    Desired unit system. Takes ENGLISH or METRIC.

    Example: ENGLISH

    path

    Accept-Yield-Preference

    string

    Desired yield representation (unit) type. Takes VOLUME or MASS.

    Example: MASS

    path

    FieldTypeDescription & Example
    name
    string
    Field Operation name.
    Example: fieldOperationMapImage
    declaredType

    ---

    ---
    Example: See sample response below.
    scope

    ---

    ---
    Example: See sample response below.
    image
    Base64 encoded PNG image
    The PNG image file.
    Example: See sample response below.
    legends

    ---

    The legend used to render the map image. Includes unitId2 and ranges.
    Example: See sample response below.
    extent

    ---

    Two coordinates that represent the corners of the image when overlaid onto a Web Mercator projection1. Includes minimumLatitude, minimumLongitude, maximumLatitude, and maximumLongitude.
    Example: See sample response below.
    unitId2
    string
    Numeric values in the legend's ranges are measurements in this unit. The unit depends on the Accept-UOM-System header for the MapImage request.
    Example: cm
    ranges

    ---

    The ranges contained in the legend. Includes either a label (for non-numeric ranges), or minimum, maximum, hexColor, and percent.
    Example: See sample response below.
    label
    string
    A label associated with the legend item. May be omitted for ranges with numeric values.
    Example: 15
    hexColor
    string
    The HEX color value of the legend item.
    Example: #4B0082
    percent
    number
    The percentage of agronomic data points that are represented by this legend item. For example, 0.05 means that 5% of the operation's measurements fall into this legend range.
    Example: 1
    nil
    boolean
    ---
    Example: false
    globalScope
    boolean
    ---
    Example: true
    typeSubstituted
    boolean
    ---
    Example: false
    200 OK
    Content-Type: application/vnd.deere.axiom.v3+json
    {
      "name": "fieldOperationMapImage",
      "declaredType": "com.deere.api.axiom.generated.v3.FieldOperationMapImage",
      "scope": "javax.xml.bind.JAXBElement$GlobalScope",
      "value": {
        "image": "data:image/png;base64...",
        "legend": {
          "@type": "MapLegend",
          "unitId": "cm",
          "ranges": [
            {
              "@type": "MapLegendItem",
              "label": "15",
              "hexColor": "#4B0082",
              "percent": 1
            }
          ]
        },
        "extent": {
          "@type": "MapExtent",
          "minimumLatitude": 41.66625903184001,
          "maximumLatitude": 41.669542228078,
          "minimumLongitude": -93.15431597923825,
          "maximumLongitude": -93.15009035584056
        },
        "links": [
          {
            "@type": "Link",
            "rel": "self",
            "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA/measurementTypes/TillageDepthTarget"
          },
          {
            "@type": "Link",
            "rel": "organization",
            "uri": "https://sandboxapi.deere.com/platform/organizations/123456"
          },
          {
            "@type": "Link",
            "rel": "field",
            "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27"
          },
          {
            "@type": "Link",
            "rel": "fieldOperation",
            "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA"
          },
          {
            "@type": "Link",
            "rel": "measurementType",
            "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA/measurementTypes/TillageDepthTarget"
          }
        ]
      },
      "nil": false,
      "globalScope": true,
      "typeSubstituted": false
    }


    Field Operation Measurement

    GET

    /fieldOperations/{operationId} /measurementTypes/{measurementType}
    Field Operations include a variety of measurements collected when the operation is performed in the field. This endpoint returns an array of measurement types available for a given field operation. Two categories of measurements are available today:
    • Target: Target measurements refer to what the machine or implement attempted to perform in the field.
    • Result: Result measurements refer to what the machine or implement actually accomplished in the field.
    For example, the SeedingRateTarget measurement describes the rate at which the equipment attempted to plant seeds, while the SeedingRateResult measurement describes the rate at which seeds were actually planted by the equipment. Target measurements may be consistent throughout the entire operation (the operator may have applied a single rate across an entire field) but result measurements will vary during the operation as they account for machine error, operator error, and environmental factors. The difference in rate and location are easily visible in the associated map image.

    Note: The values included in the responses will depend on their availability as well as the field operation type (Seeding, Application Tank Mix, Application Single Product, Harvest Yield Contour, or Harvest Yield Result). To view the different responses for each field operation type, view the Field Operation Measurements documentation above. Please refer measurement types

    OAuth Scope Required: ag2

    Request URI

    GET https://sandboxapi.deere.com/platform/fieldOperations/{operationId} /measurementTypes/{measurementType}

    Accept: application/vnd.deere.axiom.v3+json

    ParameterTypeDescription & ExampleIn
    operationId

    Required

    string

    Operation ID

    Example: MTIzNF81NjFiZGY1

    path

    measurementType

    string

    Measurement Type

    Example: HarvestYield

    path

    KeyTypeDescription & ExampleIn / Defaults

    Accept-UOM-System

    string

    Desired unit system. Takes ENGLISH or METRIC.

    Example: ENGLISH

    path

    Accept-Yield-Preference

    string

    Desired yield representation (unit) type. Takes VOLUME or MASS.

    Example: MASS

    path

    FieldTypeDescription & Example
    measurementName
    string
    Measurement Name.
    Example: TillageDepthTarget
    measurementCategory
    string
    Measurement Category.
    Example: Target
    area

    ---

    The area covered for this measurement. Includes value, and unitId2.
    Example: See sample response below
    averageDepth

    ---

    The average depth observed across the area covered. Includes value, and unitId.
    Example: See sample response below
    value
    integer
    Numeric measurement value.
    Example: 15.24
    unitId2
    string
    Unit of measurement.
    Example: cm
    200 OK
    Content-Type: application/vnd.deere.axiom.v3+json
    {
      "@type": "FieldOperationMeasurement",
      "measurementName": "TillageDepthTarget",
      "measurementCategory": "Target",
      "area": {
        "@type": "EventMeasurement",
        "value": 0.72,
        "unitId": "ha"
      },
      "averageDepth": {
        "@type": "EventMeasurement",
        "value": 15.24,
        "unitId": "cm"
      },
      "links": [
        {
          "@type": "Link",
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA/measurementTypes/TillageDepthTarget"
        },
        {
          "@type": "Link",
          "rel": "mapImage",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA/measurementTypes/TillageDepthTarget"
        },
        {
          "@type": "Link",
          "rel": "organization",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456"
        },
        {
          "@type": "Link",
          "rel": "field",
          "uri": "https://sandboxapi.deere.com/platform/organizations/123456/fields/d61b83f4-3a12-431e-8010-596f2466dc27"
        },
        {
          "@type": "Link",
          "rel": "fieldOperation",
          "uri": "https://sandboxapi.deere.com/platform/fieldOperations/MjIzMDMxXzU4NDFkMDM2YTA2ZDkwMDk3MGYyNDJkNA"
        }
      ]
    }


    Additional Information

    1. Web Mercator Projections: Please note that the Web Mercator projection differs from other projections like WGS 84. The images retrieved from this endpoint will not align with background imagery unless overlaid on a Web Mercator projected background. The National Geospatial Intelligence Agency (NGA) has a technical document describing the Web Mercator projection.

    2. Units: The unit format that looks like [floz1ac-2] is from ADAPT. Positive numbers follow the unit in the numerator, whereas negative numbers follow the denominator. The value of the positive or negative numbers in the unit indicate the power. floz1ac-2 = fluid ounces per acre squared; gal1ac-1 = gallons per acre.

    Measurement Type

    Measurement

    Description

    TargetSeedingRateTargetThe target amount of seed to be applied.
    ResultSeedingRateResultThe actual amount of seed applied.
    ResultSeedingSpeedResultHow far apart each seed was placed.
    TargetSeedingVarietiesTargetThe target crop varieties to be applied.
    ResultSeedingVarietiesResultThe target amount of seed to be applied.
    TargetApplicationRateTargetThe target amount of product to be applied.
    ResultApplicationRateResultThe actual amount of product that was applied.
    ResultApplicationSpeedResult
    ResultHarvestYieldResultThe actual yield measured.
    ResultHarvestYieldContourResultDry yield calculated from a contour map.
    ResultHarvestWetMassResultThe actual wet mass collected.
    ResultHarvestMoistureResultThe moisture content of the harvested crop.
    ResultHarvestTrashResultTrash mixed with the harvest from a sugarcane harvester.
    ResultHarvestSpeedResult
    ResultHarvestAdfResultAcid detergent fiber from a forage harvester
    ResultHarvestNdfResultNeutral detergent fiber from a forage harvester.
    ResultHarvestCrudeProteinResultCrude protein measured by a forage harvester.
    ResultHarvestStarchResultStarch content measured by a forage harvester.
    ResultHarvestSugarResultSugar content measured by a forage harvester.
    ResultTillageDepthResultMeasured tillage depth.
    ResultTillagePressureResultDownforce applied to a tillage implement.
    ResultTillageSpeedResult
    TargetTillageDepthTargetExpected tillage depth.
    TargetTillagePressureTargetExpected downforce from a tillage operation.

    Field Operation Event

    Field operation events are triggered whenever an addition, modification, or deletion is made to a field operation. For example, if new field operation data is available or if field operation data has been edited, then an event will be sent. The client must specify an orgId filter while creating a subscription. Other filters are optional. The values for each filter are arrays, so multiple orgIds, cropSeasons, fieldIds, and/or fieldOperationTypes may be requested in a single subscription.

    These events are provided through Data Subscription Service. Learn how to subscribe to events on the Getting Started page.

    Field operation subscriptions are best created for a single orgId rather than multiple since:

    • You cannot change the list of orgIds in a subscription after it has been created, and

    • Subscriptions are terminated if the user loses access to any of the orgIds in the subscription.

    FieldOperation Event Filters

    MetaDataFilter

    Required

    Example:

    Description

    orgId

    Yes

    ["123456", "654321"]

    The organization associated to the fields.

    cropSeason

    No

    ["2019"]

    The crop season associated with the field operation.

    fieldId

    No

    ["0f38f7e1-299d-4823-aafc-13be555605ed"]

    The GUID(s) that identifies the field(s).

    fieldOperationType

    No

    ["seeding", "harvest"]

    Any operation type of ["application", "harvest", "seeding", "tillage"].


    A 404 response from following the targetResource link signifies that the Field Operation was deleted.


    {
      "clientKey": "johndeere-123456789",
      "eventTypeId": "fieldOperation",
      "targetResource": "https://sandboxapi.deere.com/platform/fieldOperations/MTIzNF81NjFiZG00",
      "metadata": [
        {
          "key": "orgId",
          "value": "123456"
        },
        {
          "key": "cropSeason",
          "value": "2019"
        },
        {
          "key": "fieldId",
          "value": "0f38f7e1-299d-4823-aafc-13be555605ed"
        },
        {
          "key": "fieldOperationType",
          "value": "application"
        }
      ],
      "links": [
        {
          "rel": "user",
          "uri": "https://sandboxapi.deere.com/platform/users/johndoe"
        },
        {
          "rel": "subscription",
          "uri": "https://sandboxapi.deere.com/platform/eventSubscriptions/ae4b499c-1111-2222-3333-d7498cd7d9dd"
        }
      ]
    }


    Authentication (OAuth 2)

    The John Deere Precision Tech API endpoints use OAuth 2.0 for authentication. OAuth is an open protocol, and these APIs currently only support the authorization code grant type for external applications.

    You can also see our sample code for examples of navigating our OAuth 2 authentication code flow.

    1. Create an Application on Developer.Deere.com

      You must be a validated John Deere user to create an application on developer.deere.com. If you do not have a John Deere username and password, you can create one using the Create an Account option on our digital tools home page here: https://www.deere.com/en/digital-tools/. You must be able to sign into the developer.deere.com to use the Create Application option in the My Applications section of the website. Please follow the steps of the Create Application workflow on the website before proceeding to the next steps.

      Once your application is created, the Security section of the application Details will provide you with the Application ID and Secret necessary for the next steps to sign your API token requests.

      A note on Redirect URIs (Callback URLs):

      During the creation of the application (or found after creation in the application Details/Security section) you will need to define one or any number of Redirect URIs (Callback URLs). These are required for the OAuth 2 authentication flow. If you do not have this when creating the application, there is an example given in that section when creating the application that you may use for now which is http://localhost:9090/callback

      If Redirect URIs are not added to your application properly or used in the authentication process in a different format than listed in the application details (for example encoded vs non-encoded), your users will experience a 400 Bad Redirect error during authentication.

    2. Call the OAuth 2 well-known URL

      With your application client or a web browser window, make a GET request to https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. This URL contains the authorization and token endpoints, as well as the available scopes mentioned in the steps below.

      {
          "issuer": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7",
          "authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize",
          "token_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token",
          "registration_endpoint": "https://signin.johndeere.com/oauth2/v1/clients",
          "jwks_uri": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/keys",
          "response_types_supported": [
              "code",
              "token",
              "id_token",
              "code id_token",
              "code token",
              "id_token token",
              "code id_token token"
          ],
          "response_modes_supported": [
              "query",
              "fragment",
              "form_post",
              "okta_post_message"
          ],
          "grant_types_supported": [
              "authorization_code",
              "implicit",
              "refresh_token",
              "password",
              "client_credentials",
              "urn:ietf:params:oauth:grant-type:device_code"
          ],
          "subject_types_supported": [
              "public"
          ],
          "scopes_supported": [
              "ag1",
              "ag2",
              "ag3",
              "eq1",
              "eq2",
              "files",
              "finance1",
              "finance2",
              "org1",
              "org2",
              "work1",
              "work2",
              "openid",
              "profile",
              "email",
              "address",
              "phone",
              "offline_access",
              "device_sso"
          ],
          "token_endpoint_auth_methods_supported": [
              "client_secret_basic",
              "client_secret_post",
              "client_secret_jwt",
              "private_key_jwt",
              "none"
          ],
          "claims_supported": [
              "ver",
              "jti",
              "iss",
              "aud",
              "iat",
              "exp",
              "cid",
              "uid",
              "scp",
              "sub"
          ],
          "code_challenge_methods_supported": [
              "S256"
          ],
          "introspection_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/introspect",
          "introspection_endpoint_auth_methods_supported": [
              "client_secret_basic",
              "client_secret_post",
              "client_secret_jwt",
              "private_key_jwt",
              "none"
          ],
          "revocation_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/revoke",
          "revocation_endpoint_auth_methods_supported": [
              "client_secret_basic",
              "client_secret_post",
              "client_secret_jwt",
              "private_key_jwt",
              "none"
          ],
          "end_session_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/logout",
          "request_parameter_supported": true,
          "request_object_signing_alg_values_supported": [
              "HS256",
              "HS384",
              "HS512",
              "RS256",
              "RS384",
              "RS512",
              "ES256",
              "ES384",
              "ES512"
          ],
          "device_authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/device/authorize",
          "dpop_signing_alg_values_supported": [
              "RS256",
              "RS384",
              "RS512",
              "ES256",
              "ES384",
              "ES512"
          ]
      }
    3. Acquire an authorization code

      The authorization code is obtained by using the authorization server as an intermediary between the client and resource owner. The client directs the resource owner to an authorization server, and once authorized the server redirects the resource owner back to the client with the authorization code. Along with the GET request to the authorization server URL, you will need to send a response type code parameter, along with OAuth scopes, client ID, state, and redirect URI.

      auth_code_1

      The authorization URL for the user to follow (in a web browser) should look like this:

      GET

      'https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize?response_type=code&scope={scopes}&client_id={clientId}&state={state}&redirect_uri={redirect_uri}

      A note on OAuth Scopes and Data Permissions:

      In the  Dev Docs API sections, the required OAuth scopes will be referenced for each method and endpoint. For the OAuth access token, you must request the required scopes for each endpoint your application will be using. DO NOT request all scopes available on our authorization server as not all are required for your application, and your users should be prompted to only accept scopes (permissions) necessary for the API calls you will be making.

      The OAuth scopes your application requests initially for a user access token will directly relate to the permissions granted when the user makes the organization connection to your application. Please refer to the scopes table below. These scopes directly relate to user, partner, and Connected Software Company data access permissions referenced in Team Manager.

      Note: If the user has less permissions in their own organization(s) or their partner organization(s) than the scopes you are requesting initially, only the user’s permission set will be assumed in the connection from the selected organization to your application. We will not grant more permissions to your application than the connecting user has.

      Once the connection from the user’s organization is made to your application, you may request a higher-level scope or new scopes for the user access token, however, the connection permissions must also be adjusted by the user in https://connections.deere.com for the requesting application. Before adjusting those permission levels in the Connections website, the user must have obtained those permissions in their own organization or must be shared by the partner organizations that are currently connected.

      Scope

      User/Connection Permission

      Description

      org1

      Organization Management Access Level 1

      View Staff, Operators, and Partners

      org2

      Organization Management Access Level 1

      Organization Management Access Level 2

      View Staff, Operators, and Partners

      Modify Staff, Operators, and Partners

      eq1

      Equipment Access Level 1

      RDA

      Setup & WDT

      View Equipment

      Remote Display Access

      Setup File Creator, Products, and Wireless Data Transfer

      eq2

      Equipment Access Level 1

      Equipment Access Level 2

      Equipment Access Level 3

      RDA

      Setup & WDT

      View Equipment

      Edit Equipment (also View Detailed Machine Measurements)

      Manage Equipment

      Remote Display Access

      Setup File Creator, Products, and Wireless Data Transfer

      ag1

      Locations Access Level 1

      View Locations (Clients, Farms, Fields and Associated Data)

      ag2

      Locations Access Level 1

      Locations Access Level 2

      View Locations (Clients, Farms, Fields and Associated Data)

      Analyze Production Data (Website Access Only)

      ag3

      Locations Access Level 1

      Locations Access Level 2

      Locations Access Level 3

      View Locations (Clients, Farms, Fields and Associated Data)

      Analyze Production Data (Website Access Only)

      Manage Locations & Production Data (Website and API Access)

      files

      Files API Access

      Equipment Access Level 3

      Setup & WDT

      Files API Access (ag3 scope also required for most file types)

      Manage Equipment

      Setup File Creator, Products, and Wireless Data Transfer

      finance1

      Financial Access Level 1

      View Financials

      finance2

      Financial Access Level 1

      Financial Access Level 2

      View Financials

      Manage Financials

      work1

      Work and Crop Plans Access Level 1

      View Work and Crop Plans

      work2

      Work and Crop Plans Access Level 1

      Work and Crop Plans Access Level 2

      View Work and Crop Plans

      View Work and Crop Plans

      offline_access

      API Authentication Only

      Request a Refresh Token

      To summarize the Authorization Code steps:

      1. The customer initiates a request for data from a client application, and the client sends an OAuth request to the authorization server with the proper headers.

      2. The customer is redirected to the John Deere sign-in page.

      3. The customer signs into John Deere, and the request is redirected back to the authorization server.

      4. The customer is then presented with the scope allowance screen. (During first token request, or with modified scopes)

      5. Scope acceptance is sent back to the OAuth server, and the customer is then redirected back to the client application with the authorization code.

    4. Acquire an Access Token

      Once the application has the authorization code, the client then requests an access token from the token server by sending a grant type authorization_code parameter, along with the authorization code, a redirect URI, and the client credentials. The authorization server authenticates the client and issues an access token and a refresh token (only if offline_access scope was requested in the previous step). The access token will expire after 12 hours after which it must be refreshed (see the last step).

      auth_code_1

      POST

      https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token

      Content-Type: application/x-www-form-urlencoded

      • grant_type=authorization_code

      • code={auth_code_from_authorize_call_response}

      • redirect_uri={redirect_uri}

      • client_id={client_id}

      • client_secret={client_secret}

    5. Post authorization redirect to enable organization access

      Once the client obtains a valid access token, there is an additional step required to enable organization data access for your client application. If this step is skipped, the client will receive a 403 Forbidden response when trying the access data for any organization to which the user has access

      auth_code_1
      1. Make a call to GET /organizations. If you see a ‘connections’ link in the response, your client has not granted access to that organization.

        Note: A user may have access to multiple organizations but may not enable access to all of them. A ‘connections’ may always be returned for an organization the user chooses not to allow your application access to.

        Example Response:

        [
          {
            "@type": "Organization",
            "name": "Spahn Ranch",
            "type": "customer",
            "member": true,
            "internal": false,
            "id": "283480",
            "links": [
              {
                "@type": "Link",
                "rel": "self",
                "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
              },
              {
                "@type": "Link",
                "rel": "connections",
                "uri": "https://connections.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/select-organizations"
              }
            ]
          }
        ]
      2. Redirect the user to Operations Center (in a web browser) using the URI provided in the ‘connections’ link. You can also provide a redirect_uri query parameter so the user will be redirected back to your application after the organization selection process is completed. The redirect_uri that is provided must match one of the Redirect URIs listed in your application profile. The redirect_uri must also be URL encoded (i.e. “https://example.client.com/callback” should be passed as “https%3A%2F%2Fexample.client.com%2Fcallback”).

        Example URI: https://connections.deere.com/connections/{clientId}/select-organizations?redirect_uri={redirectUri}

      3. The user selects the organization(s) to which your client can have access.

        auth_code_1

      4. Once the organization selection is complete, the user will be redirected back to your application based on the redirect_uri query parameter that was provided. If the redirect_uri query parameter is not provided or is invalid, then the user will remain on the Connections application in Operations Center.

        Additionally, the GET /organizations endpoint will no longer include the ‘connections’ link and instead will include a ‘manage_connections’ link. This will link into the management modal in Connections for the application in the organization. Having the ‘manage_connections’ link implies that a connection between an application and organization is fully established.

        Example Response:

        [
          {
            "@type": "Organization",
            "name": "Spahn Ranch",
            "type": "customer",
            "member": true,
            "internal": false,
            "id": "283480",
            "links": [
              {
                "@type": "Link",
                "rel": "self",
                "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
              },
              {
                "@type": "Link",
                "rel": "manage_connections",
                "uri": "https://connections-qual.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/connections-dialog?orgId=283480"
              }
            ]
          }
        ]
      5. Avoid getting into a redirect loop and only perform the connections redirect one time per user session. There are a few scenarios in Operations Center when a user either decides not to or is unable to complete the organization selection step. If your application does not have access to an organization after completing the connections redirect, we suggest that you inform the user that the connection was not completed and they may need to login to Operations Center to modify the Connection manually.

    6. Use the access token to call API resource

      Once the client obtains the valid access token and the user has enabled organization access for the client, they can use this token to call the appropriate resource server (API) to obtain the data needed.

      auth_code_1

      For API call structure, parameters, and headers, refer to the Dev Docs section.

      All your API calls should include an Authorization: Bearer {token} utilizing the obtained token.

    7. Setup Token Refresh Process

      The client application will need to pass a refresh token to the authorization (token) server to obtain a new access token before the access token expires (12 hours). For this you will pass through a refresh_token grant type parameter, along with the refresh_token to the token server.

      Even if the customer did not request a resource call, the client would need to initiate a periodic refresh of this token to keep it 'hot'. The refresh token will expire after 365 days if it is not used. If the refresh token expires, the customer will need to re-authenticate. As long as you continue to refresh the access token with this refresh token, it will remain active indefinitely (unless the customer removes all organization connections on https://connections.deere.com to your application).

      POST

      https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token

      Accept: application/json

      Content-Type: application/x-www-form-urlencoded

      • grant_type=refresh_token

      • refresh_token={refresh_token}

      • redirect_uri={redirect_uri}

      • scope={scopes}

      • client_id={client_id}

      • client_secret={client_secret}


    Using Postman to call the MyJohnDeere API (OAuth 2)

    Postman is a third-party API client, which you can use to test your John Deere API calls. You may use the Postman website or the desktop application for calling APIs while in Sandbox to see and follow REST API responses. Other API test clients may work for this as well. The below instructions will provide the initial setup steps to get Postman configured and obtain an OAuth 2 token.

    1. Download and install Postman on your computer (link above), or you may use the web version.

    2. Open Postman, click on Settings at the top, and in General settings turn off all of the Headers options.

    3. In the top nav section of the Postman client application, you can hit the + sign to add a new request to your console.

    4. In the Auth section of that new request tab, there is a dropdown to select the type of authorization you’ll be using. Select the OAuth2 option.

    5. The screen will change, and you will see Type is set as OAuth 2.0.

    6. Add auth data to should be set as Request Headers.

    7. Header Prefix should be set as Bearer.

    8. Within the Configure New Token section, you will need to add values to each of the fields or configure the options before selecting the Get New Access Token button (or it will error out).

      1. Add a Token Name (can be anything).

      2. Leave the Grant Type as Authorization Code.

      3. The Callback URL for redirecting the authorization code back to Postman is https://www.getpostman.com/oauth2/callback. The Callback URL can be set to anything in this example. Remember that if you will be using this Postman callback URL, it (and any other Callback URL you use) will need to be synced with your OAuth client. See step 2 in this document for help in syncing this Callback URL with your application.

      4. The Auth URL and Access Token URL can be found with opening a new Postman request window and doing a GET on this URL https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. No Auth is needed for this GET request. You can also open this URL in any internet browser window.

      5. For the Client ID and Client Secret Developer.Deere.com, login, and access your application profile in the "My Applications" section.

      6. In the Details window, under the Security section, you will find this information. What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

      7. The Scope box should be populated with only the scopes require for the API calls you are making (space delimited). The scopes required for your API calls can be found in the Dev Docs section of every API under each endpoint’s documentation.

      8. State is an opaque value to prevent cross-site forgery. Enter any unique string in this box (ex. 12345).

      9. For Client Authentication, this option should be set to Send client credentials in body for this example. (not selecting this option will result in an error)

    9. Once the steps above are complete, press the Get New Access Token button to proceed to the John Deere sign in page where a valid Operations Center user can sign in. If this is the first time the user is obtaining an API token for your application, they will be presented with the scopes acceptance screen, to which they must choose Allow Access (Don’t Allow will result in a token with no assigned scopes).

    10. In the Details window, the first two pieces of information that OAuth requires are found in the Application Details section (illustration below). What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

    11. Once the token is obtained and shown in the Postman screen, select the Use Token button to apply the token to your current API call. (you do not need to configure Authorization headers on the API call, as Postman will do this for you)

    12. The next step is to enter the URL of the API call and configure an Accept header. To test, please configure the API URL to be GET https://sandboxapi.deere.com/platform/organizations. In the Headers section, please configure an Accept header with a value of application/vnd.deere.axiom.v3+json. (you may leave the default Postman headers in the request, if applicable)

    13. Only once all the steps above are completed, can you hit the Send button in the API request to make the API call and receive a 200 OK response and response body.

    14. If you can’t complete this process or have any questions, please feel free to use the Support button in the top navigation of the page to contact us.



    eTags

    If your client will be making frequent/regular calls to some API to check for updates, you can use Deere's eTag implementation to limit the response to newly modified data. This feature is available for most APIs that return a list through MyJohnDeere API. To use this function:

    1. Include x-deere-signature as a request header.

    2. The response header will include a String Token. Send the request again with this String Token as the value for the x-deere-signature header

    3. If there are no changes to the list, then the resource will return 304 Not Modified. If there are changes to the list, it will return only the changed data, along with a new String Token. You must use this new String Token in your next request.

    4. While using eTags,pagination is skipped and the complete response, which include all the changes since last API call, is returned.

    String Tokens should be stored as string data types.

    eTags are retained by John Deere for forty-five days. If an eTag is no longer retained, the response will include the whole list. The same will occur if the signature used is not found.

    GET https://sandboxapi.deere.com/platform/organizations/1234/files

    Accept: application / vnd.deere.axiom.v3 + json
    x - deere - signature:
    Authorization: Bearer {token}
    200 OK

    pragma: no - cache
    date: Tue, 05 May 2015 19:37:58 GMT
    server: Apache - Coyote / 1.1
    x - deere - handling - server: ldxctc1
    x - deere - elapsed - ms: 225
    x - frame - options: SAMEORIGIN
    x - deere - signature: 520122365ebb4870a344784570d202c7
    content - language: en - US
    cache - control: no - cache, no-store, max-age=0
    transfer - encoding: chunked
    connection: Keep - Alive
    content - type: application / vnd.deere.axiom.v3 + json;charset=UTF-8
    keep - alive: timeout = 5, max=100
    expires: Thu, 01 Jan 1970 00:00:00 GMT
    GET https://sandboxapi.deere.com/platform/organizations/1234/files

    Accept: application / vnd.deere.axiom.v3 + json
    x - deere - signature: 520122365ebb4870a344784570d202c7
    Authorization: Bearer {token}
    304 Not Modified

    date: Tue, 05 May 2015 19:53:00 GMT
    cache - control: no - cache, no-store, max-age=0
    server: Apache - Coyote / 1.1
    connection: Keep - Alive
    keep - alive: timeout = 5, max=100
    expires: Thu, 01 Jan 1970 00:00:00 GMT

    Links

    Links is John Deere’s implementation of HATEOS. They are handy for discovering additional actions and endpoints. Please note that we do not show or hide returned links in a response based on client API access granted, but we do make efforts to return only those links that a user or application has access to based on data permissions. In summary, not all returned links will be accessible to your application as some APIs are not public facing and you may not have access to that endpoint, and not all returned links will allow every action (GET, PUT, POST, DELETE).

    Due to our large number of API's, the number of links can become overwhelming. For some base resources, links can account for the majority of the response payload. You can optionally disable links by specifying a showLinks=none query parameter on any API call. You can also request specific links. For example, showLinks=field,clients will only show links if they have a 'rel' value of 'fields', or 'clients'.

    Some Examples:

    "links": [
      {
        "rel": "self",
        "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de"
      },
      {
        "rel": "fields",
        "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de/fields"
      },
      {
        "rel": "clients",
        "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de/clients"
      },
      {
        "rel": "owningOrganization",
        "uri": "https://sandboxapi.deere.com/platform/organizations/1234"
      }
    ]

    How are these links helpful?

    • Links help to identify and discover additional API's and actions.

    • If you do not have access to a link, it will return a 403 response to your application.

    • Only those returned links that relate to the public APIs visible in https://developer.deere.com are accessible to external applications.


    Common Error Codes

    When a client application is making requests to John Deere APIs, it will encounter HTTP response errors that should be handled appropriately. Below you will find most of these errors and instructions on handling them.

    400 Bad Request

    HTTP Code: 400
    Response code: Bad Request

    This error means that either the POST/PUT body used in the request is incorrect, or if this error is seen in the OAuth 2 POST /token request, it means the refresh token is invalid. Before contacting API Support, please attempt to update the request body or get a valid token for the user. Please see the OAuth 2 documentation here.

    401 Unauthorized

    HTTP Code: 401
    Response code: Server Authorization Failed

    This error means that either the application does not have a license for the endpoint, or the user token is expired. Before contacting API Support, please attempt to get a valid token for the user, or use the refresh token process to get a new access token. Please see the OAuth 2 documentation here. Information about what APIs a client application can call by default are listed here, and all other APIs listed on the website are only accessible via a given license.

    403 Forbidden

    HTTP Code: 403
    Response code: Access Denied

    This error pertains to the user not having access to this resource. You should only request resources found while navigating the REST endpoints for the user. If the client calls for a resource the user does not have access to, the request will be denied. You can prevent this error by beginning your calls with /platform, and following the returned links to discover resource IDs available to the user (most are found under the /organizations link).

    HTTP Code: 403
    Response: The client does not have a proper access for this API

    This error relates to missing OAuth 2 scopes for the user token. Along with this error code, you will see the client ID, license needed, and read/write/delete scopes needed for that license to make the corresponding requests.

    HTTP Code: 403
    Response: Requested org is in a restricted state

    This error relates to our updates Orgs Terms & Conditions process. We have a guide for handling these requests here.

    404 Not Found

    HTTP Code: 404
    Response code: The requested resource was not found

    This error means that the resource ID requested is not valid. All resource IDs should be parsed from API responses immediately before requesting access to it. If IDs are stored for long periods of time, user access to that resource could change or be removed.

    429 Too Many Requests

    HTTP Code: 429
    Response code: HTTP_TOO_MANY_REQUESTS

    When the John Deere Servers are overwhelmed by requests, clients may receive a HTTP 429 response. That response may include a "Retry-After" header with a numeric value indicating the number of seconds the client should wait before trying again. When you receive a 429 response with that header, you have to wait at least for the specified time before retrying the request. If a customer is actively waiting for the result, you may need to return an error instead of waiting. If your application is fully asynchronous, always wait the Retry-After amount.

    503 Service Unavailable

    HTTP Code: 503
    Response code: : HTTP_SERVICE_UNAVAILABLE

    When John Deere Servers have a backend or server problem, they MAY return a corresponding Retry-After header along with a 503 response. If a 503 is returned without a Retry-After header then John Deere Servers cannot estimate a reasonable recovery time. Your application should enter an exponential back-off loop or return an error in this case. If a Retry-After header is returned, wait the number of seconds given and try again

    For all other possible status codes, please refer to this resource that is publicly available (provided by Wikipedia).


    Markdown

    Markdown is a simple and easy-to-use markup language with broad industry adoption. There are readily available tutorials and reference materials if you’d like an introduction.

    We do not support everything Markdown offers. The supported Markdown is listed below.

    Supported Markdown

    Map Layer Summary POST

    Markdown is supported on the text field of Map Layer Summaries. View Map Layer Summary POST documentation

    A *description* of a **Map Layer Summary** showing Markdown support.
    ***
    an ordered list:
    1. first item 
    2. second item 
    3. third item 
    ***
    an unordered list:
    - first item 
    - second item 
    - third item 
    More examples can be found at this [link](https://en.wikipedia.org/wiki/Markdown).
    markdown

    Asset Location POST

    AssetLocation has a property named measurementData, which supports Markdown on its name attribute. Please note that only links are supported here; no other Markdown will be rendered. View Asset Location POST documentation

    "measurementData" : [
        {
            "@type" : "BasicMeasurement",
            <span class="spanText">"name" : "[Leaf Wetness](https://www.example.com)",</span>
            "value" : "1.3",
            "unit" : "u1"
        }
    ]
    markdown2

    Required Customer Action (RCA) Events

    A Required Customer Action (RCA) event is a change or addition to the customer‘s organization flow that requires the user to take action before further account activity is allowed. This includes API calls on behalf of a customer.

    Example: User must accept new terms and conditions to verify their account information.

    What does it look like?

    • The client’s API calls will result in a 403 Forbidden response.

    • X-Deere-Warning header will indicate a more specific error message.

    • Example: "Requested Org is in a restricted state."

    • X-Deere-Terms-Location header will include a redirect URL where the user can take action.

    • Example: "https://teammanager.deere.com/organizations/{OrgId}/terms."

    • The response payload will indicate a short description of required user action.

    {
      "@type": "Errors",
      "errors": [
        {
          "@type": "Error",
          "guid": "19f7b283-d383-4990-9e14-1b3ee0f7b63d",
          "message": "Requested Org is in a restricted state."
        }
      ],
      "otherAttributes": {}
    }

    How should your app handle these RCAs?

    • If possible, navigate the user to the URL supplied in the 403 response X-Deere-Terms-Location header.

    • Implement a way to notify the customer that action is required. Supply a 403 response message and X-Deere-Terms-Location URL as instructions to resolve.

    Consider RCA Event handling as a best practice moving forward. Your application should take steps to handle these events now.