Introduction
Introduction

Overview

The Trimble Connected Farm is an independent, brand agnostic platform that connects infield devices and operational workflows, to more efficiently execute crop production plans and collect the most robust dataset in the industry.<br><br>In addition to delivering customer value around the Operational Workflow, the Trimble Ag Platform connects and enables compatibility with non-Trimble platforms and applications that deliver additional value to the farmer. Enabling farmers to complete workflows that involve solutions from multiple technology providers is critical to our customers, especially in cases where 3rd party applications address unique regional farming practices, are preferred by local advisor networks, offer enhanced local technology support or address local regulatory policies.<br><br>Trimble Ag APIs are REST APIs that enable this value delivery.

Use Cases

The Trimble Ag Software API allows users to accomplish a variety of tasks:<br>
  • Align Client/Farm/Field, Boundaries, Guidance Lines, and Landmarks between  3rd party applications and Trimble Ag Software/Trimble Displays 
  • Send Prescriptions from 3rd party applications to Trimble Ag Software/Trimble Displays 
  • Send as-applied data from Trimble Displays to 3rd party applications
  • Many others…

Concepts

  • Data flow within the Trimble Ag Platform - Data from 3rd party applications is sent to Trimble Ag Software and may then be automatically or manually sent to connected Trimble Displays. Data from connected Trimble Displays will be sent to Trimble Ag Software and then may be sent to 3rd party applications.
  • In Trimble Ag Software, Organizations are the basic structure that segregates user data. An organization typically represents the business entity that manages the resources (fields, equipment, personnel, materials) used in a farming operation. Each Trimble Ag Software user account will have access to one or more organizations.
  • Trimble Displays supported for most Trimble Ag Platform data exchange include TMX-2050, GFX-750, GFX-350, XCN-2050, XCN-1050, and XCN-750

Dependencies

  • To exchange data between a connected 3rd party application and a Trimble Ag Software Organization the Organization must have a Trimble Ag Software base license (e.g. Farmer Core). 
  • To connect to a Trimble Ag Software Organization a Trimble Display must have a Trimble Ag Software display license (e.g. Display Connection).
Getting Started

Setup

Step-by-step instructions on how to get started with this API.
  • Create Application
    • Send an email to ag_api@trimble.com requesting API credentials for your application. Your email should include your application name and a brief description of what users do in your application. As well, you should specify one of the Grant Type options below. Trimble Ag can assist if you have questions about Grant Types.
    • Grant Type Options - your application will be set up using one of the two options below. This decision depends on who will be accessing the API through your application.
      • Authorization Code Grant
        • Operation - allows confidential and public clients to exchange an authorization code for an access token via a trusted back channel.
        • Use Case - this configuration option utilizes user-level authorization. This is applicable when multiple users (i.e. your customers) log into the 3rd party application connected via API (your application) and every user should have access to the different organizations that they individually have access to through different Trimble Ag Software logins.
      • Client Credentials Grant
        • Operation - allows clients to obtain an access token outside of the context of a user with a secured environments.
        • Use Case - this configuration option utilizes application-level authorization. This is applicable when only a single entity (i.e. your business) logs into the 3rd party application connected via API (your application) and every user should have access to the same authorized organizations in the Trimble Ag Software.
  • For access to a Trimble Ag demo Org and demo data please send a request to ag_api@trimble.com.

Connecting to Trimble Ag APIs

  • Authenticate your application to gain an access token. Note that your process will differ depending on whether your application is setup to use the Authorization Code Grant or Client Credentials Grant  (see the instructions below).
  • Users authorize access to data in Organizations through an OAuth process you initiate (see the instructions below).
  • Connect to endpoints for accessing authorized organizations and exchanging data (see API documentation).

Common Workflows

See below for API workflows that cover some common use cases. Note there are additional APIs available as part of these workflows that can provide information such as other related data or the status of a process. Furthermore, there are many other use cases supported by the Trimble Ag APIs.
  • Send a prescription to a Trimble display
    • Devices GET to see what Trimble Displays are available in an Org
    • Prescriptions POST to create a new prescription record
    • Prescriptions PATCH to append a prescription shapefile to the prescription record
  • Send fields, boundaries, and guidance lines to Trimble Ag Software and sync them to a Trimble Display by enabling AutoSync from the web
    • Fields POST to create a new field
    • Boundaries POST to create a new boundary
    • Guidance Line POST to create a new guidance line
  • Access as-applied from a Trimble display
    • Equipment Activity GET to get a list of Trimble tasks
    • Layers GET to get list of layers for a Trimble task
    • Layers Samples GET to get the sensor value for each location in a layer
Authorization Code Grant

Overview and When to Use

Overview-and-When-to-Use-1
Nearly all API partners are set up to use the Authorization Code Grant for Authentication. Unless you are informed otherwise, this is how your API Connection will be set up and you should use these authentication and authorization instructions (the Client Credentials Grant will not work for your API setup).<br><br>This configuration option utilizes user-level authorization. This authentication applies when multiple users log into the 3rd party application connected via API (your application) and every user should have access to the different organizations that they individually have access to through different Trimble Ag Software logins.<br><br><strong>Definition of Variables</strong>
VariablesDefinition
TID - Trimble Identity {{Env Auth root}}Production authentication - https://id.trimble.com
Trimble Ag API {{Env Data root}}Production data - https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0
{{yourAppName}}The application name provided by Trimble that is assigned to your application
{{yourClientId}}The GUID (unique identifier) provided by Trimble that is assigned to your application
{{authenticationCallbackURL}}The URL that users should be returned to from OAuth login at TID (must be an exact match to a URL in the list of valid authenticationCallback URLs you provide)
{{logoutURL}}The URL that users should be returned to after logging out of the application www.trimbleag.com (must be an exact match to a URL in the list of valid logout URLs you provide)
{{authorizationRedirectURL}}The URL that users should be redirected to after authorizing Organizations for data access at www.trimbleag.com (must be an exact match to a URL in the list of valid authorizationRedirectURLs you provide)
{{authProvider}}The returned value of the authentication provider that was accessed
{{TIDAuthCode}}The code generated by the TID system that you can exchange for an access, refresh and ID token from TID.
This code may only be used once and expires after 10 minutes.
{{accessToken}}The JWT token that is used to access data endpoints.
The access token has a 1 hour expiration.
{{idToken}}The JWT token contains additional information about the user who was authenticated in TID.
{{refreshToken}}The token has a 7-day expiration that can be exchanged for a new access token.

Authentication

Authentication
In order for your application to access data within an Organization, the Trimble user must approve your application in an Authorization step, but in order to discover if a user has authorized your application you need to go through an OAuth process to gain access to the data that is scoped to that user.<br><br>These flow diagrams illustrate how you can use the APIs to allow third-party software to send data to and receive data from the Connected Farm software.

Authorization/Authentication API data flow diagram

User Authorization Code

Step 1

The first step of the OAuth process is to send the user to log into Trimble’s identity management system in order to obtain an authorization code. This code will be valid for 10 minutes.

URL

Use this GET call to redirect the user to TID.

{{Env Auth root}}/oauth/authorize?scope={{yourAppName}} openid&response_type=code&redirect_uri={{authenticationCallbackUrl}}&client_id={{yourClientId}}

Step 2

After the user logs into TID they will be returned to your application via the following URL:

{{authenticationCallbackUrl}}?code={{TIDAuthCode}}&identity_provider={{authProvider}}

Authentication Token API

This API can be used for authentication from a third party client application or a web service to obtain an access token to use for subsequent method calls as described in the Common authentication token. This API also returns an ID for identification and a refresh token for re-authentication after the access token expires. <strong>The authentication token is valid for 1 hour and the refresh token is valid for 9 days. The refresh token is a single-use token that becomes invalid after use.</strong>

URL

This URL should be used to obtain an authentication token and the refresh token.

POST {{Env Auth root}}/oauth/token

Input Example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret which you would replace with your own values.

POST: https://id.trimble.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TXlQcm….
grant_type=authorization_code&code=sd3ds…&client_id=e3rdfF…&redirect_uri=https://mydomain.com/oauthreturn

The header and request body values are defined in the following tables.

Header Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields in the header:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Request Body Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication typeauthorization_codeY
codeThe authorization code returned from the OAuth process{{TIDAuthCode}}Y
client_idThe GUID provided to you{{yourClientId}}Y
redirect_uriAn exact match to one of the URLs provided to Trimble by you to return to your app after logging in.{{authenticationCallbackUrl}}Y

Response

This service acknowledges with an HTTP code 200 for success (OK) and all other HTTP codes for failure. 

In addition to the 200 HTTP code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”
expires_inTime in seconds until expiration.Returns “3600”.  
Each call to the endpoint results in a new token lasting 60 minutes.
Please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorThe Error title of the error being shown. 
error_descriptionError description to help understand the error provided. 

Response example (tokens truncated)

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1….",
    "refresh_token": "NAwdjwEX6vj….",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhb….",
}

Logout

(Optional): If you wish to log the user out of TID and return them to your application utilize the following URL:

URL

{{Env Auth root}}/oauth/logout?id_token_hint={{IdToken}}
&post_logout_redirect_uri={{yourLogoutUrl}}

Refresh Authentication Token API

URL

Use the following URL to obtain a refresh token once the authentication token expires.

POST  {{Env Auth root}}/oauth/token

Input example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret are replaced with your own values.

Header Values

The web service expects you to post a URL- Form- Encoded string in the body, containing the following header values:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content type.application/x-www-form-urlencodedY

Body Values

The web service expects you to post a URL-Form-Encoded string in the body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication type.refresh_tokenY
refresh_tokenThe refresh code returned from the Authentication Token [link inserted here] endpoint.{{RefreshToken}}Y
tenantDomain*Required valuetrimble.comY

Response

The service sends an acknowledgement with HTTP code 200 for success (OK) and any other HTTP code for failure.

In addition to the HTTP 200 code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that needs to be used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token must be returned.Will always be “bearer”
expires_inTime in seconds until expiration.Will return 3600.  Each call to the endpoint will result in a new token lasting 60 minutes, please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorError title 
error_descriptionError description to help understand the error provided. 

Response example

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1....",
    "refresh_token": "NAwdjwEX6vj....",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhb....", 
}

Common Authentication Token

All REST calls made available by the Connected Farm data center will require proper authentication. To achieve this, a Trimble Identity access token must be passed to validate that the caller has permission. All subsequent calls are validated by Trimble’s TID service and the access token should be prefixed with Bearer in the Authorization header. <br>The following is an example of the parameters to help illustrate the definition:
GET:
https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/2.0/Organizations/
Authorization: Bearer 
eyJ0eXAiOiJK....
Client Credentials Grant

Overview and When to Use

Overview-and-When-to-Use-2
This configuration only applies to specific API partners. You would be informed if you are set up to use the Client Credentials Grant. If you are not setup to use the Client Credentials Grant process you can skip this section.<br><br>This configuration option utilizes application-level authorization.  This authentication and authorization applies when only a single entity logs into the 3rd party application connected via API (your application) and every user should have access to the same authorized organizations in the Trimble Ag Software.

Definition of variables

VariablesDefinition
TID - Trimble Identity {{Env Auth root}}Production authentication - https://id.trimble.com
{{yourAppName}}The application name provided by Trimble that is assigned to your application.
{{yourClientId}}The GUID (unique identifier) provided by Trimble that is assigned to your application.
{{accessToken}}The JWT token that is used to access data endpoints.
The access token has a 1 hour expiration.

Authentication

alternate-authentication
In order for your application to access data within an Organization, the Trimble user must approve your application in an Authorization step, but in order to discover if a user has authorized your application you need to go through an OAuth process to gain access to the data that is scoped to that user.<br> <br>These flow diagrams illustrate how you can use the APIs to allow third-party software to send data to and receive data from the Connected Farm software.

Authorization / authentication API data flow diagram:

Authentication Token API

Authentication-Token-API-2
This API can be used for authentication from a third party client application or a web service to obtain an access token to use for subsequent method calls as described in the Common authentication token. This API also returns an ID for identification and a refresh token for re-authentication after the access token expires. <strong>The authentication token is valid for 1 hour and the refresh token is valid for 9 days. The refresh token is a single-use token that becomes invalid after use.</strong>

URL

This URL should be used to obtain an authentication token and the refresh token.

POST {{Env Auth root}}/oauth/token

Input Example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret which you would replace with your own values.

POST: https://id.trimble.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TXlQcm....
grant_type=client_credentials&scope=MyAppName

The header and request body values are defined in the following tables.

Header Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields in the header:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Parameter Values

The web service expects the following fields as query string parameters:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication typeclient_credentialsY
scopeThe name of your application{{yourAppName}}Y

Response

This service acknowledges with an HTTP code 200 for success (OK) and all other HTTP codes for failure.

In addition to the 200 HTTP code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”.
expires_inTime in seconds until expiration.Returns “3600”.  
Each call to the endpoint results in a new token lasting 60 minutes.
Please cache and reuse the token for calls within 60 minutes of the last authentication.
errorError title 
error_descriptionError description to help understand the error provided. 

Response example (tokens truncated)

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600
    "access_token": "eyJ0eXAiOiJKV1....",  
}
Organizations

Authorization of Organizations

<strong>In order to gain access to an Organization’s data, a user of that Organization must authorize your application to do so. This is accomplished through an OAuth process, where the user will be directed to a Trimble Ag website. Here, the user is required to sign in, approve your application and select which Organizations to approve for access.</strong>

Step 1

From your application, or via another process of your choice, redirect the user that would be approving your application to the following URL:

URL for Authorization Code Grant

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}&redirectionUrl={{authorizationRedirectUrl}}

URL for Client Credentials Grant

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}

Step 2

Users who are not currently logged in are directed to Trimble’s login service for www.trimbleag.com.

Step 3

The logged-in user is presented with an Authorization page that uses the logo provided to Trimble as part of the Authorization setup.

Step 4

Once your application is authorized for that user, the user will be presented with a list of Organizations to which they have access and can select the Organizations to which they want your application to have access as well.  Selecting a Trimble Ag Advisor Organization provides access to all the child Organizations that the logged- in user has access to for that Advisor Organization.

Step 5

This step only applicable for Authorization Code Grant

Once the user hits the save button after selecting the Organizations, they will be redirected to the authorization redirect URL that you provided during setup of your application with Trimble.

Step 6

Once the user has authorized you to access their data, you can expect the following:

Below applies to Authorization Code Grant
  • The OrgIds authorized for that user will appear in the GET config/organizations result set.
  • The returned results will be scoped to the token for that user.  It is your responsibility to use the proper user token for matching the user in your system and use the refresh token before it expires.
  • If the refresh token expires before you use it to acquire a new token, your system will need to acquire a new User Authorization Code to exchange for a new access and refresh token.
  • User Authorization Code - Valid for 10 mins, Access Token - Valid for 1 hour, Refresh Token - Valid for 9 days.
Below applies to Client Credentials Grant
  • The OrgIds authorized for that user will appear in the GET config/organizations result set.
  • The returned results will be scoped to the list of orgs authorized to be accessed by your application.
  • When the access token expires you will need to call the Authentication Token endpoint again to obtain a new access_code to use with the APIs.
  • Access Token - Valid for 1 hour.

For each user that approves usage of their data, it is your responsibility to ensure that only the authorized user has access to the authorized data in your application.

Organizations

Use this method from a third-party client application or web service to obtain a list of approved organizations for the access token.  For each user that approves Organization data it is your responsibility to ensure that only that authorized user has access to that data in your application.
Clients, Farms, Fields

Overview

clients-farms-fields-overview
The Client, Farm, Field APIs enable users to create Clients, Farms, and Fields in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Clients, Farms, and Fields from Trimble Ag Software or Trimble Displays can also be sent back to the other applications.

Clients

Clients are the highest level of the organization hierarchy for a Field. Clients contain Farms.

Farms

Farms are the middle level of the organization hierarchy for a Field. Farms are contained within Clients, and contain Fields.

Fields

Fields define a piece of ground and are used to organize the work that happens on that ground. Fields are contained within Farms. Fields contain Boundaries, Field Extents, Guidance Lines, Landmarks, Crop Seasons, Prescriptions, Files, and Tasks.
Field Resources

Overview

resources-overview
The Field Resources APIs enable users to create Field Extents, Boundaries, Guidance Lines, and Landmarks in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Field Extents, Boundaries, Guidance Lines, and Landmarks from Trimble Ag Software or Trimble Displays can also be sent to other applications.

FieldExtents

FieldExtents
A Field Extent is a property of a field and is primarily used for record-keeping. On a Trimble display Field Extents can be viewed, but not edited, using the Field Manager. In the Trimble Ag web and mobile tools Field Extents can be viewed and edited from the Fields List. As Field Extents are properties of Fields, they share the same ID as the Field.<br>

Boundaries

Boundaries are the functional extent of a field and are used for operational workflows. On a Trimble display Boundaries can be viewed and edited using the Field Manager. On the web Boundaries are viewed from Landmarks page within a Crop Zone.

GuidanceLines

GuidanceLines
Guidance Line are a navigation aid used by precision ag displays to define where to drive in a field. Guidance Lines are contained within Fields.

Landmarks

Landmarks are features that are points of interest within a Field. Landmarks are contained within Fields.
Crop Zones

Overview

cropZones-overview
Crop Zones are used to organize information about the crop being grown in a field in a particular year. Crop Zones include information about the crop, boundary for that crop, and what tasks occurred in relation to that crop in a particular growing season.

MasterCrops

Master Crops represent crops that can assigned to be grown in a Crop Zone.

CropSeasons

Crop Seasons represent the combination of a year and a Master Crop being grown in a field within a particular year.

CropZones

Crop Zones represent a Crop Season for a Field. Crop Zones are contained within Fields. Equipment Activities and Crop Zone Activities are contained within Crop Zones.

CropZoneExtents

A Crop Zone Extent is a property of a Crop Zone and represents the boundary for a Crop Zone. When created in the Trimble Ag UI, Crop Zone Extents will initially be an exact match of the Field Extent and can then be modified by the user. As Crop Zone Extents are properties of Crop Zones, they share the same ID as the Crop Zone.
Vehicles, Implements, Devices

Overview

vehicles-implements-devices-overview
The Vehicles, Implements, Devices APIs are used to create and capture information about equipment that is used to complete work. This information may be associated with jobs that are completed (as available from the EquipmentActivity or CropZoneActivity APIs) in a Crop Zone. Further, The Devices APIs can enable sending recommendations directly to the devices that will execute those recommendations in the field (using the Prescriptions APIs).

Devices

Devices represent displays that are used for in-field operational workflows and are contained within Organizations.

Vehicles

Vehicles represent machinery that is used to complete fieldwork. Vehicles have a Manufacturer, Equipment Type, and may optionally be included in Equipment Groups. Devices may be assigned to Vehicles.

VehicleTypes

Vehicle Types are assigned to Vehicles and are used to account for the general vehicle function. Example Vehicle Types include “Combine”, “Spayer”, “Tractor-4WD” and “Generic”.

EquipmentGroup

Equipment Groups are an optional classification that can be created and apply to Vehicles. These assignments could be based on Vehicles that serve the same function, are in the same region, or for any other reason the user chooses.

EquipmentManufacturers

Equipment Manufacturers are applied to Vehicles and represent the maker of the Vehicle.

Implement

An Implement represents an equipment that is used to execute work in the field. Implements may optionally include Operation Type and/or Equipment Group.
Contacts

Overview

contacts-overview
The Contacts APIs enable users to create Contacts and Operator groups in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Contacts and Operator Groups from Trimble Ag Software can also be sent to other applications.

Contacts

Contacts represent people that are associated with the running of an operation. Contact information can include detail such as contact detail,  whether the contact is an Equipment Operator, and whether the person has Trimble Display access when Operator Sign-in is on for an Org.

OperatorGroups

Operator Groups are an optional classification that can be created and apply to Contacts. These assignments could be based on Contacts that perform the same function, are in the same region, or for any other reason the users choose.
Prescriptions

Overview

prescriptions-overview
The Prescriptions APIs allow users to send prescriptions from partner applications to Trimble Ag Software and, if desired, directly to a field device.

Prescriptions

Prescriptions represent a recommendation file. The zip file should contain at least one set of .shp, .dbf, and .shx files with the polygons and rates. The projection for the prescription shapefiles should be GCS WGS84. The user does not need to include a .prj file in the zip file. The polygons should only have one exterior cycle and may contain one or more interior cycles (holes). The .dbf should have at least one numeric column of data that contains the corresponding rates for each polygon.  Multiple sets of shapefiles may be included in a single .zip file, but all the .dbf files must have the same rate column name for the display to recognize the rate column.
Management Zones

Overview

management-zone-overview
The Management Zone APIs are used for managing spatial zones. These zones may be used as part of field management practices such as the creation and application of a variable rate prescription.

ManagementZone

ManagementZoneDetail

Tasks (As-Applied)

Overview

tasks-overview
The Tasks APIs enable users to forward job data from devices and Trimble Ag Software to 3rd parties.

EquipmentActivity

The Equipment Activity endpoints provide detailed information on tasks (i.e. in-field jobs) created from precision ag displays. This includes tasks from Trimble displays and other equipment manufacturer display data that has been imported to a Trimble account. <br><br><strong>The as-applied or sensor data associated with an Equipment Activity task is available from the Layers endpoints.</strong><br><br>Within the optional Equipment Activity query parameters, the startDate and endDate parameters are based on the ending time for a task. Therefore, if the task end UTC is equal to or past the query parameter startDate UTC, we return the task. Likewise, if the task end UTC is equal to or before the query filter EndDate UTC, we return the task.<br>

Layers

The Layers endpoints provide access to the layer and sensor data associated with Equipment Activity tasks. Descriptions of the Layers endpoints are below:<br><br>- Gets a list of Layers for the EquipmentActivityId - returns a list of all layers for an Equipment Activity Task<br>- Get a Layer by Id - returns details about a single layer for an Equipment Activity Task<br>- Get list of sensors on a layer - returns a list of sensors for a single layer. Sensors could include values such as target rate, applied rate, or speed.<br>- Get list of samples on a layer - returns geometry in GeoJSON format with associated sensor values for a single layer.

OperationType

Operation Types represent the different types of operations for the Equipment Activities and Crop Zone Activities. These are generic for all Orgs. Operation examples would be “Spreading” or Spraying”.

OperationSubtype

Operation Subtypes represent the different types of operations subtypes for the Equipment Activities and Crop Zone Activities. These would be customized by individual users. Examples could be “First Spraying” or “Second Spraying”.

CropZoneActivity

Crop Zone Activities represent manual field records that were created in the Trimble mobile or online application. Crop Zone Activities do not have machine coverage or as-applied data.

Files

Task files from field devices that are stored in the Trimble Ag Software are available to be downloaded through the Files API. Files will be zip files with either an AgGPS (FMX/FMX+) or AgData (Precision-IQ) folder of files. Once downloaded these files may need to be combined and will need to be parsed using the Trimble plugins for the AgGateway ADAPT framework. More information about ADAPT can be found at adaptframework.org.<br><br>Note that the Files endpoint provides the same data that is available from the EquipmentActivity endpoints, but in an unprocessed and encrypted format.<br><br><strong>Retrieve list of files from devices</strong><br><br>Use this resource to obtain a list of files that are associated with a given organization. Each file returned will contain metadata about the file, and an Id plus a URL that can be used to directly download the file.

Download specific files

Use the temporaryAccessUri returned the FileManagement/v3/Files API response to download individual files.

Materials

Overview

materials-overview
The Materials APIs allow users to create, export, and track different inputs that are associated with applications in a Crop Zone.

 

Materials

Materials represent different inputs that are applied to Crop Zones. Materials type examples include chemical, fertilizer, and seed. Material details could include information such as form, rate, and manufacturer.
Inventory

Overview

inventory-overview
The Inventory APIs are used for record-keeping purposes and enable users to track current material inventory and create new material inventory.

Purchase

Purchases are used to track material purchases and will impact materials inventory.

Balance

Balances represent current material inventory for a specific crop year.
Units

Overview

units-overview
The Units APIs provide detailed information about the units that are returned with different calls.

Units

The Units APIs return Units for different data types such as Materials, Contracts, or Layer Sensors.
ADAPT

Overview

adapt-introduction
ADAPT – the Agricultural Data Application Programming Toolkit – is a framework for converting<br>agronomic data between various formats. This toolkit is the result of a collaborative industry effort and includes multiple pieces, including both an open source core framework and a set of plugins. The core framework consists of a common data model, a plugin manager, and a set of utilities for managing units of measure and data representations. The plugins are assemblies which convert data between that common data model and various other data formats.<br>

AdaptToken

The ADAPT Data Model

The entire functionality of ADAPT is centered on converting data to and from a common Application<br>Data Model. As an application developer, this means you only need to integrate with one data model.<br>The Application Data Model is contained in the AgGateway.ADAPT.ApplicationDataModel.dll assembly.<br>

Plugin Manager

The plugin manager is the main entry point when using ADAPT as an SDK. It detects and identifies available plugins, determines which plugin is appropriate for reading a given data source, and marshals plugins and their dependencies as needed. It is contained in the AgGateway.ADAPT.PluginManager.dll assembly.

Representation

The representation assembly, AgGateway.ADAPT.Representation.dll, includes utility classes to help work with units of measure and data representations (similar in concept to ISO DDI’s).

Plugins

Each plugin is responsible for translating data between the Application Data Model and a specific external data format. The Trimble plugin supports both the AgGPS and AgData file formats.

Getting Started

Referencing ADAPT

You can reference ADAPT using NuGet by referencing the package at https://www.nuget.org/packages/AgGatewayADAPTFramework/  If you would rather not use a NuGet client, you can download any version of the package from nuget.org and extract it using a zip utility. In addition to executables, the ADAPT package contains a “Resources” folder that contains RepresentationSystem.xml and UnitSystem.xml. This entire Resources folder needs to be copied to your application’s \bin directory for the representation system to work.

Application Data Model

The ADAPT Application Data Model is being documented by the AgGateway committee responsible forthe ADAPT project. The project homepage is found at http://www.adaptframework.org/

Plugin Manager

The Plugin Manager is used to retrieve and marshal plugins. The PluginFactory must be passed a filesystem directory where the plugin assemblies are stored. Note that while there may be subdirectories (i.e., a folder for each manufacturers’ plugins), the plugin manager will only recurse one level of subdirectories. In other words, passing “C:\AdaptPlugins\” to the PluginFactory would cause it to discover plugins inside both “C:\AdaptPlugins\” and first level subdirectories like “C:\AdaptPlugins\Trimble\”, but not in “C:\AdaptPlugins\Trimble\AgGPS\”. Following is sample code which shows how to load plugins and import a datacard.

PluginFactory factory = new PluginFactory("directory containing plugins");
List<string> pluginNames = factory.AvailablePlugins;
foreach(string pluginName in pluginNames)
{
  IPlugin plugin = factory.GetPlugin(pluginName);
  if(plugin.IsDataCardSupported("datacard path")
  {
    ApplicationDataModel dataModel = plugin.Import("datacard path");
    return dataModel;
  }
}

Representation

The Representation namespace includes two sets of helper API’s the Unit of Measure System and the Representation System. Together, they form something similar to the ISO DDI system of describing data. A Representation describes the type of data – such as harvest moisture, implement section state, or the GPS receiver offsets. A Unit of Measure provides both the syntax for specifying a unit and the ability to convert between different units of measure or perform arithmetic operations. You can explore the Representations and the units of measure in the included RepresentationSystem.xml and UnitSystem.xml files. Note that these xml files are used by the Representation namespace; if you reference the ADAPT Representation assembly, you will need to include those xml files as resources which are copied to your application’s executing directory.

Unit of Measure System

The simplest way to retrieve unit of measure objects is using static methods on the UnitSystemManager class. To retrieve a UnitOfMeasure instance, pass a unit code to UnitSystemManager.GetUnitOfMeasure(“unit code”). You may also use UN Rec20 unit codes, via UnitSystemManager.FromUNRec20Code(“UN unit code”).

To help use the units of measure: Once you create a NumericValue, which consists of a value and unit, we offer helper methods for arithmetic operations or unit conversions. If you add the namespace: using AgGateway.ADAPT.Representation.UnitSystem.ExtensionMethods; You will then have access to NumericalValue.Add(double value), NumericalValue.ConvertToUnit(UnitOfMeasure unit), and other helper methods.

Trimble ADAPT Plugins

The ADAPT plugins to read Trimble display data are

  • Trimble.Ag.ADAPT.Plugins.AgData.dll - PIQ and related displays
  • Trimble.Ag.ADAPT.Plugins.AgGPS.dll - FMX and related displays

Initialization

Trimble plugins require a license token to be validated in the initialization process that is acquired through the Trimble Cloud API system. Applications will need to be registered in the Trimble Cloud system to access this API.

To simplify the process of authenticating and requesting the token, functions have been added to the Trimble plugins that will perform the API calls for a 3rd party application to request a new token. The function is:

AdaptTokenClient.GetTokenAsync( {AppName}, {AppClientID}, {AppSecret} )
  • AppName: Name of calling application as registered in Trimble Cloud
  • AppClientID: GUID assigned to application by Trimble Cloud
  • AppSecret: Application password assigned by Trimble Cloud

The token structure returned will have the following:

  • token: string with encrypted token value to be used in Initialize function
  • expiration: date and time the token expires. Tokens can be reused up to the expiration date.

Datacard Paths

The Trimble plugin will support multiple datacard paths. It will support a path that includes the AgGPS or AgData directory (ex: C:\TrimbleData\AgGPS). It will also support passing the parent directory as well (ex: C:\TrimbleData).

Please note that the plugin will not support both file formats at once. If you have a datacard path that has both an AgGPS and AgData directory, it will only read the AgGPS information.

Other Information

Bookmarks

The maximum number of records returned for most calls is 1000. In cases where the potential number of records in a response exceeds the maximum number of records that can be returned, a bookmark attribute is included in the response. The token associated with that bookmark then can be passed as a query parameter in a subsequent call to obtain the next set of records. For example, if the total number of records associated with some request is 1,500, the first response will include 1,000 records and a bookmark attribute. A following call including the token from that bookmark would return the remaining 500 records.<br><br>An example of the bookmark attribute as part of a response is shown below.<br><br><img width="722" height="93" src="https://lh6.googleusercontent.com/mogue_-8AvRE88K1FJxBKEPveylNbPIIDZ-blwjFkIW0USjrrBNrHwig6hGo8W64XYFggdsareAJZG5lx0WsiOHyE2UVRigLN4sY62S-exR85CwNqAqyemhp2SUbnruMH7ggGwT6x6i92u6j9g">

 

Links

Links are Trimble Ag’s implementation of <a href="https://restfulapi.net/hateoas/">HATEOAS</a>. These links are useful in discovering additional actions and endpoints that are associated with a particular call. If you do not wish to include links in the response, these can be disabled by using the query parameter includeLinks=false in the request.<br><br>The following is an example of links being returned for the Clients GET endpoint:
"links": [
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9",
                   "rel": "GetClient",
                   "method": "GET"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients",
                   "rel": "CreateClient",
                   "method": "POST"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9",
                   "rel": "UpdateClient",
                   "method": "PUT"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9/retire",
                   "rel": "RetireClient",
                   "method": "PATCH"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9/unretire",
                   "rel": "UnretireClient",
                   "method": "PATCH"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/farms",
                   "rel": "GetFarms",
                   "method": "GET"
               }
           ]