Introduction

The Agrimetrics developer portal allows developers to access the Agrimetrics APIs. Through the portal developers can sign up for an account, and subscribe to online products consisting of data APIs. The portal also has documentation, and a built-in console that allows developers to explore how the APIs work more easily.

Note that for current products a contractual agreement is also required between the developer and Agrimetrics, as well as the subscription via the portal.

Getting Started

The developer portal is organised on the basis of Products, which contain one or more APIs and may support different levels of access (e.g. request limits). A developer can subscribe to a Product, which provides a key that can be used to access the APIs. This key is specific to the developer account and Product subscription, and will be used for access control and billing (where appropriate).

To find out more about the APIs, including the format of the returned data, select an API from the Product page and explore the available endpoints and the examples of returned data and schema. This documentation is available without having to subscribe to the Product. Trying out the APIs through their documentation pages requires a subscription.

To use an Agrimetrics API product you will need to:

  1. Contact Agrimetrics to sign up for a trial or paid subscription for a particular product
  2. Register for a developer account via this portal
  3. Subscribe to a product (Agrimetrics will enable the subscription according to your agreement)
  4. From the product page, navigate to one of the APIs
  5. Click the 'Try it out' button to access the developer console.

Using the Products

The APIs within the products can be accessed by HTTP GET or POST calls, passing in any parameters required by the specific API. The full endpoint to submit the request to is given on the relevant API documentation page. Your subscription key for this product needs to be passed in to the API in the HTTP header, and is used for access control and billing (where appropriate). This key should be considered a secret that is only available to you, and should not be shared with other entities or included in source code repositories in any publically-visible place. Calls should be made using SSL to safeguard your subscription key as well as the data; calls made to an http address instead of https will be rejected. If you make a call to the APIs without providing a subscription key, or provide a key that is not recognised, you will receive a 401 response indicating that your request has not been authorised.

Data is returned from the APIs as JSON-LD documents, which can be parsed in any programming language either directly or through a JSON or JSON-LD library. They can also be loaded into your own graph. The schema describing the content is provided through the context endpoint for each API, giving a JSON-LD document that links the data to the ontology describing the entities in the data and the relationshis between them.

Each API has at least one functional endpoint, where the main functionality is provided. There are also some utility functions provided to query the status of the API and to retrieve the JSON-LD context that describes the response. All of the available endpoints for each API can be viewed from the API documentation; if you are logged in to this portal and have a subscription key for the API product you can try out each endpoint from the API documentation pages and view the responses. Examples of the responses are given (these are abridged to provide e.g. one representative element per collection, such as a single day or a single month).

  • /context - provides the JSON-LD linking the types in the response back to ontologies
  • /functional endpoint - the primary endpoint serving up the main content for this API. The name of the functional endpoint will be specific to the purpose of the API and endpoint - e.g. /trends is the name of the main functional endpoint for the Field Trends API.

API documentation describes any specifics of responses (e.g. whether a specific API responds to a call for access-controlled data with a 404 rather than a 401 to prevent implicit leaking of information).