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.
The Gro API Client requires the following OS-dependent system requirements.
MacOS and Linux¶
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.
- Powershell (should come default with Windows)
- 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.
- 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:
- 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: to find the location where Gro packages have been installed you can use the query:
pip show gro
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 (
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:
- Using the Gro Web Application (preferred)
- Using the Gro Command Line Interface
- Using the get_access_token() Function
Option 1: Using the Web App (Recommended)¶
- Log in to your Gro account at http://app.gro-intelligence.com and open your Account menu using the button on the bottom left of the Gro dashboard (see image below).
- In the Account menu, select the API tab (see below).
- Select the text of the token and copy it to your clipboard, or use the “Copy to clipboard“ button (see below).
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 firstname.lastname@example.org 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 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 = 'firstname.lastname@example.org' 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).
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:
- Changing your password, or
- 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.
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
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:¶
- Click on start menu and search for “environment variables.“ Click on “Edit the system environment variables“ option.
- In the “Advanced“ tab, select the “Environment Variables...“ button.
- Under the first section called “User variables for <username>,“ and click on the “New“ button.
- Enter the information as follows:
<insert your Gro API Token here>
- 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.
- Open up your terminal and type
- Add the following line:
export GROAPI_TOKEN="YOUR TOKEN HERE"
- Save the file and close any shells you have open. The environment variable should be available next time you open a shell.