Getting Started

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.10
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[all]

Using the`[all]` option 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

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.

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('sentinel-2-l2a')
>>> ds
dataset:remote-sensing:earth-observation:earth-observation:sentinel-2-l2a
>>> print(ds)
Dataset
    name: sentinel-2-l2a
    alias: Sentinel 2 L2A
    description: The Copernicus Sentinel-2 mission comprises a constellation of two
        polar-orbiting satellites placed in the same sun-synchronous
        orbit,  phased at 180° to each other. It aims at monitoring
        variability in land surface conditions, and its wide swath width
        (290 km) and high revisit time (10 days at the equator with one
        satellite, and 5  days  with 2 satellites under cloud-free
        conditions which results in 2-3 days at mid-latitudes) will
        support monitoring  of Earth's surface changes. L2A is surface
        reflectances in cartographic geometry. This product is considered
        as the mission Analysis Ready  Data (ARD), the product that can be
        used directly in downstream applications without the need for
        further processing.
    domain: remote-sensing
    category: earth-observation
    type: earth-observation
    Provider Info:
        name: stac
        url: https://earth-search.aws.element84.com/v0
        properties:
        collection: sentinel-s2-l2a-cogs

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