Local Environment Setup

Disclaimer

The example Python source code is meant merely as a starting point to quickly interact and retrieve insights from ADMA. It is in no way intended for production workloads.

Pre-Requisites

This tutorial assumes the following:

• a UNIX-like environment.
• a basic working knowledge of Python. This tutorial does not use anything fancy or esoteric within the Python language.
• a working version of Python 3.12.x or higher. For this tutorial, we generally install Python using Python.org.
• an instance of ADMA installed in your tenant. Installation Overview
• a SentinelHub license for accessing satellite imagery. Bring Your Own License

Tutorial Source Code

Tutorial Source Code Download

Please start by downloading and unzipping the tutorial source code.

To quickly get started, the source for the example code referenced later in this tutorial is provided tutorial source code. Unzip this to a location of your choice. It will create an adma directory from which you can work.

The directory structure of the project looks like the following.

adma
├── requirements.txt
├── resource
│   ├── application_config.yml
│   ├── el.geojson
│   └── logging.yml
└── tutorial
    ├── adma
    │   ├── farm.py
    │   ├── field.py
    │   ├── insight_attachment_util.py
    │   ├── insight.py
    │   ├── jwt.py
    │   ├── party.py
    │   └── solution.py
    ├── example
    │   ├── bulk_imagery.py
    │   ├── concurrent
    │   │   ├── bulk_imagery.py
    │   │   └── gdd.py    
    │   ├── create_farm.py
    │   ├── create_field.py
    │   ├── create_party.py
    │   ├── crop_id.py
    │   ├── gdd.py
    │   ├── get_farm.py
    │   ├── get_field.py
    │   ├── get_party.py
    │   ├── imagery.py
    │   └── jwt.py
    │   ├── smart_boundary.py
    └── util
        ├── headers.py
        ├── logging.py
        └── request_meta.py

Create a Python Virtual Environment

Let's start by creating a Python virtual environment, activating the Python virtual environment and ensuring pip is up-to-date. The virtual environment will host Python and its dependencies.

Change to the directory where you extracted adma-vX.zip, then execute the following commands.

python3 -m venv adma/venv
cd adma
source venv/bin/activate
pip3 install --upgrade pip

Install AgPowered Services Python Requirements

With the Python virtual environment still active and at the root of the adma directory, execute the installation command below.

pip3 install -r requirements.txt

Generate a JWT

In order to begin with ADMA you will need a few piece of information to acquire a JWT. A JWT is required for all calls to ADMA or AgPowered Services.

To obtain a JWT, you need the following information:

• a tenant id; This will likely be a UUID.
• a client id; This will likely be a UUID.
• a client secret
• a scope; This will likely be a URL.

application_config.yml

We are going to start by populating the configuration into the YAML file within a adma/resource directory.

e.g., adma/resource/application_config.yml

base_url: your value
fb_api_version: your value
tenant_id: your value
client_id: your value
client_secret: your value
scope: https://farmbeats.azure.net/.default

cropid_solution_id: bayerAgPowered.cropId
gdd_solution_id: bayerAgPowered.gdd
imagery_solution_id: bayerAgPowered.imagery
smart_boundary_solution_id: bayerAgPowered.smartBoundary

Assuming you have the resource/application_config.yml populated and the Python virtual environment activated, you should be able to generate a JWT using the following command. The command assumes that it is being run from the root of the adma directory.

python -m tutorial.example.jwt

Successful generation of a JWT will output a long string beginning with "Bearer eyJ".

Troubleshooting

If this does not execute successfully and an exception is raised, then please double-check the contents of resource/application_config.yml. Another problem you may encounter, depends on whether the command was executed from the command-line or from within an IDE. An IDE may set the working directory differently that expected, and you may have to change the path to resource/application_config.yml within tutorial/example/jwt.py.

When you install Python via a package downloaded from Python.org., don't forget to run the "Install Certificates" command to make sure Python will work correctly with SSL.

If you have executed the "Install Certificates" and you are still running into SSL errors, then you may need to an additional step. With the Python virtual environment active and at the root of the adma directory, execute the command below and record the fully-qualified path.

python -c "import requests; print(requests.certs.where())"

Then concatenate your organization's PEM with the fully-qualified PEM from above. This should resolve any remaining SSL issues.

cat your-organization.pem >> fully-qualified-requests.pem