Skip to the main content
John Deere Logo

Develop with Deere


Operations Center - Machine Engine Hours

Click here for more information on how to get started.

Overview

Equipment is hardware used to do work such as a machine, implement, or device. Some equipment may require that it be paired with additional equipment to function. Examples include pickup truck, backhoe, planter, spray boom, modem, display, and GPS receiver. Currently supported equipment classes are machines and implements. A machine is typically a self-propelled piece of equipment and is often used as a source of power for an implement. Some machines may also require a paired implement or attachment to do work. Examples include a backhoe, forage harvester, and pickup truck. The Machines API endpoints allow access to information about each machine and the associated sensor data.

equipment tractor
equipment jd_mobile

An implement is a piece of equipment that must be paired with a machine to do work. An implement is not self-propelled, but it determines the type of work the paired machine will perform. Examples include a planter, disk, corn head, and spray boom. The Implements API endpoints allow access to information about each implement.

equipment field_finisher

EquipmentType vs EquipmentApexType vs Category

Type is term used to describe equipment with similar capabilities and characteristics such as backhoe, forage harvester, and pickup truck. EquipmentType is the recommended attribute for accessing type as it supports a broad range of equipment across many industries. EquipmentApexType only supports agriculture equipment and is required by GreenStarTM displays. Category is available for legacy reasons, should not be used, and may be deprecated in the future.

Implements with Modems

Currently, implements that have a modem paired are managed as a machine resource due to system constraints. Future changes will be made to remove this constraint and they will be managed as implements.

Related Resources

Machines

The Machines resource provides details about the machines of a specified organization or ID.

Implements

The Implements resource provides details about the implements of a specified organization or ID.

Alert

The alerts resource provides the information captured on the terminal when an alert occurred. For example, an alert is generated by a machine when the fuel pressure is low or there is a calibration fault in the fuel injector. Various alert types include machine, geofence, and maintenance.

Device State Reports

A device state report provides the call-in history for a specified date range. There are several attributes with each call-in about the state of the equipment, terminal, and connectivity.

Engine Hours

The engine hours resource provides the last reported number of hours that a machine's engine has recorded. Each response includes a timestamp for the report and the source of the report.

Hours of Operations

The Hours of Operation resource allows provides the durations for which the engine was on or off during a specified time range. The last known state of the machine's engine is also accessible.

Machine Breadcrumbs

The Machine Breadcrumbs resource provides location along with other sensor data for a specified time range.

Machine Location History

The Machine Location History resource provides latitude, longitude, and altitude for a specified time range.


Endpoints

Engine Hours

GET

/machines/{id}/engineHours
The engine hours service returns the last reported number of hours that a machine's engine has recorded.Each response includes a timestamp for the report and the source of the report.For each returned engine hours report, the response will include a link to the machine's information.
Please Note - This API does not support eTags.

OAuth Scope Required: eq1

Request URI

GET https://sandboxapi.deere.com/platform/machines/{id}/engineHours

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

ParameterTypeDescription & ExampleDefaultIn
id

Required

string

Machine ID.

Example: 5432

N/A

path

startDate

datetime

Start date.

Example: 2015-02-03T9:00:00.000Z

N/A

query

endDate

datetime

End date.

Example: 2015-02-03T10:42:24.282Z

N/A

query

lastKnown

boolean

If true, returned only the last known engine hour reading. startDate and endDate are ignored.

Example: true

false

query

FieldTypeDescription & Example
reading
measurementAsDouble
The number of hours the engine has been running.
Example: <valueAsDouble>523.5166666666667</valueAsDouble>
reportTime
datetime
Timestamp at which the report was created.
Example: 2010-10-04T14:35:05.000Z
source1
string
Device which collected the data.
Example: CI
200 OK
Content-Type: application/vnd.deere.axiom.v3+json
{
  "links": [
    {
      "rel": "self",
      "uri": "https://sandboxapi.deere.com/platform/machines/4321/engineHours?lastKnown=false"
    }
  ],
  "total": 2,
  "values": [
    {
      "reading": {
        "@type": "measurementAsDouble",
        "valueAsDouble": 1.1833333,
        "links": null,
        "unit": "Hours"
      },
      "reportTime": "2010-10-04T15:06:34.000Z",
      "source": "TM",
      "links": [
        {
          "rel": "machine",
          "uri": "https://sandboxapi.deere.com/platform/machines/4321"
        }
      ]
    },
    {
      "reading": {
        "@type": "measurementAsDouble",
        "valueAsDouble": 1.1833333,
        "links": null,
        "unit": "Hours"
      },
      "reportTime": "2010-10-04T15:04:33.000Z",
      "source": "TM",
      "links": [
        {
          "rel": "machine",
          "uri": "https://sandboxapi.deere.com/platform/machines/4321"
        }
      ]
    }
  ]
}


Additional Information

  1. Sources & Definitions

    TMMeter readings were received from an MTG or UTG.
    MIGMeter readings were received from an MIG (Machine Information Gateway).
    CIMeter readings were received from a GTT (GlobalTracs Terminal).

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.