Note

Go to the end to download the full example code.

Basics of the Geodesic Platform#

This tutorial will introduce you to the basics of the Geodesic Platform.

We will cover the following topics:

  • What is the Geodesic Platform?

  • Install the Geodesic Python API

  • Authenticate with the Geodesic Platform

  • Setup your first project

  • Add datasets to your project

  • Create a map

What is the Geodesic Platform?#

The Geodesic Platform is a cloud-based platform that allows you to connect to data from different sources such as Google Earth Engine, ESRI ArcGIS Living atlas and even data stores in a cloud bucket. You can then use this data to create maps, run analysis and share your results with others without being confined to a single platform.

Installing the Geodesic Python API#

We highly recommend using a virtual environment to install the Geodesic Python API. We recommend Conda as it has the easiest installation options for libraries that need binaries. More specifically, we recommend using miniconda as it is a lightweight Conda package manager. To install miniconda follow the 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.

Authenticate with the Geodesic Platform#

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.

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

{
"api_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

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.

Setup your first project#

Projects are like your personal work area within the SeerAI Graph. You can store datasets and other objects and connections here and they will only be visible to those that you share them with.

You create a new project using the geodesic.account.projects.create_project() method and set the active project using the geodesic.account.projects.set_active_project() method.

import geodesic

geodesic.create_project(
    name="tutorial", alias="Tutorial Geodesic Project", description="Geodesic project for tutorial"
)

geodesic.set_active_project("tutorial")

{'name': 'tutorial', 'alias': 'tutorial', 'description': 'A project used for the Geodesic tutorial', 'owner': 'auth0|65e617fbae17969ef2cd27d7', 'keywords': 'tutorial, geodesic', 'uid': 'bae5bbc815ba5be12f9b19d9c9d1b8225cf53f37'}

Add datasets to your project#

Geodesic allows you to connect to data from different sources such as Google Earth Engine, ESRI ArcGIS Living atlas and even data stores in a cloud bucket. You can then use this data to create maps, run analysis and share your results with others without being confined to a single platform. In this tutorial, we will use add a geojson file stored in a public cloud bucket to our project.

Note

You can also add datasets from Google Earth Engine, ESRI ArcGIS Living atlas and other sources. To find out more information, please refer to Boson index page for additional methods to add datasets.

Creating the Dataset Provider#

The geodesic python API provides a method, from_tabular_data(), which makes adding GeoJSON datasets, as well as many other formats, extremely straightforward.

ds = geodesic.Dataset.from_tabular_data(
    name="marine-cadastre-aids-navigation",
    url="gs://geodesic-public-data/marine-cadastre_aids_nav.geojson",
    index_data=True,
    crs="EPSG:4326",
)
ds.save()

dataset:*:*:*:marine-cadastre-aids-navigation

Checking your Dataset Provider#

There are a few ways to go about checking your dataset provider to ensure it was added correctly.

The first way is to use the dataset_info() method to get information about the dataset provider.

ds = geodesic.get_dataset("marine-cadastre-aids-navigation")
ds.dataset_info()

{'name': 'marine-cadastre-aids-navigation', 'alias': 'marine-cadastre-aids-navigation', 'description': 'provides access tables and geospatial vector data stored in a single file on the backing storage', 'overall_extent': {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [[None, None]]}}, 'max_zoom': 23, 'conforms_to': ['http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'], 'queryables': {'marine-cadastre-aids-navigation': {}}, 'fields': {'marine-cadastre-aids-navigation': {'aid_light_characteristics': {}, 'aid_light_color': {}, 'aid_light_freq': {}, 'aid_type': {'type': 'string'}, 'aidheight': {}, 'aidname': {'type': 'string'}, 'aidrange': {}, 'aidtype': {'type': 'string'}, 'characteristics': {}, 'geometry_bbox': {'type': 'object', 'properties': {'xmax': {'type': 'number'}, 'xmin': {'type': 'number'}, 'ymax': {'type': 'number'}, 'ymin': {'type': 'number'}}}, 'lightlistnumber': {'type': 'number'}, 'location': {}, 'objectid': {'type': 'integer'}, 'remarks': {'type': 'string'}, 'signaltime': {}, 'structure': {}}}, 'geometry_types': {'marine-cadastre-aids-navigation': 'Point'}, 'links': [{'href': 'https://api.geodesic-test.seerai.space/boson/api/v1/datasets/bae5bbc815ba5be12f9b19d9c9d1b8225cf53f37/marine-cadastre-aids-navigation/dataset-info', 'rel': 'self', 'type': 'application/json'}], 'collections': [{'id': 'marine-cadastre-aids-navigation', 'title': 'marine-cadastre-aids-navigation', 'description': 'provides access tables and geospatial vector data stored in a single file on the backing storage', 'extent': {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [[None, None]]}}, 'stac_version': '', 'stac_extensions': None, 'providers': [], 'summaries': {}}], 'provider_config': {'provider_name': 'tabular', 'url': 'gs://geodesic-public-data/marine-cadastre_aids_nav.geojson', 'max_page_size': 10000, 'properties': {'crs': 'EPSG:4326', 'index_data': True, 'region': None}, 'middleware': {}, 'cache': {}, 'tile_options': {'vector': {}, 'raster': {}}, 'servicer_settings': {}}}

Another way is to use the search() method to return data from our newly added dataset. Buy running a ds.search(), it will return the first 10 rows of the dataset.

Create a Map#

Now that you know your dataset provider was added correctly you can search for the data and create a simple map. The Marine Cadeastre dataset contains data on all types of different aids. For this search we are going to do a simple bbox search around the island of Nantucket, MA and filter to select on just lighthouses (aid_type = 'lighthouse').

from geodesic import cql

nantucket_bbox = [-70.350314, 41.107178, -69.836354, 41.442610]

results = ds.search(
    limit=None, bbox=nantucket_bbox, filter=cql.CQLFilter.eq("aid_type", "lighthouse")
)

from geodesic import mapping

m = mapping.Map(center=[41.293247, -70.055904], zoom=10)
m.add_feature_collection("navigation aids", results)
m

Map(center=[41.293247, -70.055904], controls=(ZoomControl(options=['position', 'zoom_in_text', 'zoom_in_title', 'zoom_out_text', 'zoom_out_title']), AttributionControl(options=['position', 'prefix'], position='bottomright'), LayersControl(options=['collapsed', 'position'])), crs={'name': 'EPSG3857', 'custom': False}, default_style=MapStyle(), dragging_style=MapStyle(cursor='move'), layers=(TileLayer(attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://carto.com/attributions">CARTO</a>', base=True, max_zoom=20, min_zoom=1, name='CartoDB.DarkMatter', options=['attribution', 'bounds', 'detect_retina', 'max_native_zoom', 'max_zoom', 'min_native_zoom', 'min_zoom', 'no_wrap', 'tile_size', 'tms', 'zoom_offset'], url='https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png'), GeoJSON(data={'type': 'FeatureCollection', 'features': [{'id': '0', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Flashing', 'aid_light_color': 'white', 'aid_light_freq': '5', 'aid_type': 'lighthouse', 'aidheight': 71, 'aidname': 'Nantucket (Great Point) Light', 'aidrange': '14', 'aidtype': 'FD', 'characteristics': 'Fl W 5s', 'geometry_bbox': {'xmax': -70.04828, 'xmin': -70.04829, 'ymax': 41.390186, 'ymin': 41.39018}, 'lightlistnumber': 545, 'location': None, 'objectid': 111, 'remarks': 'Red from 084 degrees to 106 degrees.  Covers Cross Rip and Tuckernuck Shoals', 'signaltime': 'Night', 'structure': 'On white tower', 'id': '110', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.04828076226858, 41.390184628403695)}, 'bbox': (-70.04828076226858, 41.390184628403695, -70.04828076226858, 41.390184628403695)}, {'id': '1', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Flashing', 'aid_light_color': 'white', 'aid_light_freq': '7', 'aid_type': 'lighthouse', 'aidheight': 158, 'aidname': 'Sankaty Head Light', 'aidrange': '20', 'aidtype': 'FD', 'characteristics': 'Fl W 7.5s', 'geometry_bbox': {'xmax': -69.96608, 'xmin': -69.96609, 'ymax': 41.284393, 'ymin': 41.284386}, 'lightlistnumber': 555, 'location': None, 'objectid': 112, 'remarks': None, 'signaltime': 'Both', 'structure': 'White tower with red band in the middle', 'id': '111', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-69.96608628460076, 41.28438738847254)}, 'bbox': (-69.96608628460076, 41.28438738847254, -69.96608628460076, 41.28438738847254)}, {'id': '2', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Flashing', 'aid_light_color': 'green', 'aid_light_freq': '4', 'aid_type': 'lighthouse', 'aidheight': 30, 'aidname': 'Nantucket East Breakwater Light 3', 'aidrange': '3', 'aidtype': 'FD', 'characteristics': 'Fl G 4s', 'geometry_bbox': {'xmax': -70.10003, 'xmin': -70.10004, 'ymax': 41.310318, 'ymin': 41.31031}, 'lightlistnumber': 15150, 'location': None, 'objectid': 3541, 'remarks': None, 'signaltime': 'Night', 'structure': 'SG on skeleton tower', 'id': '3540', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.10003410805687, 41.3103118332056)}, 'bbox': (-70.10003410805687, 41.3103118332056, -70.10003410805687, 41.3103118332056)}, {'id': '3', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Quick', 'aid_light_color': 'white', 'aid_light_freq': None, 'aid_type': 'lighthouse', 'aidheight': 35, 'aidname': 'Nantucket Harbor Range Front Light', 'aidrange': '9', 'aidtype': 'FD', 'characteristics': 'Q W', 'geometry_bbox': {'xmax': -70.09232, 'xmin': -70.09233, 'ymax': 41.289906, 'ymin': 41.289898}, 'lightlistnumber': 15160, 'location': None, 'objectid': 3543, 'remarks': 'Higher intensity beam to seaward.   Lighted throughout 24 hours', 'signaltime': 'Both', 'structure': 'KRW on white wooden skeleton tower', 'id': '3542', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.09232549302561, 41.289904607703775)}, 'bbox': (-70.09232549302561, 41.289904607703775, -70.09232549302561, 41.289904607703775)}, {'id': '4', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Fixed', 'aid_light_color': 'white', 'aid_light_freq': None, 'aid_type': 'lighthouse', 'aidheight': 51, 'aidname': 'Nantucket Harbor Range Rear Light', 'aidrange': None, 'aidtype': 'FD', 'characteristics': 'F W', 'geometry_bbox': {'xmax': -70.09205, 'xmin': -70.092064, 'ymax': 41.289276, 'ymin': 41.289272}, 'lightlistnumber': 15165, 'location': '81 yards, 161.9 degrees from front light', 'objectid': 3544, 'remarks': 'Higher intensity beam to seaward.Lighted throughout 24 hours', 'signaltime': 'Night', 'structure': 'KRW on white wooden skeleton tower', 'id': '3543', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.09205215904086, 41.289272940704606)}, 'bbox': (-70.09205215904086, 41.289272940704606, -70.09205215904086, 41.289272940704606)}, {'id': '5', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Occulting', 'aid_light_color': 'red', 'aid_light_freq': '4', 'aid_type': 'lighthouse', 'aidheight': 26, 'aidname': 'Brant Point Light', 'aidrange': '9', 'aidtype': 'FD', 'characteristics': 'Oc R 4s', 'geometry_bbox': {'xmax': -70.09026, 'xmin': -70.09027, 'ymax': 41.290035, 'ymin': 41.29003}, 'lightlistnumber': 15205, 'location': None, 'objectid': 3552, 'remarks': 'HORN: 1 blast ev 10s (1s bl). MRASS-Fog signal is radio activated, during times of reduced visibility, turn marine VHF-FM radio to channel 83A/157.175Mhz.  Key microphone 5 times consecutively, to activate fog signal for 45 minutes', 'signaltime': 'Night', 'structure': 'White, cylindrical tower, footbridge to shore', 'id': '3551', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.09026965897205, 41.29003460737487)}, 'bbox': (-70.09026965897205, 41.29003460737487, -70.09026965897205, 41.29003460737487)}, {'id': '6', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Fixed', 'aid_light_color': 'green', 'aid_light_freq': None, 'aid_type': 'lighthouse', 'aidheight': 14, 'aidname': 'Nantucket Ferry Slip 1 Light 1', 'aidrange': None, 'aidtype': 'PA', 'characteristics': 'F G', 'geometry_bbox': {'xmax': -70.09526, 'xmin': -70.09527, 'ymax': 41.28628, 'ymin': 41.286274}, 'lightlistnumber': 15213, 'location': None, 'objectid': 3553, 'remarks': None, 'signaltime': 'Night', 'structure': 'Green', 'id': '3552', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.09526688269302, 41.28627516279178)}, 'bbox': (-70.09526688269302, 41.28627516279178, -70.09526688269302, 41.28627516279178)}, {'id': '7', 'type': 'Feature', 'properties': {'aid_light_characteristics': 'Fixed', 'aid_light_color': 'red', 'aid_light_freq': None, 'aid_type': 'lighthouse', 'aidheight': 14, 'aidname': 'Nantucket Ferry Slip 2 Light 2', 'aidrange': None, 'aidtype': 'PA', 'characteristics': 'F R', 'geometry_bbox': {'xmax': -70.09506, 'xmin': -70.09507, 'ymax': 41.28581, 'ymin': 41.285805}, 'lightlistnumber': 15214, 'location': None, 'objectid': 3554, 'remarks': None, 'signaltime': 'Night', 'structure': 'Red', 'id': '3553', 'style': {'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'}}, 'geometry': {'type': 'Point', 'coordinates': (-70.09506688267649, 41.28580849555475)}, 'bbox': (-70.09506688267649, 41.28580849555475, -70.09506688267649, 41.28580849555475)}], 'bbox': (-70.10003410805687, 41.28438738847254, -69.96608628460076, 41.390184628403695)}, hover_style={'fillOpacity': 1.0}, name='navigation aids', style={'opacity': 1.0, 'fillOpacity': 0.5, 'color': '#428BA9', 'fillColor': '#428BA9'})), options=['bounce_at_zoom_limits', 'box_zoom', 'center', 'close_popup_on_click', 'double_click_zoom', 'dragging', 'fullscreen', 'inertia', 'inertia_deceleration', 'inertia_max_speed', 'interpolation', 'keyboard', 'keyboard_pan_offset', 'keyboard_zoom_offset', 'max_zoom', 'min_zoom', 'prefer_canvas', 'scroll_wheel_zoom', 'tap', 'tap_tolerance', 'touch_zoom', 'world_copy_jump', 'zoom', 'zoom_animation_threshold', 'zoom_delta', 'zoom_snap'], scroll_wheel_zoom=True, style=MapStyle(), zoom=10.0)
Nantucket Lighthouses

Recap#

In this tutorial you learned how to:

  • Install the Geodesic Python API

  • Authenticate with the Geodesic Platform using the CLI

  • Setup your first project

  • Add a dataset to your project

  • Create a simple map

Total running time of the script: (0 minutes 5.973 seconds)

Gallery generated by Sphinx-Gallery