Map Layers in the John Deere Operations Center help users understand their operation on a field by field basis. There are many different types of Map Layers that exist including but not limited to: management zones, drone and satellite imagery, topographic and soil maps. With these Map Layers, you can specify the legend ranges, provide summary information and let the user know that your tool created the Map Layer.

The intention of Map Layers is to provide growers with geospatially relevant information that is associated to a field and helps them monitor, diagnose and manage that field.

Webhooks

If you are planning to make frequent requests to the Map Layer API, please consider our Data Subscription Service. It can alert your application via webhook when new Map Layers are available.

Where does it appear?

Map layers appear in Field Analyzer's Operations Center web application, as well as the Operations Center mobile and Connect Mobile applications for Android and iOS.

Endpoints Overview

Posting to this API will allow you to add contextual information to summarize the overall field event. A Map Layer Summary does not contain images, rather it provides general information related to the Map Layers you associate to it. This endpoint supports Markdown.

Calling this API will get all of the Map Layer summaries that are available to download.

Posting to this API will allow you to add Map Layers. These Map Layers must be associated to a Map Layer Summary. For each Map Layer you can post an image, a legend associated to the image, and other contextual information specific to the image. A Map Layer represents one image. This endpoint supports Markdown.

Calling this API will get all the Map Layers that are available to view.

Calling this API by using the Map Layer ID will get an image of that Map Layer in a .png format, regardless of the original format of the uploaded Map Layer data.

This API reserves a spot within Operations Center to store the image data for the Map Layer.

Calling this API will allow you to get the original image that was given.

This API will put the image in the Map Layer file resource which was created in the previous step.

Markdown Support

Map Layers Summary supports a subset of Markdown's markup features. Find out more about our support for Markdown and links to helpful Markdown resources here.

This guide goes over the steps to contributing your first Map Layer to Operation Center.

1. CREATE A MAP LAYER SUMMARY

1.1 Use the POST Create a Map Layer Summary endpoint to create a Map Layer Summary. This will generate the links that are required to complete the subsequent steps.

{
  "links": [
    {
      "rel": "owningOrganization",
      "uri": "https://sandboxapi.deere.com/platform/organizations/ORG_ID"
    },
    {
      "rel": "contributionDefinition",
      "uri": "https://sandboxapi.deere.com/platform/contributionDefinitions/DEFINITION_GUID"
    }
  ],
  "title": "some title",
  "text": "description of the Map Layers",
  "metadata": [
    {
      "name": "The Name",
      "value": "The Value"
    }
  ],
  "dateCreated": "2016-01-02T16:14:23.421Z"
}

1.2 Use the Location provided in the Map Layer Summary response header to for the subsequent steps.

HTTP/1.1 201 Created
Location: https://sandboxapi.deere.com/platform/mapLayerSummaries/mapLayerSummary_ID

2. CREATE A MAP LAYER

2.1 Use the POST Create a Map Layer endpoint to create a Map Layer. Include the location link in your response header.

{
  "links": [
    {
      "rel": "owningOrganization",
      "uri": "https://sandboxapi.deere.com/platform/organizations/ORG_ID"
    }
  ],
  "title": "The title on the Map Layer",
  "text": "Description of the Map Layer",
  "metadata": [
    {
      "name": "The Name",
      "value": "The Value"
    }
  ],
  "extent": {
    "minimumLatitude": 41.76073,
    "maximumLatitude": 41.771366,
    "minimumLongitude": -93.488106,
    "maximumLongitude": -93.4837
  },
  "legends": {
    "unitId": "seeds1ha-1",
    "ranges": [
      {
        "label": "Some Label",
        "minimum": 87300,
        "maximum": 87300,
        "hexColor": "#0BA74A",
        "percent": 0.13
      }
    ]
  }
}

HTTP/1.1 201 Created
Location : https://sandboxapi.deere.com/platform/mapLayers/map_layer_id_location

3. CREATE A FILE RESOURCE

3.1 Use the POST Create a File Resource endpoint to create a File Resource. You will request a location to upload the file resouces to.

{
  "links": [
    {
      "rel": "owningOrganization",
      "uri": "https://sandboxapi.deere.com/platform/organizations/ORG_ID"
    }
  ],
  "mimeType": "image/png",
  "metadata": [
    {
      "name": "filename",
      "value": "filename.png"
    }
  ]
}

HTTP/1.1 201 Created
Response header : https://sandboxapi.deere.com/platform/fileResources/file_resource_id_location

4. UPLOAD A FILE RESOURCE

4.1 Use the PUT Upload a File Resource endpoint to upload a File Resource. Associate the File Resource to a Map Layers. You can upload a .png image or .zip shapefile to this location as shown below. Check the status of the upload by requesting the File Resource's targetResource Link.

PUT https://sandboxapi.deere.com/platform/fileResources/File_Resource_ID

HTTP/1.1 204 Modified

Additional Information

Models

Metadata Details

1. Map Layer Types:

Metadata Details

Additional Information

Models

Metadata Details

Extent Details

Legend Details

Range Details

1. Status:

   VALID; INVALID; QUEUED; NO_FILE_RESOURCE;

Additional Information

Models

Metadata Details

1. MIME Types:

Metadata Details

Map Layer events are triggered when the Map Layer status changes. When a File Resource is uploaded for the Map Layer, the initial status is set to QUEUED. The status will be updated once the image is processed.

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

Map Layer event 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.

Map Layer Event Statuses

Map Layer Event Filters

{
  "clientKey": "johndeere-123456789",
  "eventTypeId": "contributedMapLayer",
  "targetResource": "https://sandboxapi.deere.com/platform/mapLayers/c303004d-beb8-471d-b144-c44bb5318e55",
  "metadata": [
    {
      "key": "orgId",
      "value": "123456"
    },
    {
      "key": "id",
      "value": "c303004d-beb8-471d-b144-c44bb5318e55"
    },
    {
      "key": "fieldId",
      "value": "5513840f-1a8d-4dd4-aff2-3020d308d154"
    },
    {
      "key": "summaryId",
      "value": "335c06b6-f645-42fd-99f6-74c84f633d46"
    },
    {
      "key": "type",
      "value": "PRESCRIPTION"
    },
    {
      "key": "status",
      "value": "VALID"
    },
    {
      "key": "action",
      "value": "CREATED"
    }
  ],
  "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"
    }
  ]
}

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.

   Sample Response [JSON]

   {
       "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.

   

   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).

   

   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

   

   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.

      

   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.

   

   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}

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.

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.

6. 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.

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

8. 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).

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.

10. 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)

11. 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)

12. 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.

13. 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.

When a Precision Tech API returns a collection of objects, it wraps the response in a CollectionPage object. This wrapper object has three properties:

• Integer total: An integer value that represents the number of available values.

• List<Link> links: A collection of links. If the response was paginated, this will contain 'nextPage' and 'previousPage' links.

• List<T> values: The actual object values returned by the API.

By default, collections are paginated. Each page of data contains 10 values. The response will contain nextPage and previousPage links, which can be followed to view the entire response. The last page of data will not have a nextPage link. Please note that not all responses from each API are paginated or accept the page size parameters below.

Page Item Limit

You can control the page size by adding an itemLimit parameter to your request url. The value for this parameter should be in multiples of 10 up to 100 (max limit). You can set this by appending ?itemLimit=100 to the end of the request url.

Page Offset

You can control what page the response begins with by adding a pageOffset parameter to your request url. You can set this by appending ?pageOffset=0 to the end of the request url. The value used for this parameter should be in line with the item limit you are requesting. By default the page size is 10, so when not using the itemLimit parameter, this value should be in multiples of 10 (10,20,30, etc.). If you are using an itemLimit of 100, the value should be in multiples of 100 (100,200,300, etc.)

Disabling Paging

If you prefer, you can disable pagination entirely. The API response will still wrap responses in a CollectionPage object, but you would receive the entire collection at once. To disable pagination, add a request header named x-deere-no-paging and set its value to true. If you will be repeatedly polling an endpoint for updated data, consider using eTags instead of disabling pagination.

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.

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 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

• List- supports ordered list and unordered list (bullets will not render on UI)

• Paragraph

• Strong

• Italic

• Line Break

• Horizontal Rule

• Links

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).

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