Quickstart

If you are ready to jump in, this page will get you started with the Geodesic python API. This is intended to get the API installed and authenticated quickly but we recommend that if this is your first time using Geodesic that you read the overview guides, or jump straight into the Geodesic Basics section.

Installation

You will want to use some sort of virtual environment to manage your python libraries. This ensures that you do not have version conflicts with any other projects you might have that also use python. We recommend Conda as it has the easiest installation options for libraries that need binaries.

To install miniconda (the lightweight Conda package manager) follow instructions here.

Once conda is installed we can create a virtual environment:

conda create -n geodesic python=3.8
conda activate geodesic

You can then install the Geodesic API through pip. There are a few installation options including installing all dependencies or only installing minimal dependencies to work. For getting started we recommend installing all dependencies. This will enable all functionality including all Jupyter widgets and visualizations. To install all dependencies along with the Geodesic API, run

pip install geodesic-api[jupyter]

Another common option is [all]. This will install everything needed for all parts of the geodesic-api. Geodesic should now be usable in the geodesic conda environment.

Note

If the widgets wont display in Jupyter Lab, it is likely due to an outdated version of Conda. Check that you are using version 21.X.X or greater. Version 4.X.X may not work.

Using the API

To use the Geodsic API you must first authenticate with the platform. This can be done either from python or from the command line.

CLI Authentication

$ geodesic authenticate
To authorize access needed by Geodesic, open the following URL in a web browser and follow the instructions. If the web browser does not start automatically, please manually browse the URL below.

    https://seerai.us.auth0.com/authorize?client_id=*******************

The authorization workflow will generate a code, which you should paste in the box below.
Enter verification code:

This will print a link in the terminal and wait for a verification code. Copy paste the link into your browser and follow the login flow. You should be presented with a login page that looks like this:

After logging in you will be redirected to a page with your verification code.

Paste this code in the terminal prompt to complete the authentication flow.

Python Authentication

Python authentication can be done either in the python interpreter or a Jupyter environment.

>>> import geodesic
>>> geodesic.authenticate()

The rest of the process is the same as the CLI authentication. You will not need to log in each time you use the API. The credentials stored are long lived.

First Entanglement Query

Now that you have the python API installed and authenticated we can test that it works. Open a Jupyter notebook and try to query Entanglement.

ds = geodesic.list_datasets(search='modis')
ds

You should see the dataset widget displayed with the metadata for the MODIS dataset. |

If for some reason you do not want to use a Jupyter environment, you can still perform the test query. Open a python interpreter from the command line and run the above lines. You will see a line of text for the MODIS dataset that should look something like

{'modis-mcd43a4': dataset:remote-sensing:earth-observation:multispectral:modis-mcd43a4}

Your Geodesic Python API should now be setup and ready to use.