.. _adding_arcgis_service:

Adding An ArcGIS Service Dataset
======================================

Problem
-------

You want to use Boson to connect to a data source which is available as a *Feature, Image, or Map Service* in ArcGIS Online or ArcGIS Enterprise.


Solution
--------

In this example, we will be using a Coastal Barrier Resources System (CBRS) Boundaries layer from the `HIFLD Open Data Catalogue <https://hifld-geoplatform.hub.arcgis.com/pages/hifld-open/>`_.
This layer is an ArcGIS Map service with polygons showing the perimeters of fires in the US from 2000 to 2013. The layer is available `here <https://cbrsgis.wim.usgs.gov/arcgis/rest/services/FEMA/CBRS_Prohibitions/MapServer/0>`_.
Because this is a public layer, we can access it without any credentials.


Setup
~~~~~

To begin we start by importing geodesic:

.. code-block:: python

    import geodesic

If you haven't yet, you will need to authenticate geodesic using the following command:

.. code-block:: python

    geodesic.authenticate()

This process is covered in more detail in the :ref:`Getting Started Guide<getting_started>`.

We need to set the active project to ensure that our dataset is saved to the correct project. We do this using the uid of our desired project. If you do not know the uid, you can fetch a dictionary of existing project that you can access by running :meth:`geodesic.account.projects.get_projects()`. Once you have the uid, you can set your active project like so:

.. code-block:: python

    geodesic.set_active_project('cookbook-examples')


If you need to create a new project the process is detailed in :ref:`Geodesic Projects<projects>` page.

Creating The Provider
~~~~~~~~~~~~~~~~~~~~~

The geodesic python API provides a method, :meth:`geodesic.entanglement.dataset.Dataset.from_arcgis_service()` which makes adding an ArcGIS Service dataset extremely straightforward.
This method supports adding Feature, Map and Image services. To add our fire perimeter dataset, we simply run:

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

    ds = geodesic.Dataset.from_arcgis_service(
        name='cbrs-boundaries',
        url='https://cbrsgis.wim.usgs.gov/arcgis/rest/services/FEMA/CBRS_Prohibitions/MapServer',
        layer_id=0
    )
    ds.save()

This will create a new dataset in our active project called 'cbrs-boundaries' and save it to the project.

Testing The Provider
~~~~~~~~~~~~~~~~~~~~

Now to run a quick test to ensure that the provider is working. Let's search run a simple search to check that features are returned

.. code-block:: python

    ds.search()

This should return the first ten features from the ArcGIS Layer. If you are running in a jupyter notebook, this should appear in a widget like so:

.. figure:: ../../_static/img/cookbooks/from_arcgis/arcgis_service_search.png
    :width: 800

If you are missing the dependencies required to generate the jupyter widgets, or are not running in a notebook at all, the `ds.search()` method will return a dict containing the same information.

As a slightly less trivial example, let's search for fires from the year 2011, that took place in Texas, and were larger than 150k acres:

.. code-block:: python
    :caption: Searching The Dataset

    from geodesic import cql
    feats = ds.search(
        limit=10,
        filter=cql.CQLFilter.logical_and(
            cql.CQLFilter.eq('Unit', 'N01'),yttttt
            cql.CQLFilter.gte('CBRS_Type', 'System Unit'),
        )
    )
    feats

This should return just two features:

.. figure:: ../../_static/img/cookbooks/from_arcgis/arcgis_service_cql.png
    :width: 800

Finally, if you have installed the relevant dependencies, you can use the geodesic mapping utilities to visualize these features on a map using the following lines:

.. code-block:: python
    :caption: Mapping The Features

    from geodesic import mapping
    feats_dict = feats.__geo_interface__
    m = mapping.Map(center = [32.080502,-81.074123], zoom = 10)
    m.add_feature_collection('fires', feats_dict)
    m

If you use the map to navigate to the area of Georgia, you should see the two features from our search:

.. figure:: ../../_static/img/cookbooks/from_arcgis/arcgis_service_map.png
    :width: 800