API

The core API client for interacting with the Geobox.

class HttpMethods

A class to represent HTTP methods.

class _RequestSession(access_token=None)

A custom session class that maintains headers and authentication state.

__init__(access_token=None)

Initialize the session with authentication.

Parameters:

• access_token (str, optional) – Bearer token for authentication

• apikey (str, optional) – API key for authentication

update_access_token(access_token)

Update the access token of the session.

Parameters:

access_token (str) – The new access token

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.update_access_token(access_token="new_access_token")

_manage_headers_for_request(files=None, is_json=True)

Manages headers for different types of requests.

Parameters:

• files (dict, optional) – Files to upload

• is_json (bool, optional) – Whether payload is JSON

Returns:

Original content type if it was modified

Return type:

str

request(method, url, verify=True, **kwargs)

Override request method with header management.

Parameters:

• method (str) – HTTP method

• url (str) – Request URL

• **kwargs – Additional request parameters

• verify (bool)

Returns:

Response object

Return type:

requests.Response

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.request(method="GET", url="https://api.geobox.ir/v1/layers/")

class GeoboxClient(host='https://api.geobox.ir', ver='v1/', username=None, password=None, access_token=None, apikey=None, verify=True)

A class to interact with the Geobox API.

Parameters:

• host (str)

• ver (str)

• username (str)

• password (str)

• access_token (str)

• apikey (str)

• verify (bool)

__init__(host='https://api.geobox.ir', ver='v1/', username=None, password=None, access_token=None, apikey=None, verify=True)

Constructs all the necessary attributes for the Api object.

You can set these parameters in the environment variables to avoid passing them as arguments:

• GEOBOX_USERNAME

• GEOBOX_PASSWORD

• GEOBOX_ACCESS_TOKEN

• GEOBOX_APIKEY

• DEBUG

You can set the DEBUG to True to set the logging level to DEBUG.

Parameters:

• host (str) – API host URL

• ver (str) – API version

• username (str, optional) – Username for authentication

• password (str, optional) – Password for authentication

• access_token (str, optional) – Bearer token for authentication

• apikey (str, optional) – API key for authentication

• verify (bool, optional) – it controls whether to verify the server’s TLS certificate. Defaults to True. When set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify to False may be useful during local development or testing

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient(host="https://api.geobox.ir", ver="v1/",
                            username="username",
                            password="password")
>>> client = GeoboxClient(apikey="apikey")
>>> client = GeoboxClient(access_token="access_token")

__repr__()

Return a string representation of the GeoboxClient object.

Returns:

A string representation of the GeoboxClient object.

Return type:

str

get_access_token()

Obtains an access token using the username and password.

Returns:

The access token.

Return type:

str

Raises:

AuthenticationError – If there is an error obtaining the access token.

_parse_error_message(response)

Parse error message from API response.

Parameters:

response (requests.Response) – The API response object.

Returns:

The parsed error message.

Return type:

str

_handle_error(response)

Handle API error response.

Parameters:

response (requests.Response) – The API response object.

Raises:

• AuthenticationError – If authentication fails (401)

• AuthorizationError – If access is forbidden (403)

• NotFoundError – If resource is not found (404)

• ValidationError – If request validation fails (422)

• ServerError – If server error occurs (500+)

Return type:

None

_make_request(method, endpoint, payload=None, is_json=True, files=None, stream=None)

Makes an HTTP request to the API using the session.

Parameters:

• method (str) – HTTP method

• endpoint (str) – API endpoint

• payload (dict, optional) – Request payload

• is_json (bool, optional) – Whether payload is JSON

• files (dict, optional) – Files to upload

• stream (bool, optional) – Whether to stream response

Return type:

dict

get(endpoint, stream=False)

Sends a GET request to the API.

Parameters:

• endpoint (str) – The API endpoint.

• stream (bool)

Returns:

The response data.

Return type:

Dict

post(endpoint, payload=None, is_json=True, files=None)

Sends a POST request to the API.

Parameters:

• endpoint (str) – The API endpoint.

• payload (Dict, optional) – The data to send with the request.

• is_json (bool, optional) – Whether the payload is in JSON format.

Returns:

The response data.

Return type:

Dict

put(endpoint, payload, is_json=True)

Sends a PUT request to the API.

Parameters:

• endpoint (str) – The API endpoint.

• payload (Dict) – The data to send with the request.

• is_json (bool, optional) – Whether the payload is in JSON format.

Returns:

The response data.

Return type:

Dict

delete(endpoint, payload=None, is_json=None)

Sends a DELETE request to the API.

Parameters:

• endpoint (str) – The API endpoint.

• payload (Dict)

• is_json (bool)

Returns:

The response data.

Return type:

Dict

get_vectors(**kwargs)

Get a list of vector layers with optional filtering and pagination.

Keyword Arguments:

• include_settings (bool) – Whether to include layer settings. Default is False.

• temporary (bool) – Whether to return temporary layers, default is False

• q (str) – Query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – Search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – Comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of layers to skip. default is 0.

• limit (int) – Maximum number of layers to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared layers. default is False.

Returns:

A list of VectorLayer instances or the layers count if return_count is True.

Return type:

List[VectorLayer] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layers = client.get_vectors(include_settings=True,
...                                 skip=0,
...                                 limit=100,
...                                 return_count=False,
...                                 search="my_layer",
...                                 search_fields="name, description",
...                                 order_by="name",
...                                 shared=True)

get_vector(uuid, user_id=None)

Get a specific vector layer by its UUID.

Parameters:

• uuid (str) – The UUID of the layer to retrieve.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The requested layer instance.

Return type:

VectorLayer

Raises:

NotFoundError – If the layer with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")

get_vectors_by_ids(ids, user_id=None, include_settings=False)

Get vector layers by their IDs.

Parameters:

• ids (List[int]) – The IDs of the layers to retrieve.

• user_id (int, optional) – Specific user. privileges required.

• include_settings (bool, optional) – Whether to include the layer settings. default is False.

Returns:

The list of VectorLayer instances.

Return type:

List[VectorLayer]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layers = client.get_vectors_by_ids(ids=[1, 2, 3])

create_vector(name, layer_type, display_name=None, description=None, has_z=False, temporary=False, fields=None)

Create a new vector layer.

Parameters:

• name (str) – The name of the layer.

• layer_type (LayerType) – The type of geometry to store.

• display_name (str, optional) – A human-readable name for the layer. default is None.

• description (str, optional) – A description of the layer. default is None.

• has_z (bool, optional) – Whether the layer includes Z coordinates. default is False.

• temporary (bool, optional) – Whether to create a temporary layer. temporary layers will be deleted after 24 hours. default is False.

• fields (List, optional) – List of field definitions for the layer. default is None.

Returns:

The newly created layer instance.

Return type:

VectorLayer

Raises:

ValidationError – If the layer data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.create_vector(name="my_layer",
...                                 layer_type=LayerType.Point,
...                                 display_name="My Layer",
...                                 description="This is a description of my layer",
...                                 has_z=False,
...                                 fields=[{"name": "my_field", "datatype": "FieldTypeString"}])

get_vector_by_name(name, user_id=None)

Get a vector layer by name

Parameters:

• name (str) – the name of the vector to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the vector if a vector matches the given name, else None

Return type:

VectorLayer | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector_by_name(name='test')

get_files(**kwargs)

Retrieves a list of files.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D.NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – if true, the total number of results will be returned. default is False.

• skip (int) – number of results to skip. default is 0.

• limit (int) – number of results to return. default is 10.

• user_id (int) – filter by user id.

• shared (bool) – Whether to return shared files. default is False.

Returns:

A list of File objects or the total number of results.

Return type:

List[File] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> files = client.get_files(search_fields='name', search='GIS', order_by='name', skip=10, limit=10)

get_file(uuid)

Retrieves a file by its UUID.

Parameters:

uuid (str, optional) – The UUID of the file.

Returns:

The retrieved file instance.

Return type:

File

Raises:

NotFoundError – If the file with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> file = client.get_file(uuid="12345678-1234-5678-1234-567812345678")

get_files_by_name(name, user_id=None)

Get files by name

Parameters:

• name (str) – the name of the file to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns files that matches the given name

Return type:

List[File]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> files = client.get_files_by_name(name='test')

upload_file(path, user_id=None, scan_archive=True)

Upload a file to the GeoBox API.

Parameters:

• path (str) – The path to the file to upload.

• user_id (int, optional) – specific user. privileges required.

• scan_archive (bool, optional) – Whether to scan the archive for layers. default: True

Returns:

The uploaded file instance.

Return type:

File

Raises:

• ValueError – If the file type is invalid.

• FileNotFoundError – If the file does not exist.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> file = client.upload_file(path='path/to/file.shp')

get_tasks(**kwargs)

Get a list of tasks

Keyword Arguments:

• state (TaskStatus) – Available values : TaskStatus.PENDING, TaskStatus.PROGRESS, TaskStatus.SUCCESS, TaskStatus.FAILURE, TaskStatus.ABORTED

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – The count of the tasks. default is False.

• skip (int) – The skip of the task. default is 0.

• limit (int) – The limit of the task. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared tasks. default is False.

Returns:

The list of task objects or the count of the tasks if return_count is True.

Return type:

List[Task] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tasks = client.get_tasks()

get_task(uuid)

Gets a task.

Parameters:

uuid (str) – The UUID of the task.

Returns:

The task object.

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> task = client.get_task(uuid="12345678-1234-5678-1234-567812345678")

get_views(**kwargs)

Get vector layer views.

Keyword Arguments:

• layer_id (int) – The id of the layer.

• include_settings (bool) – Whether to include the settings of the layer. default is False.

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – Comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return the count of the layer views. default is False.

• skip (int) – The number of layer views to skip. minimum is 0.

• limit (int) – The maximum number of layer views to return. minimum is 1. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared views. default is False.

Returns:

A list of VectorLayerView instances or the layer views count if return_count is True.

Return type:

list[VectorLayerView] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> views = client.get_views(layer_id=1,
...                             include_settings=True,
...                             search="test",
...                             search_fields="name",
...                             order_by="name A",
...                             return_count=False,
...                             skip=0,
...                             limit=10,
...                             shared=True)

get_views_by_ids(ids, user_id=None, include_settings=False)

Get vector layer views by their IDs.

Parameters:

• ids (List[int]) – list of comma separated layer ids to be returned. e.g. 1, 2, 3

• user_id (int, optional) – specific user. privileges required.

• include_settings (bool, optional) – Whether to include the settings of the vector layer views. default is False.

Returns:

A list of VectorLayerView instances.

Return type:

List[VectorLayerView]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> views = client.get_views_by_ids(ids=[1,2,3])

get_view(uuid, user_id=None)

Get a specific vector layer view by its UUID.

Parameters:

• uuid (str) – The UUID of the vector layer view.

• user_id (int, optional) – Specific user. privileges required.

Returns:

A VectorLayerView instance.

Return type:

VectorLayerView

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> view = client.get_view(uuid="12345678-1234-5678-1234-567812345678")

get_view_by_name(name, user_id=None)

Get a view by name

Parameters:

• name (str) – the name of the view to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the view if a view matches the given name, else None

Return type:

VectorLayerView | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> view = client.get_view_by_name(name='test')

create_tileset(name, layers, display_name=None, description=None, min_zoom=None, max_zoom=None, user_id=None)

Create a new tileset.

Parameters:

• name (str) – The name of the tileset.

• layers (List['VectorLayer' | 'VectorLayerView']) – list of vectorlayer and view objects to add to tileset.

• display_name (str, optional) – The display name of the tileset.

• description (str, optional) – The description of the tileset.

• min_zoom (int, optional) – The minimum zoom level of the tileset.

• max_zoom (int, optional) – The maximum zoom level of the tileset.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The created tileset instance.

Return type:

Tileset

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> view = client.get_view(uuid="12345678-1234-5678-1234-567812345678")
>>> tileset = client.create_tileset(name="your_tileset_name",
...                                     display_name="Your Tileset",
...                                     description="Your description",
...                                     min_zoom=0,
...                                     max_zoom=14,
...                                     layers=[layer, view])

get_tilesets(**kwargs)

Retrieves a list of tilesets.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – if True, returns the total number of tilesets matching the query. default is False.

• skip (int) – number of records to skip. default is 0.

• limit (int) – number of records to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared tilesets. default is False.

Returns:

A list of Tileset instances or the total number of tilesets

Return type:

List[Tileset] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tilesets = client.get_tilesets(q="name LIKE '%your_tileset_name%'",
...     order_by="name A",
...     skip=0,
...     limit=10,
... )

get_tilesets_by_ids(ids, user_id=None)

Retrieves a list of tilesets by their IDs.

Parameters:

• ids (List[str]) – The list of tileset IDs.

• user_id (int, optional) – Specific user. privileges required.

Returns:

A list of Tileset instances.

Return type:

List[Tileset]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tilesets = client.get_tilesets_by_ids(ids=['123', '456'])

get_tileset(uuid)

Retrieves a tileset by its UUID.

Parameters:

uuid (str) – The UUID of the tileset.

Returns:

The retrieved tileset instance.

Return type:

Tileset

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tileset = client.get_tileset(uuid="12345678-1234-5678-1234-567812345678")

get_tileset_by_name(name, user_id=None)

Get a tileset by name

Parameters:

• name (str) – the name of the tileset to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the tileset if a tileset matches the given name, else None

Return type:

Tileset | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tileset = client.get_tileset_by_name(name='test')

get_rasters(**kwargs)

Get all rasters.

Keyword Arguments:

• terrain (bool) – whether to get terrain rasters.

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – whether to return the total count of rasters. default is False.

• skip (int) – number of rasters to skip. minimum is 0.

• limit (int) – number of rasters to return. minimum is 1.

• user_id (int) – user id to show the rasters of the user. privileges required.

• shared (bool) – whether to return shared rasters. default is False.

Returns:

A list of Raster objects or the total count of rasters.

Return type:

List[Raster] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> rasters = client.get_rasters(terrain=True, q="name LIKE '%GIS%'")

get_rasters_by_ids(ids, user_id=None)

Get rasters by their IDs.

Parameters:

• ids (List[str]) – The IDs of the rasters.

• user_id (int, optional) – specific user. privileges required.

Returns:

A list of Raster objects.

Return type:

List[‘Raster’]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> rasters = client.get_rasters_by_ids(ids=['123', '456'])

get_raster(uuid)

Get a raster by its UUID.

Parameters:

• uuid (str) – The UUID of the raster.

• user_id (int, optional) – specific user. privileges required.

Returns:

A Raster object.

Return type:

Raster

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> raster = client.get_raster(uuid="12345678-1234-5678-1234-567812345678")

get_raster_by_name(name, user_id=None)

Get a raster by name

Parameters:

• name (str) – the name of the raster to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the raster if a raster matches the given name, else None

Return type:

Raster | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> raster = client.get_raster_by_name(name='test')

get_mosaics(**kwargs)

Get a list of mosaics.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”.

• seacrh (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – if true, the number of mosaics will be returned.

• skip (int) – number of mosaics to skip. minimum value is 0.

• limit (int) – maximum number of mosaics to return. minimum value is 1.

• user_id (int) – specific user. privileges required.

• shared (bool) – Whether to return shared mosaics. default is False.

Returns:

A list of Mosaic instances or the number of mosaics.

Return type:

List[‘Mosaic’] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> mosaics = client.get_mosaics(q="name LIKE '%GIS%'")

get_mosaics_by_ids(ids, user_id=None)

Get mosaics by their IDs.

Parameters:

• ids (List[str]) – The IDs of the mosaics.

• user_id (int, optional) – specific user. privileges required.

Returns:

A list of Mosaic instances.

Return type:

List[Mosaic]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> mosaics = client.get_mosaics_by_ids(ids=['1, 2, 3'])

create_mosaic(name, display_name=None, description=None, pixel_selection=None, min_zoom=None, user_id=None)

Create New Raster Mosaic

Parameters:

• name (str) – The name of the mosaic.

• display_name (str, optional) – The display name of the mosaic.

• description (str, optional) – The description of the mosaic.

• pixel_selection (str, optional) – The pixel selection of the mosaic.

• min_zoom (int, optional) – The minimum zoom of the mosaic.

• user_id (int, optional) – specific user. privileges required.

Returns:

The created mosaic.

Return type:

Mosaic

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> mosaic = client.create_mosaic(name='mosaic_name')

get_mosaic(uuid, user_id=None)

Get a mosaic by uuid.

Parameters:

• uuid (str) – The UUID of the mosaic.

• user_id (int, optional) – specific user. privileges required.

Returns:

The mosaic object.

Return type:

Mosaic

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> mosaic = client.get_mosaic(uuid="12345678-1234-5678-1234-567812345678")

get_mosaic_by_name(name, user_id=None)

Get a mosaic by name

Parameters:

• name (str) – the name of the mosaic to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the mosaic if a mosaic matches the given name, else None

Return type:

Mosaic | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> mosaic = client.get_mosaic_by_name(name='test')

get_models(**kwargs)

Get a list of models with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”.

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – whether to return total count. default is False.

• skip (int) – number of models to skip. default is 0.

• limit (int) – maximum number of models to return. default is 10.

• user_id (int) – specific user. privileges required.

• shared (bool) – Whether to return shared models. default is False.

Returns:

A list of Model objects or the count number.

Return type:

List[Model] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> models = client.get_models(search="my_model",
...                           search_fields="name, description",
...                           order_by="name A",
...                           return_count=True,
...                           skip=0,
...                           limit=10,
...                           shared=False)

get_model(uuid, user_id=None)

Get a model by its UUID.

Parameters:

• uuid (str) – The UUID of the model to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The model object.

Return type:

Model

Raises:

NotFoundError – If the model with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> model = client.get_model(uuid="12345678-1234-5678-1234-567812345678")

get_model_by_name(name, user_id=None)

Get a model by name

Parameters:

• name (str) – the name of the model to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the model if a model matches the given name, else None

Return type:

Model | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> model = client.get_model_by_name(name='test')

get_maps(**kwargs)

Get list of maps with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared maps. default is False.

Returns:

A list of Map instances or the total number of maps.

Return type:

List[Map] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> maps = client.get_maps(q="name LIKE '%My Map%'")

create_map(name, display_name=None, description=None, extent=None, thumbnail=None, style=None, user_id=None)

Create a new map.

Parameters:

• name (str) – The name of the map.

• display_name (str, optional) – The display name of the map.

• description (str, optional) – The description of the map.

• extent (List[float], optional) – The extent of the map.

• thumbnail (str, optional) – The thumbnail of the map.

• style (Dict, optional) – The style of the map.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The newly created map instance.

Return type:

Map

Raises:

ValidationError – If the map data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> map = client.create_map(name="my_map", display_name="My Map", description="This is a description of my map", extent=[10, 20, 30, 40], thumbnail="https://example.com/thumbnail.png", style={"type": "style"})

get_map(uuid, user_id=None)

Get a map by its UUID.

Parameters:

• uuid (str) – The UUID of the map to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The map object.

Return type:

Map

Raises:

NotFoundError – If the map with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> map = client.get_map(uuid="12345678-1234-5678-1234-567812345678")

get_map_by_name(name, user_id=None)

Get a map by name

Parameters:

• name (str) – the name of the map to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the map if a map matches the given name, else None

Return type:

Map | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> map = client.get_map_by_name(name='test')

get_queries(**kwargs)

Get Queries

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of queries to skip. default is 0.

• limit (int) – Maximum number of queries to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared queries. default is False.

Returns:

list of queries or the number of queries.

Return type:

List[Query] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> queries = client.get_queries()

create_query(name, display_name=None, description=None, sql=None, params=None)

Creates a new query.

Parameters:

• name (str) – The name of the query.

• display_name (str, optional) – The display name of the query.

• description (str, optional) – The description of the query.

• sql (str, optional) – The SQL statement for the query.

• params (list, optional) – The parameters for the SQL statement.

Returns:

The created query instance.

Return type:

Query

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> query = client.create_query(name='query_name', display_name='Query Name', sql='SELECT * FROM some_layer')

get_query(uuid, user_id=None)

Retrieves a query by its UUID.

Parameters:

• uuid (str) – The UUID of the query.

• user_id (int, optional) – specific user ID. privileges required.

Returns:

The retrieved query instance.

Return type:

Query

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")

get_query_by_name(name, user_id=None)

Get a query by name

Parameters:

• name (str) – the name of the query to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the query if a query matches the given name, else None

Return type:

Query | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> query = client.get_query_by_name(name='test')

get_system_queries(**kwargs)

Returns the system queries as a list of Query objects.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”.

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – whether to return the total count of queries. default is False.

• skip (int) – number of queries to skip. minimum is 0. default is 0.

• limit (int) – number of queries to return. minimum is 1. default is 100.

• user_id (int) – specific user. privileges required.

• shared (bool) – whether to return shared queries. default is False.

Returns:

list of system queries.

Return type:

List[Query]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> queries = client.get_system_queries()

get_users(**kwrags)

Retrieves a list of users (Permission Required)

Keyword Arguments:

• status (UserStatus) – the status of the users filter.

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared maps. default is False.

Returns:

list of users or the count number.

Return type:

List[User] | int

Example

>>> from geobox import Geoboxclient
>>> client = GeoboxClient()
>>> users = client.get_users()

create_user(username, email, password, role, first_name, last_name, mobile, status)

Create a User (Permission Required)

Parameters:

• username (str) – the username of the user.

• email (str) – the email of the user.

• password (str) – the password of the user.

• role (UserRole) – the role of the user.

• first_name (str) – the firstname of the user.

• last_name (str) – the lastname of the user.

• mobile (str) – the mobile number of the user. e.g. “+98 9120123456”.

• status (UserStatus) – the status of the user.

Returns:

the user object.

Return type:

User

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> user = client.create_user(username="user1",
...                             email="user1@example.com",
...                             password="P@ssw0rd",
...                             role=UserRole.ACCOUNT_ADMIN,
...                             first_name="user 1",
...                             last_name="user 1",
...                             mobile="+98 9120123456",
...                             status=UserStatus.ACTIVE)

search_users(search=None, skip=0, limit=10)

Get list of users based on the search term.

Parameters:

• search (str, optional) – The Search Term.

• skip (int, optional) – Number of items to skip. default is 0.

• limit (int, optional) – Number of items to return. default is 10.

Returns:

A list of User instances.

Return type:

List[User]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> users = client.get_users(search="John")

get_user(user_id='me')

Get a user by its id (Permission Required)

Parameters:

user_id (int, optional) – Specific user. don’t specify a user_id to get the current user.

Returns:

the user object.

Return type:

User

Raises:

NotFoundError – If the user with the specified id is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> user = client.get_user(user_id=1)
get the current user
>>> user = client.get_user()

get_my_sessions()

Get a list of user available sessions (Permission Required)

Returns:

list of user sessions.

Return type:

List[Session]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.get_my_sessions()

get_workflows(**kwargs)

Get list of workflows with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared workflows. default is False.

Returns:

A list of workflow instances or the total number of workflows.

Return type:

List[Workflow] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> workflows = client.get_workflows(q="name LIKE '%My workflow%'")

create_workflow(name, display_name=None, description=None, settings={}, thumbnail=None, user_id=None)

Create a new workflow.

Parameters:

• name (str) – The name of the Workflow.

• display_name (str) – The display name of the workflow.

• description (str) – The description of the workflow.

• settings (Dict) – The settings of the workflow.

• thumbnail (str) – The thumbnail of the workflow.

• user_id (int) – Specific user. privileges workflow.

Returns:

The newly created workflow instance.

Return type:

Workflow

Raises:

ValidationError – If the workflow data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> workflow = client.create_workflow(name="my_workflow")

get_workflow(uuid, user_id=None)

Get a workflow by its UUID.

Parameters:

• uuid (str) – The UUID of the workflow to get.

• user_id (int) – Specific user. privileges required.

Returns:

The workflow object.

Return type:

Workflow

Raises:

NotFoundError – If the workflow with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> workflow = client.get_workflow(uuid="12345678-1234-5678-1234-567812345678")

get_workflow_by_name(name, user_id=None)

Get a workflow by name

Parameters:

• name (str) – the name of the workflow to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the workflow if a workflow matches the given name, else None

Return type:

Workflow | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> workflow = client.get_workflow_by_name(name='test')

get_versions(**kwargs)

Get list of versions with optional filtering and pagination.

Keyword Arguments:

• layer_id (str) – the id of the vector layer.

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared versions. default is False.

Returns:

A list of vector layer version instances or the total number of versions.

Return type:

List[VectorLayerVersion] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> versions = client.get_versions(q="name LIKE '%My version%'")

get_version(uuid, user_id=None)

Get a version by its UUID.

Parameters:

• uuid (str) – The UUID of the version to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The vector layer version object.

Return type:

VectorLayerVersion

Raises:

NotFoundError – If the version with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> version = client.get_version(uuid="12345678-1234-5678-1234-567812345678")

get_version_by_name(name, user_id=None)

Get a version by name

Parameters:

• name (str) – the name of the version to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the version if a version matches the given name, else None

Return type:

VectorLayerVersion | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> version = client.get_version_by_name(name='test')

get_layouts(**kwargs)

Get list of layouts with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared layouts. default is False.

Returns:

A list of layout instances or the total number of layouts.

Return type:

List[Layout] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layouts = client.get_layouts(q="name LIKE '%My layout%'")

create_layout(name, display_name=None, description=None, settings={}, thumbnail=None, user_id=None)

Create a new layout.

Parameters:

• name (str) – The name of the layout.

• display_name (str) – The display name of the layout.

• description (str) – The description of the layout.

• settings (Dict) – The settings of the layout.

• thumbnail (str) – The thumbnail of the layout.

• user_id (int) – Specific user. privileges layout.

Returns:

The newly created layout instance.

Return type:

Layout

Raises:

ValidationError – If the layout data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layout = client.create_layout(name="my_layout")

get_layout(uuid, user_id=None)

Get a layout by its UUID.

Parameters:

• uuid (str) – The UUID of the layout to get.

• user_id (int) – Specific user. privileges required.

Returns:

The layout object.

Return type:

Layout

Raises:

NotFoundError – If the layout with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layout = client.get_layout(uuid="12345678-1234-5678-1234-567812345678")

get_layout_by_name(name, user_id=None)

Get a layout by name

Parameters:

• name (str) – the name of the layout to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the layout if a layout matches the given name, else None

Return type:

Layout | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layout = client.get_layout_by_name(name='test')

get_3dtiles(**kwargs)

Get list of 3D Tiles with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared maps. default is False.

Returns:

A list of 3D Tile instances or the total number of 3D Tiles.

Return type:

List[Tile3d] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tiles = client.get_3dtiles(q="name LIKE '%My tile%'")

get_3dtile(uuid, user_id=None)

Get a 3D Tile by its UUID.

Parameters:

• uuid (str) – The UUID of the map to 3D Tile.

• user_id (int) – Specific user. privileges required.

Returns:

The 3D Tile object.

Return type:

Tile3d

Raises:

NotFoundError – If the 3D Tile with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tile = client.get_3dtile(uuid="12345678-1234-5678-1234-567812345678")

get_3dtile_by_name(name, user_id=None)

Get a 3dtile by name

Parameters:

• name (str) – the name of the 3dtile to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the 3dtile if a 3dtile matches the given name, else None

Return type:

Tile3d | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tile3d = client.get_3dtile_by_name(name='test')

get_system_settings()

Get System Settings object (Permission Required).

Returns:

the system settings object.

Return type:

SystemSetting

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> setting = client.get_system_settings()

get_scenes(**kwargs)

Get list of scenes with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared scenes. default is False.

Returns:

A list of scene instances or the total number of scenes.

Return type:

List[Scene] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> scenes = client.get_scenes(q="name LIKE '%My scene%'")

create_scene(name, display_name=None, description=None, settings={}, thumbnail=None, user_id=None)

Create a new scene.

Parameters:

• name (str) – The name of the scene.

• display_name (str, optional) – The display name of the scene.

• description (str, optional) – The description of the scene.

• settings (Dict,optional) – The settings of the scene.

• thumbnail (str, optional) – The thumbnail of the scene.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The newly created scene instance.

Return type:

Scene

Raises:

ValidationError – If the scene data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> scene = client.create_scene(name="my_scene")

get_scene(uuid, user_id=None)

Get a scene by its UUID.

Parameters:

• uuid (str) – The UUID of the scene to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The scene object.

Return type:

Scene

Raises:

NotFoundError – If the scene with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> scene = client.get_scene(uuid="12345678-1234-5678-1234-567812345678")

get_scene_by_name(name, user_id=None)

Get a scene by name

Parameters:

• name (str) – the name of the scene to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the scene if a scene matches the given name, else None

Return type:

Scene | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> scene = client.get_scene_by_name(name='test')

route(stops, **kwargs)

Find best driving routes between coordinates and return results.

Parameters:

stops (str) – Comma-separated list of stop coordinates in the format lon,lat;lon,lat.

Keyword Arguments:

• alternatives (bool) – Whether to return alternative routes. Default value : False.

• steps (bool) – Whether to include step-by-step navigation instructions. Default value : False.

• geometries (RoutingGeometryType) – Format of the returned geometry.

• overview (RoutingOverviewLevel) – Level of detail in the returned geometry.

• annotations (bool) – Whether to include additional metadata like speed, weight, etc.

Returns:

the routing output

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> route = client.route(stops="53,33;56,36",
...                         alternatives=True,
...                         steps=True,
...                         geometries=RoutingGeometryType.geojson,
...                         overview=RoutingOverviewLevel.full,
...                         annotations=True)

get_plans(**kwargs)

Get list of plans with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared plans. default is False.

Returns:

A list of plan instances or the total number of plans.

Return type:

List[Plan] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> plans = client.get_plans(q="name LIKE '%My plan%'")

create_plan(name, plan_color, storage, concurrent_tasks, daily_api_calls, monthly_api_calls, daily_traffic, monthly_traffic, daily_process, monthly_process, number_of_days=None, display_name=None, description=None)

Create a new plan.

Parameters:

• name (str) – The name of the plan.

• plan_color (str) – hex value of the color. e.g. #000000.

• storage (int) – storage value in bytes. must be greater that 1.

• concurrent_tasks (int) – number of concurrent tasks. must be greater that 1.

• daily_api_calls (int) – number of daily api calls. must be greater that 1.

• monthly_api_calls (int) – number of monthly api calls. must be greater that 1.

• daily_traffic (int) – number of daily traffic. must be greater that 1.

• monthly_traffic (int) – number of monthly traffic. must be greater that 1.

• daily_process (int) – number of daily processes. must be greater that 1.

• monthly_process (int) – number of monthly processes. must be greater that 1.

• number_of_days (int, optional) – number of days. must be greater that 1.

• display_name (str, optional) – display name of the plan.

• description (str, optional) – description of the plan.

Returns:

The newly created plan instance.

Return type:

Plan

Raises:

ValidationError – If the plan data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> plan = client.create_plan(name="new_plan",
...                             display_name=" New Plan",
...                             description="new plan description",
...                             plan_color="#000000",
...                             storage=10,
...                             concurrent_tasks=10,
...                             daily_api_calls=10,
...                             monthly_api_calls=10,
...                             daily_traffic=10,
...                             monthly_traffic=10,
...                             daily_process=10,
...                             monthly_process=10,
...                             number_of_days=10)

get_plan(plan_id)

Get a plan by its id.

Parameters:

plan_id (int) – The id of the plan to get.

Returns:

The plan object

Return type:

Plan

Raises:

NotFoundError – If the plan with the specified id is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> plan = client.get_plan(plan_id=1)

get_plan_by_name(name)

Get a plan by name

Parameters:

• api (GeoboxClient) – The GeoboxClient instance for making requests.

• name (str) – the name of the plan to get

Returns:

returns the plan if a plan matches the given name, else None

Return type:

Plan | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> plan = client.get_plan_by_name(name='test')

get_dashboards(**kwargs)

Get list of Dashboards

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

• search_fields (str) – comma separated list of fields for searching.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default is False.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. privileges required.

• shared (bool) – Whether to return shared Dashboards. default is False.

Returns:

A list of Dashboard instances or the total number of Dashboards.

Return type:

List[Dashboard] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> dashboards = client.get_dashboards()

create_dashboard(name, display_name=None, description=None, settings={}, thumbnail=None, user_id=None)

Create a new Dashboard.

Parameters:

• name (str) – The name of the Dashboard.

• display_name (str, optional) – The display name of the Dashboard.

• description (str, optional) – The description of the Dashboard.

• settings (Dict, optional) – The settings of the sceDashboarde.

• thumbnail (str, optional) – The thumbnail of the Dashboard.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The newly created Dashboard instance.

Return type:

Dashboard

Raises:

ValidationError – If the Dashboard data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> dashboard = client.create_dashboard(name="my_dashboard")

get_dashboard(uuid, user_id=None)

Get a Dashboard by its UUID.

Parameters:

• uuid (str) – The UUID of the Dashboard to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The dashboard object.

Return type:

Dashboard

Raises:

NotFoundError – If the Dashboard with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> dashboard = client.get_dashboard(uuid="12345678-1234-5678-1234-567812345678")

get_dashboard_by_name(name, user_id=None)

Get a dashboard by name

Parameters:

• name (str) – the name of the dashboard to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the dashboard if a dashboard matches the given name, else None

Return type:

Dashboard | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> dashboard = client.get_dashboard_by_name(name='test')

get_basemaps()

Get a list of basemaps

Returns:

list of basemaps.

Return type:

List[BaseMap]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> basemaps = client.get_basemaps()

get_basemap(name)

Get a basemap object

Parameters:

name (str) – the basemap name

Returns:

the basemap object

Return type:

Basemap

Raises:

NotFoundError – if the base,ap with the specified name not found

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> basemap = client.get_basemap(name='test')

proxy_basemap(url)

Proxy the basemap

Parameters:

url (str) – the proxy server url.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.proxy_basemap(url='proxy_server_url')

get_attachments(resource, **kwargs)

Get the resouces attachments

Parameters:

resource (Map | VectorLayer | VectorLayerView) – options are: Map, Vector, View objects

Keyword Arguments:

• element_id (str) – the id of the element with attachment.

• search (str) – search term for keyword-based searching among all textual fields.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• return_count (bool) – Whether to return total count. default is False.

Returns:

A list of attachments instances or the total number of attachments.

Return type:

List[Attachment] | int

Raises:

TypeError – if the resource type is not supported

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> map = client.get_maps()[0]
>>> attachments = client.get_attachments(resource=map)

create_attachment(name, loc_x, loc_y, resource, file, feature=None, display_name=None, description=None)

Create a new Attachment.

Parameters:

• name (str) – The name of the scene.

• loc_x (int) – x parameter of the attachment location.

• loc_y (int) – y parameter of the attachment location.

• resource (Map | VectorLayer | VectorLayerView) – the resource object.

• file (File) – the file object.

• feature (Feature, optional) – the feature object.

• display_name (str, optional) – The display name of the scene.

• description (str, optional) – The description of the scene.

Returns:

The newly created Attachment instance.

Return type:

Attachment

Raises:

ValidationError – If the Attachment data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(feature_id=1)
>>> file = client.get_file(uuid="12345678-1234-5678-1234-567812345678")
>>> attachment = client.create_attachment(name="my_attachment",
...                                             loc_x=30,
...                                             loc_y=50,
...                                             resource=layer,
...                                             file=file,
...                                             feature=feature,
...                                             display_name="My Attachment",
...                                             description="Attachment Description")

update_attachment(attachment_id, **kwargs)

Update the attachment.

Parameters:

attachment_id (int) – the attachment id.

Keyword Arguments:

• name (str) – The name of the attachment.

• display_name (str) – The display name of the attachment.

• description (str) – The description of the attachment.

• loc_x (int) – x parameter of the attachment location.

• loc_y (int) – y parameter of the attachment location.

Returns:

The updated attachment data.

Return type:

Dict

Raises:

ValidationError – If the attachment data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.update_attachment(attachment_id=1, display_name="New Display Name")

get_apikeys(**kwargs)

Get a list of apikeys

Keyword Arguments:

• search (str) – search term for keyword-based searching among all textual fields.

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• skip (int) – Number of layers to skip. default is 0.

• limit (int) – Maximum number of layers to return. default is 10.

• user_id (int) – Specific user. privileges required.

Return type:

List[ApiKey]

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> apikeys = client.get_apikeys()

create_apikey(name, user_id=None)

Create an ApiKey

Parameters:

• name (str) – name of the key.

• user_id (int, optional) – Specific user. privileges required.

Returns:

the apikey object

Return type:

ApiKey

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> apikey = client.create_apikey(name='test')

get_apikey(key_id)

Get an ApiKey

Parameters:

key_id (str) – the id of the apikey.

Returns:

the ApiKey object

Return type:

ApiKey

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> apikey = client.get_apikey(key_id=1)

get_apikey_by_name(name, user_id=None)

Get an ApiKey by name

Parameters:

• name (str) – the name of the key to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the key if a key matches the given name, else None

Return type:

ApiKey | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> apikey = client.get_apikey_by_name(name='test')

get_logs(**kwargs)

Get a list of Logs

Keyword Arguments:

• search (str) – search term for keyword-based searching among all textual fields

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• skip (int) – Number of items to skip. default is 0.

• limit (int) – Number of items to return. default is 10.

• user_id (int) – Specific user. Privileges required.

• from_date (datetime) – datetime object in this format: “%Y-%m-%dT%H:%M:%S.%f”.

• to_date (datetime) – datetime object in this format: “%Y-%m-%dT%H:%M:%S.%f”.

• user_identity (str) – the user identity in this format: username - firstname lastname - email .

• activity_type (str) – the user activity type.

Returns:

a list of logs

Return type:

List[Log]

Example

>>> from geobox import Geobox
>>> client = GeoboxClient()
>>> logs = client.get_logs()

get_api_usage(resource, scale, param, from_date=None, to_date=None, days_before_now=None, limit=None)

Get the api usage of a user

Parameters:

• resource (User | ApiKey) – User or ApiKey object.

• scale (UsageScale) – the scale of the report.

• param (UsageParam) – traffic or calls.

• from_date (datetime, optional) – datetime object in this format: “%Y-%m-%dT%H:%M:%S”.

• to_date (datetime, optional) – datetime object in this format: “%Y-%m-%dT%H:%M:%S”.

• days_before_now (int, optional) – number of days befor now.

• limit (int, optional) – Number of items to return. default is 10.

Raises:

• ValueError – one of days_before_now or from_date/to_date parameters must have value

• ValueError – resource must be a ‘user’ or ‘apikey’ object

Returns:

usage report

Return type:

List

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> user = client.get_user() # gets current user
>>> usage = client.get_api_usage(resource=user,
...                               scale=UsageScale.Day,
...                               param=UsageParam.Calls,
...                               days_before_now=5)

get_process_usage(user_id=None, from_date=None, to_date=None, days_before_now=None)

Get process usage of a user in seconds

Parameters:

• user_id (int, optional) – the id of the user. leave blank to get the current user report.

• from_date (datetime, optional) – datetime object in this format: “%Y-%m-%dT%H:%M:%S”.

• to_date (datetime, optional) – datetime object in this format: “%Y-%m-%dT%H:%M:%S”.

• days_before_now (int, optional) – number of days befor now.

Raises:

ValueError – one of days_before_now or from_date/to_date parameters must have value

Returns:

process usage of a user in seconds

Return type:

float

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> process_usage = client.get_process_usage(days_before_now=5)

get_usage_summary(user_id=None)

Get the usage summary of a user

Parameters:

user_id (int, optional) – the id of the user. leave blank to get the current user report.

Returns:

the usage summery of the users

Return type:

Dict

Returns:

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> usage_summary = client.get_usage_summary()

update_usage(user_id=None)

Update usage of a user

Parameters:

user_id (int, optional) – the id of the user. leave blank to get the current user report.

Returns:

the updated data

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> client.update_usage()

get_tables(**kwargs)

Get list of tables with optional filtering and pagination.

Keyword Arguments:

• include_settings (bool) – Whether to include table settings. default: False

• temporary (bool) – Whether to return temporary tables. default: False

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored

• search_fields (str) – comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default: False.

• skip (int) – Number of items to skip. default: 0

• limit (int) – Number of items to return. default: 10

• user_id (int) – Specific user. privileges required

• shared (bool) – Whether to return shared tables. default: False

Returns:

A list of table instances or the total number of tables.

Return type:

List[Table] | int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> tables = client.get_tables(q="name LIKE '%My table%'")

create_table(name, display_name=None, description=None, temporary=False, fields=None)

Create a new table.

Parameters:

• name (str) – The name of the Table.

• display_name (str, optional) – The display name of the table.

• description (str, optional) – The description of the table.

• temporary (bool, optional) – Whether to create a temporary tables. default: False

• fields (List[Dict], optional) – raw table fields. you can use add_field method for simpler and safer field addition. required dictionary keys: name, datatype

Returns:

The newly created table instance.

Return type:

Table

Raises:

ValidationError – If the table data is invalid.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> table = client.create_table(name="my_table")

get_table(uuid, user_id=None)

Get a table by UUID.

Parameters:

• uuid (str) – The UUID of the table to get.

• user_id (int) – Specific user. privileges required.

Returns:

The Table object.

Return type:

Table

Raises:

NotFoundError – If the table with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> table = client.get_table(uuid="12345678-1234-5678-1234-567812345678")

get_table_by_name(name, user_id=None)

Get a table by name

Parameters:

• name (str) – the name of the table to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the table if a table matches the given name, else None

Return type:

Table | None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> table = client.get_table_by_name(name='test')

get_relationships(**kwargs)

Get a list of relationships with optional filtering and pagination.

Keyword Arguments:

• q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

• search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored

• search_fields (str) – comma separated list of fields for searching

• order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

• return_count (bool) – Whether to return total count. default: False.

• skip (int) – Number of items to skip. default: 0

• limit (int) – Number of items to return. default: 10

• user_id (int) – Specific user. privileges required

• shared (bool) – Whether to return shared tables. default: False

Returns:

A list of relationship instances or the total number of relationships.

Return type:

List[Relationship] | int

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relatinship
>>> client = GeoboxClient()
>>> relationships = client.get_relationships(q="name LIKE '%My relationship%'")

create_relationship(name, cardinality, *, source, target, relation_table=None, display_name=None, description=None, user_id=None)

Create a new Relationship

Parameters:

• name (str) – name of the relationship

• cardinality (RelationshipCardinality) – One to One, One to Many, or Many to Many

• source (RelationshipEndpoint)

• target (RelationshipEndpoint)

• relation_table (Table | None)

• display_name (str | None)

• description (str | None)

• user_id (int | None)

Keyword Arguments:

• source (RelationshipEndpoint) – Definition of the source side of the relationship, including the table (or layer), field, and foreign-key field

• target (RelationshipEndpoint) – Definition of the target side of the relationship, including the table (or layer), field, and foreign-key field

• relation_table (Table, optional) – The table that stores the relationship metadata or join records. (Required for Many-to-Many relationships)

• display_name (str, optional) – Human-readable name for the relationship

• description (str, optional) – the description of the relationship

• user_id (int, optional) – Specific user. privileges required.

Returns:

a relationship instance

Return type:

Relationship

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import RelationshipEndpoint, RelationshipCardinality
>>> client = GeoboxClient()
>>> source = RelationshipEndpoint(
...     table=client.get_table_by_name('owner'),
...     field="name", # on source table
...     fk_field="book_name", # on relation table
... )
>>> target = RelationshipEndpoint(
...     table=client.get_table_by_name('parcel'),
...     field="name", # on target table
...     fk_field="author_name", # on relation table
... )
>>> relationship = client.create_relationship(
...     name="owner_parcel",
...     cardinality=RelationshipCardinality.ManytoMany,
...     source=source,
...     target=target,
...     relation_table=client.get_table_by_name('owner_parcel'),
... )

get_relationship(uuid, user_id=None)

Get a relationship by UUID.

Parameters:

• uuid (str) – The UUID of the relationship to get.

• user_id (int, optional) – Specific user. privileges required.

Returns:

The Relationship object.

Return type:

Relationship

Raises:

NotFoundError – If the Relationship with the specified UUID is not found.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")

get_relationship_by_name(name, user_id=None)

Get a relationship by name

Parameters:

• name (str) – the name of the relationship to get

• user_id (int, optional) – specific user. privileges required.

Returns:

returns the relationship if a relationship matches the given name, else None

Return type:

Relationship | None

Example

>>> from geobox import GeoboxClient
>>> from geobox.relationship import Relationship
>>> client = GeoboxClient()
>>> relationship = client.get_relationship_by_name(name='test')

get_database_tables(creds)

Get the list of tha database tables

Parameters:

creds (DBCredentials) – the database connection credentials

Returns:

list of the database tables

Return type:

List[DatabaseTable]

Example

>>> from geobox import GeoboxClient
>>> from geobox.db_connection import Database, DBCredentials, DBType
>>> client = GeoboxClient()
>>> creds = DBCredentials(...)
>>> tables = client.get_database_tables(creds)