.. _quickstart:

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 :ref:`Geodesic Basics<geodesic_basics>`
section.


Installation
------------

You will want to use some sort of virtual environment to manage your python libraries. This ensures that you do notvhave version conflicts with any other projects you might have that also use python. We recommend 
`Conda <https://docs.conda.io/en/latest/>`_ as it has the easiest installation options for libraries that need binaries.

To install miniconda (the lightweight Conda package manager) follow instructions `here <https://docs.conda.io/en/latest/miniconda.html>`_.

Once conda is installed we can create a virtual environment:

.. code:: bash

    conda create -n geodesic python=3.10
    conda activate geodesic

:ref:`Installing<installing>` the Geodesic Python API is done uing ``pip``. For getting started we recommend installing all dependencies.

.. code-block:: python
    
    pip install geodesic-api[all]


Authenticate with the API
-------------

This can be done either from python or from the command line. For more information on authentication see :ref:`Account Management<authentication>`.

CLI Authentication
^^^^^^^^^^^^^^^^^^
.. code:: bash

    $ geodesic authenticate

.. code:: bash
    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.

A browser window should open and you will see the following screen.

.. code:: bash

    {
    "api_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }

Python Authentication
^^^^^^^^^^^^^^^^^^^^^

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

.. code:: python

    import geodesic
    geodesic.authenticate()


Create a Project
^^^^^^^^^^^^^^^^^

Create your own personal project in within the SeerAI Graph. For more information on projects see :ref:`Geodesic Projects<projects>`.

.. code-block:: python
    
    geodesic.create_project(name="cookbook-examples", alias="Cookbooks Example Project", description="Test project for illustration purposes")
    geodesic.set_active_project("cookbook-examples")



Add a Dataset
^^^^^^^^^^^^^^^^^

Add a dataset to your project. This is just one example of one method of adding a dataset. For more information on adding datasets see :ref:`Adding Datasets<_geodesic_boson_index>`.

.. code-block:: python
    :caption: Creating The Provider

    ds = geodesic.Dataset.from_tabular_data(
        name='uscb-pop-centers',
        url='gs://geodesic-public-data/CenPop2020_Mean_CO.geojson',
        index_data=True,
        crs='EPSG:4326',
    )
    ds.save()