Warning: This document is for the development version of Gro API Client.

Setting Up Your Environment

In order to start engaging with the Gro API Client, you will need to set up your local environment with some basic requirements.

  1. System Prerequisites
  2. Authentication Token/Saving Environment Variables

System Prerequisites

The Gro API Client requires the following OS-dependent system requirements.

MacOS and Linux

  1. git (Installation instructions)
  2. python version 3.5 or above from https://www.python.org. Support for Python 2.7.13 or above is also maintained, but with its End of Life soon approaching, Python 3 is recommended.

Windows

The Gro API Client package is supported both with or without Anaconda. However, some popular data science packages, including some used in the sample scripts provided, are only available on Windows via conda. For that reason, instructions are provided for both. You should select the distribution that fits your requirements.

Anaconda

  1. Download Anaconda with Python 3.5 or above from anaconda.com. Support for Python 2.7.13 or above is also maintained, but with its End of Life soon approaching, it is recommended you start with Python 3.
  2. Install Git from git-scm.com. Proceed with the default options.

Non-Anaconda

  1. Powershell (should come default with Windows)
  2. Download Python version 3.5 or above from python.org. Support for Python 2.7.13 or above is also maintained, but with its End of Life soon approaching, it is recommended you start with Python 3.
  3. Install both Python and pip to PATH either in the installer (enable component during the installation) or manually. The easiest way to do this is to make sure the below is checked during installation: readme_add_python_to_path_installer.png
  4. Install Git from git-scm.com. Proceed with the default options.

Installing Gro Packages

Now that you have downloaded the base system requirements, you will need to install the packages for the Gro API Client.

Install with pip install

pip install git+https://github.com/gro-intelligence/api-client.git

Note: even if you are using Anaconda, the API Client install should still be performed using pip and not conda.

Note: to find the location where Gro packages have been installed you can use the query:

pip show gro

Authentication Token

  1. Retrieving a token
  2. Expiring/Regenerating Tokens
  3. Saving your token as an environment variable

To work with the Gro API, you need an authentication token. This token needs to be sent along with every request made to the API. This is typically done by using one of the included Client classes (Client, GroClient, BatchClient, or CropModel): you provide your access token when creating the object, and then every API request made thereafter automatically includes the token.

Retrieving a token

Note that your account needs to be activated for API access before you will be able to retrieve a token. See https://gro-intelligence.com/products/gro-api for more info regarding unlocking API access for your account. Once you have API access enabled for your account, you may retrieve your token in any of the following ways:

  1. Using the Gro Web Application (preferred)
  2. Using the Gro Command Line Interface
  3. Using the get_access_token() Function

Option 2: Using the gro_client Command Line Interface

Limitation: The Gro Command Line Interface cannot retrieve tokens for users using OAuth authentication. If this applies to you, please use the Gro web application instead.

When you install the Gro API Client via pip, the gro_client command line interface is automatically added to your PATH. This is a convenience tool for doing basic operations on the command line without needing to write a full Python script. One of its uses is it can retrieve your authentication token and print that token out to the console. To do so, execute the command below on your command line, substituting email@example.com for the email address associated with your Gro web application account:

gro_client --user_email="email@example.com" --print_token

You should then be prompted for a password. Note that this password prompt does not display any user input on the command line, so it may appear as though you are not typing anything. This is intended. Simply type your password and press Enter.

If the password is accepted, your access token is printed to the console.

Option 3: Using the get_access_token() Function

Limitation: The get_access_token() function cannot retrieve tokens for users using OAuth authentication. If this applies to you, please use the Gro web application instead.

If you would like to programmatically retrieve your active token, you may use the get_access_token() function in the API Client library. See below:

from api.client.lib import get_access_token
API_HOST = 'api.gro-intelligence.com'
EMAIL = 'example@example.com'
PASSWORD = 'password123'
ACCESS_TOKEN = get_access_token(API_HOST, EMAIL, PASSWORD)

It is generally bad practice to put login credentials directly in code as in this example, but the get_access_token() function may be useful for productionization purposes, making the application more robust to tokens expiring (see the next section).

Expiring/Regenerating Tokens

There are two ways you can invalidate your current authorization token and create a new one, both of which are performed through the Gro web application:

  1. Changing your password, or
  2. Using the “Regenerate Token“ button in the API section of your Account menu (see instructions below)

If you have your authentication token saved, performing either of these two actions will cause any applications using the old token to cease being able to contact the Gro API. You will need to follow the instructions in Section 1 to retrieve your new token and update any such applications accordingly.

To regenerate your authentication token, open the API tab in your Account menu as in Retrieving a token, Option 1: Using the Web App, but instead of copying the authentication token, press the “Regenerate Token“ button (see below). A prompt will appear to warn that any applications using the old token will need to be updated and to confirm your intent.

regenerate-token.png

Saving your token as an environment variable

If you don‘t want to enter a password or token each time, you can save the token as an environment variable. In some of the sample code, it is assumed that you have the token saved to your environment variables as GROAPI_TOKEN.

Please consult your OS or IDE documentation for the most accurate and up-to-date information on how to set environment variables, e.g. setting environment variables in Windows Powershell or Mac OS X/Linux or Anaconda. As a quick guide, the following steps should work:

For Windows 10:

  1. Click on start menu and search for “environment variables.“ Click on “Edit the system environment variables“ option.
  2. In the “Advanced“ tab, select the “Environment Variables...“ button.
  3. Under the first section called “User variables for <username>,“ and click on the “New“ button.
  4. Enter the information as follows:

Variable name: GROAPI_TOKEN

Variable value: <insert your Gro API Token here>

  1. Click OK

Your environment variable should now be saved. You will likely need to close an re-open your IDE for the IDE to recognize the change. Whenever you run code that includes the code os.environ['GROAPI_TOKEN'] it should automatically pull in your API Token.

For Mac:

  1. Open up your terminal and type open ~/.bash_profile
  2. Add the following line: export GROAPI_TOKEN="YOUR TOKEN HERE"
  3. Save the file and close any shells you have open. The environment variable should be available next time you open a shell.