Quick Start - Setting Up for the API

Our Jupyter Notebooks

All of the documentation and samples we provide are built using Jupyter notebooks. You can read the documentation in text form here. You can run the notebooks yourself by cloning the ibmpairs repository and looking at the “notebooks” directory.

To run the notebooks you will need a number of things:

  • IBM Environmental Intelligence: Geospatial APIs credentials stored in EI_API_KEY, EI_TENANT_ID (or EI_CLIENT_ID) and EI_ORG_ID environment variables

  • A Python3.7 or higher environment

  • A Jupyter Notebook environment

  • The ibmpairs pip package at version 3.0.0 or greater installed into you Python3 environment.

Note that the notebooks include runnable examples but you need to run them in order from top to bottom. This is because there are some lines of set up code, for example, setting authentication credentials, that only appear in the first code cell. We leave them out subsequent cells to avoid clutter.

Also note that in point 1 above you could change the notebooks so that you place your username and api key in-line in the code rather than using the environment variables included. However, we don’t recommend this, as inclusion in a notebook increases the risk of your credentials being passed on to other people.

Geospatial APIs Credentials

The Geospatial APIs component provides an API (at https://api.ibm.com/geospatial/run/na/). To use this you will also need an API key, a Tenant (or Client) Id and an Org Id. If you don’t have an API key, a Tenant (or Client) Id and an Org Id please contact your IBM representative.

In the Jupyter Notebooks that are part of this quick start tutorial we don’t include secret credentials. We read the credentials from operating system environment variables when they are required:

EI_API_KEY   = os.environ.get('EI_API_KEY')
EI_TENANT_ID = os.environ.get('EI_TENANT_ID')
EI_ORG_ID    = os.environ.get('EI_ORG_ID')

If you do not have a tenant id you can instead set a client id (e.g. EI_CLIENT_ID) and pass client_id = EI_CLIENT_ID to the authentication.OAuth2 object init or the get_client() call.

Set these values in your environment before you start so that they are ready to be used when required, for example,

On Linux

In the shell where you will launch the Jupyter notebooks do the following:

export EI_API_KEY   = <your IBM Environmental Intelligence api key key here>
export EI_TENANT_ID = <your IBM Environmental Intelligence tenant key here>
export EI_ORG_ID    = <your IBM Environmental Intelligence org id here>

From here, you can now start to use the notebooks provided.

On Windows

Open the ‘Environment Variables’ dialog by doing the following

  • Type ‘sysdm.cpl’ into the ‘Type here to search’ box to bring up the ‘System Properties’ dialog

  • Select the ‘Advanced’ tab

  • Press the ‘Environment Variables…’ button

On the ‘Environment Variables’ dialog you can create ‘New…’ environment variables for EI_API_KEY, EI_TENANT_ID and EI_ORG_ID setting the values to the ones you have been given.

Now you have set environment variables you need to start a new DOS prompt or Powershell. The new shells will adopt these new environment variables. From here, you can now start to use the notebooks provided.

Python3

The API tutorials are written in Python3. You can use any programming language by talking to the Geospatial APIs HTTPs endpoints using the standard HTTPs libraries from your language of choice.

If you want to use Python3 but don’t have an environment set up including Jupyter notebooks there are many resources on the internet that can help you.

ibmpairs SDK

The Jupyter notebooks in this tutorial use the ibmpairs API wrapper for convenience. You will need to install this into your Python3 environment. Make sure you have install at least version 3.0.0.

There is a more detailed overview of the ibmpairs SDK here.

PIP

pip3 install ibmpairs>=3.0.0

Installing in Watson Studio Notebook

put the following code in a cell

!pip install ibmpairs

Common Python3 Issues

Supported Python3 Versions

The ibmpairs SDK is only tested on Python3 Version 3.7 and above. If you see an error like the following when you are installing the wrapper then your Python3 version may be too old.

Collecting pandas>=1.0.1 (from ibmpairs==3.0.0)
  Could not find a version that satisfies the requirement pandas>=1.0.1 (from ibmpairs==0.2.1) (from versions: 0.1, 0.2, 0.3.0, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.5.0, 0.6.0, 0.6.1, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.8.0, 0.8.1, 0.9.0, 0.9.1, 0.10.0, 0.10.1, 0.11.0, 0.12.0, 0.13.0, 0.13.1, 0.14.0, 0.14.1, 0.15.0, 0.15.1, 0.15.2, 0.16.0, 0.16.1, 0.16.2, 0.17.0, 0.17.1, 0.18.0, 0.18.1, 0.19.0, 0.19.1, 0.19.2, 0.20.0, 0.20.1, 0.20.2, 0.20.3, 0.21.0, 0.21.1, 0.22.0, 0.23.0, 0.23.1, 0.23.2, 0.23.3, 0.23.4, 0.24.0, 0.24.1, 0.24.2)
No matching distribution found for pandas>=1.0.1 (from ibmpairs==3.0.0)

Missing Geospatial APIs Libraries On Windows

If you see the following error while builds are progressing as part of the ibmpairs SDK install:

A GDAL API version must be specified. Provide a path to gdal-config using a GDAL_CONFIG environment variable or use a GDAL_VERSION environment variable.

This indicates that your Windows environment is not configured properly in order to build the geospatial dependencies of the Geospatial APIs wrapper. This can be tricky to get right. The easiest solution is to download and install the pre-build wheels for the following packages:

Fiona-1.8.18-cp37-cp37m-win_amd64.whl
GDAL-3.2.1-cp37-cp37m-win_amd64.whl
rasterio-1.2.0-cp37-cp37m-win_amd64.whl
Shapely-1.6.4.post2-cp37-cp37m-win_amd64.whl
basemap-1.2.2-cp37-cp37m-win_amd64.whl

You may be able to take newer versions of these wheel packages but these are known to work.

There are many resources on the internet that give suggestion about how to obtain these packages, for example

Once you have a .whl file you can install it using pip by referencing it directly, for example:

pip3 install Fiona-1.8.18-cp37-cp37m-win_amd64.whl