Agworld API Documentation
Introduction
The Agworld API is an implementation of the JSON API specification. It is currently Read-Only.
URL
In the examples below, please substitute <url> with the appropriate url for the instance that you are connecting with. A
non-exhaustive list of Agworld instances is listed below:
- Australia -
https://my.agworld.com.au - The United States -
https://us.agworld.co - New Zealand -
https://nz.agworld.co
Content-Type
Clients must include the following headers with every POST, and PATCH request:
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
The API will include the following headers with each response:
Content-Type: application/vnd.api+json
OAuth Authentication
Authentication is based on Oauth2 workflow. To authenticate the request on the user’s behalf, the appropriate JWT token must be obtained. The implementation provider documentation describing this process is here
To register a 3rd party web-based application, take the following steps:
- Provide Agworld with your site’s URLs - in particular, the Oauth2 callback and logout URLs
- Agworld will register the application and provide you with
client_id,client_secretand the base URL for authentication requests
Using the credentials provided, you then need to obtain user authorisation, see here. The required Oauth2 scope is openid.
For non-prodiction environment, it is recommended to add the email scope as well to mitigate the environment’s volatility.
Using the code in the callback URL handler of your application, you can get the access token, see here
Token should be used as an Authorization (for non-production Agworld environments use X-Authorization) header parameter when requesting Agworld API resources:
curl <url>/api/fields \
-H 'Authorization: Bearer <token>'
Requests signed with this token would be run in the context of the user and provide the data available to that user, same data as in Agworld website or Agworld mobile application.
Token Authentication
In addition to OAuth2 authentication, the Agworld API supports authentication using API tokens. This method provides a straightforward way to authenticate API requests.
Obtaining an API Token
API tokens are generated by the Agworld Sales and Customer Success teams on behalf of users. Each token:
- Is associated with a specific user account and inherits the permissions of that user
- Can have an optional expiration date
- Can be revoked at any time
To request an API token, please contact your Agworld Sales or Customer Success representative.
Using API Tokens
Include the API token in the Authorization header with the API-Key prefix:
Authorization: API-Key <your_token>
The token format is: v1_<32-character-alphanumeric-string>
Code Examples
curl
curl https://my.agworld.com.au/api/fields \
-H "Authorization: API-Key ${AGWORLD_API_TOKEN}" \
-H "Accept: application/vnd.api+json"Python
import os
import requests
# Get API token from environment
api_token = os.getenv("AGWORLD_API_TOKEN")
# API endpoint
url = "https://my.agworld.com.au/api/fields"
# Make the request
headers = {
"Authorization": f"API-Key {api_token}",
"Accept": "application/vnd.api+json"
}
response = requests.get(url, headers=headers)
data = response.json()Ruby
require 'net/http'
require 'json'
# Get API token from environment
api_token = ENV['AGWORLD_API_TOKEN']
# API endpoint
uri = URI('https://my.agworld.com.au/api/fields')
# Make the request
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "API-Key #{api_token}"
request['Accept'] = 'application/vnd.api+json'
response = http.request(request)
data = JSON.parse(response.body)C#
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class AgworldApiClient
{
static async Task Main()
{
var apiToken = Environment.GetEnvironmentVariable("AGWORLD_API_TOKEN");
var url = "https://my.agworld.com.au/api/fields";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Authorization", $"API-Key {apiToken}");
client.DefaultRequestHeaders.Accept.Add(
new MediaTypeWithQualityHeaderValue("application/vnd.api+json"));
var response = await client.GetAsync(url);
var data = await response.Content.ReadAsStringAsync();
}
}
}Go
package main
import (
"fmt"
"io/ioutil"
"net/http"
"os"
)
func main() {
apiToken := os.Getenv("AGWORLD_API_TOKEN")
url := "https://my.agworld.com.au/api/fields"
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", fmt.Sprintf("API-Key %s", apiToken))
req.Header.Add("Accept", "application/vnd.api+json")
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}Java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class AgworldApiClient {
public static void main(String[] args) throws Exception {
String apiToken = System.getenv("AGWORLD_API_TOKEN");
String url = "https://my.agworld.com.au/api/fields";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "API-Key " + apiToken)
.header("Accept", "application/vnd.api+json")
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}TypeScript/JavaScript (Node.js)
// TypeScript
import axios from 'axios';
const apiToken: string = process.env.AGWORLD_API_TOKEN!;
const url: string = "https://my.agworld.com.au/api/fields";
async function fetchFields() {
try {
const response = await axios.get(url, {
headers: {
'Authorization': `API-Key ${apiToken}`,
'Accept': 'application/vnd.api+json'
}
});
return response.data;
} catch (error) {
console.error('Error fetching fields:', error);
}
}
// JavaScript (Node.js with native fetch - Node 18+)
const fetchFieldsNative = async () => {
const response = await fetch(url, {
headers: {
'Authorization': `API-Key ${apiToken}`,
'Accept': 'application/vnd.api+json'
}
});
return response.json();
};Usage Limits
Please limit your integration to as few concurrent requests as possible.
Rate Limiting
The API enforces the following rate limits:
- Concurrent requests: Maximum of 4 concurrent API calls
- Per minute limit: 200 requests per minute
- Per hour limit: 5000 requests per hour
Rate Limit Headers
The API includes rate limit information in the response headers to help you track your usage:
X-RateLimit-Limit: The maximum number of requests allowed in the current periodX-RateLimit-Remaining: The number of requests remaining in the current period
Monitor these headers to ensure your integration stays within the allowed limits and to implement appropriate throttling when needed.
Features
The following JSON API functionality is implemented for each resource’s endpoints (index and show). Please check the JSON API specification for more detail on each of these options.
Note The URL’s passed to curl below are not URL-encoded. This makes reading them easier but it means that they will need to be properly encoded before using them yourself. For example [ and ] become %5B and %5D respectively.
-
filter (index only)
Allows the filtering of the records returned in the response by the specified attribute. The list of filterable attributes is defined for each resource in its specific section.
curl <url>/api/farms?filter[name]=Home \ -H 'Authorization: Bearer <token>' -
sorting (index only)
Allows the sorting of the records in the response by the specified attribute. The list of sortable attributes is defined for each resource in its specific section.
curl <url>/api/farms?sort=name \ -H 'Authorization: Bearer <token>' -
pagination (index only)
The Agworld API uses pagination for each index endpoint with a default page size of 10 and a maximum of 100. To fetch a specific page, a client should provide a
page[number]parameter. It is also possible to optionally override the size of the page returned by providing apage[size]parameter.curl '<url>/api/farms?page[number]=2&page[size]=5' \ -H 'Authorization: Bearer <token>' -
include
For convenience, it is possible to side-load related records in the same request. Side-loadable records for any given resource, match those shown in the relationships for that resource (note whether type is pluralised).
curl <url>/api/farms?include=grower \ -H 'Authorization: Bearer <token>' -
fields
For efficiency, it is possible to only return a subset of the fields available on a resource. The list of visible attributes is defined for each resource in its specific section.
curl '<url>/api/farms?fields[farms]=name' \ -H 'Authorization: Bearer <token>'