Quick Start

Getting Started with Geobox python SDK

To begin using Geobox python SDK, you need to create a GeoboxClient object that authenticates with the Geobox API and provides access to different modules in the SDK.

Authentication

Direct Authentication

You can authenticate directly by passing your credentials to the GeoboxClient:

from geobox import GeoboxClient
client = GeoboxClient(username="username", password="password")

Once authenticated, you have access to the platform through the SDK:

layers = client.get_vectors()

Environment Variables

For better security and convenience, you can create a .env file and add your authentication information there, so you don’t need to pass them directly to the GeoboxClient.

Add these values to your .env file:

GEOBOX_USERNAME=your_username
GEOBOX_PASSWORD=your_password

With the environment variables set, you can initialize the client without parameters:

client = GeoboxClient()

For more authentication options, check .env.example and geobox.api.GeoboxClient.__init__() for detailed information.

Example Usage

Upload and Publish a Dataset

Upload a dataset, publish it, check the publish task status, and get the published vector layer:

Sync:

from geobox import GeoboxClient
from geobox.task import TaskStatus
from geobox.file import PublishFileType

client = GeoboxClient()

# Upload a file
file = client.upload_file(path=r'path/to/file')

# Publish the file
task = file.publish(layer_name='layer_name')

# Wait until the publish task is finished and check the result
if task.wait() == TaskStatus.SUCCESS:
    layer = task.output_asset  # vector layer, raster, or 3D model object

Async:

from geobox.aio import AsyncGeoboxClient
from geobox.aio.file import PublishFileType
from geobox.aio.task import TaskStatus

async with AsyncGeoboxClient() as client:
    # Upload a file
    file = await client.upload_file(path=r'path/to/file')

    # Publish the file
    task = await file.publish(layer_name='layer_name')

    # Wait until the publish task is finished and check the result
    task_result = await task.wait()
    if task_result == TaskStatus.SUCCESS:
        layer = await task.output_asset  # vector layer, raster, or 3D model object

Working with Vector Layers

Get a specific vector layer by searching for its name, then retrieve its features and fields:

Sync:

from geobox import GeoboxClient

client = GeoboxClient()
# Search for a layer by name
layer = client.get_vectors(search='layer_name')[0]

# Get features and fields
features = layer.get_features()
fields = layer.get_fields()

Async:

from geobox.aio import AsyncGeoboxClient

async with AsyncGeoboxClient() as client:
    # Search for a layer by name
    layer = await client.get_vectors(search='layer_name')[0]

    # Get features and fields
    features = await layer.get_features()
    fields = await layer.get_fields()

For more information on working with vector layers, check Vector Layer documentation and Async Vector Layer documentation.

Creating and Executing SQL Queries

Create a query to extract data from a layer using SQL:

Sync:

from geobox import GeoboxClient
from geobox.query import QueryParamType

client = GeoboxClient()
# Get a specific layer by UUID
layer = client.get_vector(uuid='layer_uuid')

# Create a new query
query = client.create_query(name='feature_count')
query.sql = 'SELECT COUNT(id) FROM layer'

# Add parameters to the query
query.add_param(name='layer', value=layer.uuid, type=QueryParamType.LAYER)

# Execute the query
query.execute()

Async:

from geobox.aio import AsyncGeoboxClient
from geobox.aio.query import QueryParamType

async with AsyncGeoboxClient() as client:
    # Get a specific layer by UUID
    layer = await client.get_vector(uuid='layer_uuid')

    # Create a new query
    query = await client.create_query(name='feature_count')
    query.sql = 'SELECT COUNT(id) FROM layer'

    # Add parameters to the query
    query.add_param(name='layer', value=layer.uuid, type=QueryParamType.LAYER)

    # Execute the query
    result = await query.execute()

For more information on queries, check Query documentation and Async Query documentation.

Vector Processing Tools and Raster Analysis

You can perform different analysis on vector layers and rasters.

Sync - Execute the vector tool:

from geobox import GeoboxClient

client = GeoboxClient()
# Get a specific layer by UUID
layer = client.get_vector(uuid='layer_uuid')

# add buffer to the layer
# execute
result = client.vector_tool.buffer(
    vector_uuid=layer.uuid,
    distance=1000
)

or execute and save the result as a new layer:

# save as new layer
task = client.vector_tool.buffer(
    vector_uuid=layer.uuid,
    distance=1000,
    output_asset='buffered_layer'
)
task.wait()
output_layer = task.output_asset

Async - Execute the vector tool:

from geobox.aio import AsyncGeoboxClient

async with AsyncGeoboxClient() as client:
    # Get a specific layer by UUID
    layer = await client.get_vector(uuid='layer_uuid')

    # add buffer to the layer
    # execute
    result = await client.vector_tool.buffer(
        vector_uuid=layer.uuid,
        distance=1000
    )

or execute and save the result as a new layer:

# save as new layer
task = await client.vector_tool.buffer(
    vector_uuid=layer.uuid,
    distance=1000,
    output_asset='buffered_layer'
)
task.wait()
output_layer = await task.output_asset