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 some 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.

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.get_dataset('modis-mcd43a4')
>>> ds
dataset:remote-sensing:earth-observation:multispectral:modis-mcd43a4
>>> print(str(ds))
Dataset
  name: modis-mcd43a4
  alias: MODIS MCD43A4
  description: The MODIS MCD43A4 version 6 Nadir Bidirectional reflectance
    distribution function Adjusted Reflectance (NBAR) data set is a
    daily 16-day product. The Julian date in the granule ID of each
    specific file represents the 9th day of the 16 day retrieval
    period, and consequently the observations are weighted to estimate
    the Albedo for that day. The MCD43A4 algorithm, as is with all
    combined products, has the luxury of choosing the best
    representative pixel from a pool that includes all the
    acquisitions from both the Terra and Aqua sensors from the
    retrieval period. The MCD43A4 provides the 500 meter reflectance
    data of the MODIS “land” bands 1-7 adjusted using the
    bidirectional reflectance distribution  function to model the
    values as if they were collected from a nadir view.
  domain: remote-sensing
  category: earth-observation
  type: multispectral
  Provider Info:
    name: elastic
    url: https://elasticsearch-master.default.svc.cluster.local:9200
    properties:
      date_field: properties.datetime
      end_date_field: properties.end_datetime
      geometry_field: geometry
      geometry_type: geo_shape
      id_field: _id
      index_pattern: modis-mcd43a4
      insecure: True
      start_date_field: properties.start_datetime

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