Introduction
API Credentials
Obtain your API credentials by sending a request to tas_api@trimble.com.
Exchange data with Trimble Ag Software
- An organization is 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.Your customers must have a Trimble Ag account (created at www.TrimbleAg.com). Each user account will have access to one or more organizations.
- Your users must approve your application to access their data within www.trimbleag.com either through the OAuth process you initiate, or directly through www.trimbleag.com.
- To allow your application to access your customer’s Connected Farm data, you must do the following:
- Obtain an access token
- Once the client application has an access token, you will use the other Trimble Ag API endpoints.
Overview and When to Use
Variables | Definition |
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 after authorizing Organizations for data access in www.trimbleag.com (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
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
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:
Attribute | Description | Values | Required |
Authorization | Basic Auth using Base64 encoded value of provided ClientID:ClientSecret | Basic {Encoded value goes here} | Y |
Content-Type | Specifies the request content type | application/x-www-form-urlencoded | Y |
Request Body Values
This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields:
Attribute | Description | Values | Required |
grant_type | Required value to identify authentication type | authorization_code | Y |
code | The authorization code returned from the OAuth process | {{TIDAuthCode}} | Y |
client_id | The GUID provided to you | {{yourClientId}} | Y |
redirect_uri | An 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:
Attribute | Description | Values |
access_token | The security token that is used on subsequent requests. | This token will be a long string generated with each new POST to this endpoint. |
token_type | Identifier of what type of token has been returned. | Will always be “bearer” |
expires_in | Time 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_token | JWT token to provide additional information about the user. | This token will be a long string generated with each new POST to this endpoint. |
refresh_token | Token to exchange for a new access token and refresh token. | This token will be a string generated with each new POST to this endpoint. |
error | The Error title of the error being shown. | |
error_description | Error 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:
Attribute | Description | Values | Required |
Authorization | Basic Auth using Base64 encoded value of provided ClientID:ClientSecret | Basic {Encoded value goes here} | Y |
Content-Type | Specifies the request content type. | application/x-www-form-urlencoded | Y |
Body Values
The web service expects you to post a URL-Form-Encoded string in the body, containing the following fields:
Attribute | Description | Values | Required |
grant_type | Required value to identify authentication type. | refresh_token | Y |
refresh_token | The refresh code returned from the Authentication Token [link inserted here] endpoint. | {{RefreshToken}} | Y |
tenantDomain | *Required value | trimble.com | Y |
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:
Attribute | Description | Values |
access_token | The 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_type | Identifier of what type of token must be returned. | Will always be “bearer” |
expires_in | Time 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_token | JWT token to provide additional information about the user. | This token will be a long string generated with each new POST to this endpoint. |
refresh_token | Token to exchange for a new access token and refresh token. | This token will be a string generated with each new POST to this endpoint. |
error | Error title | |
error_description | Error 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
GET:
https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/2.0/Organizations/
Authorization: Bearer
eyJ0eXAiOiJK....
Authorization of Organizations
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:
Production URL
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
Once the user hits the save button after selecting the Organizations, they will be redirected to the return 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:
- 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.
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.
Overview and When to Use (Alternate)
Definition of variables
Variables | Definition |
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)
Authorization / authentication API data flow diagram:
Authentication Token API (Alternate)
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:
Attribute | Description | Values | Required |
Authorization | Basic Auth using Base64 encoded value of provided ClientID:ClientSecret | Basic {Encoded value goes here} | Y |
Content-Type | Specifies the request content type | application/x-www-form-urlencoded | Y |
Parameter Values
The web service expects the following fields as query string parameters:
Attribute | Description | Values | Required |
grant_type | Required value to identify authentication type | client_credentials | Y |
scope | The 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:
Attribute | Description | Values |
access_token | The security token that is used on subsequent requests. | This token will be a long string generated with each new POST to this endpoint. |
token_type | Identifier of what type of token has been returned. | Will always be “bearer”. |
expires_in | Time 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. |
error | Error title | |
error_description | Error 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....",
}
Authorization of Organizations (Alternate)
Step 1
As a user of www.trimbleag.com with access to the Organization you would like to authorize, open the following URL in a browser (replacing {{yourClientId}} with the Client Id provided to you):
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 to approve your application.
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
Once the user has authorized you to access their data, you can expect the following:
- 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.
Organizations
Overview
Clients
Farms
Fields
FieldExtents
Boundaries
GuidanceLines
Landmarks
Contacts
OperatorGroups
Overview
MasterCrops
CropSeasons
CropZones
CropZoneExtents
Overview
Materials
Overview
Units
Overview
Devices
Vehicles
VehicleTypes
EquipmentGroup
EquipmentManufacturers
Implement
Overview
Prescriptions
Overview
EquipmentActivity
Layers
OperationType
OperationSubtype
CropZoneActivity
Files
Download specific files
Use the temporaryAccessUri returned the FileManagement/v3/Files API response to download individual files.
Overview
The ADAPT Data Model
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.
Bookmarks
Links
"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"
}
]