Map

The Map module provides functionality for working with maps.

class Map(api, uuid, data={})[source]

Bases: Base

Parameters:
BASE_ENDPOINT = 'maps/'
__init__(api, uuid, data={})[source]

Initialize a Map instance.

Parameters:

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

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

  • uuid (str) – The unique identifier for the map.

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

classmethod get_maps(api, **kwargs)[source]

Get list of maps with optional filtering and pagination.

Parameters:

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

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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> maps = Map.get_maps(client, q="name LIKE '%My Map%'")
or
>>> maps = client.get_maps(q="name LIKE '%My Map%'")
classmethod create_map(api, name, display_name=None, description=None, extent=None, thumbnail=None, style=None, user_id=None)[source]

Create a new map.

Parameters:

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

  • 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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.create_map(client, 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"})
or
>>> 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"})
classmethod get_map(api, uuid, user_id=None)[source]

Get a map by its UUID.

Parameters:

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

  • 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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> map = client.get_map(uuid="12345678-1234-5678-1234-567812345678")
classmethod get_map_by_name(api, name, user_id=None)[source]

Get a map by name

Parameters:

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

  • 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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map_by_name(client, name='test')
or
>>> map = client.get_map_by_name(name='test')
update(**kwargs)[source]

Update the map.

Keyword Arguments:

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

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

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

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

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

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

Returns:

The updated map data.

Return type:

Dict

Raises:

ValidationError – If the map data is invalid.

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.update(display_name="New Display Name")
delete()[source]

Delete the map.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.delete()
property style: Dict

Get the style of the map.

Returns:

The style of the map.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.style
property thumbnail: str

Get the thumbnail URL of the map.

Returns:

The thumbnail of the map.

Return type:

str

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.thumbnail
set_readonly(readonly)[source]

Set the readonly status of the map.

Parameters:

readonly (bool) – The readonly status of the map.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.set_readonly(True)
set_multiuser(multiuser)[source]

Set the multiuser status of the map.

Parameters:

multiuser (bool) – The multiuser status of the map.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.set_multiuser(True)
wmts(scale=None)[source]

Get the WMTS URL of the map.

Parameters:

scale (int) – The scale of the map. value are: 1, 2

Returns:

The WMTS URL of the map.

Return type:

str

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.wmts(scale=1)
share(users)[source]

Shares the map with specified users.

Parameters:

users (List[User]) – The list of user objects to share the map with.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> users = client.search_users(search='John')
>>> map.share(users=users)
unshare(users)[source]

Unshares the map with specified users.

Parameters:

users (List[User]) – The list of user objects to unshare the map with.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> users = client.search_users(search='John')
>>> map.unshare(users=users)
get_shared_users(search=None, skip=0, limit=10)[source]

Retrieves the list of users the map is shared with.

Parameters:

  • search (str, optional) – The search query.

  • skip (int, optional) – The number of users to skip.

  • limit (int, optional) – The maximum number of users to retrieve.

Returns:

The list of shared users.

Return type:

List[User]

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.get_shared_users(search='John', skip=0, limit=10)
seed_cache(from_zoom=None, to_zoom=None, extent=None, workers=1, user_id=None, scale=None)[source]

Seed the cache of the map.

Parameters:

  • from_zoom (int, optional) – The zoom level to start caching from.

  • to_zoom (int, optional) – The zoom level to stop caching at.

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

  • workers (int, optional) – The number of workers to use. default is 1.

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

  • scale (int, optional) – The scale of the map.

Returns:

The task instance of the cache seeding operation.

Return type:

List[Task]

Raises:

  • ValueError – If the workers is not in [1, 2, 4, 8, 12, 16, 20, 24].

  • ValueError – If the cache seeding fails.

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> task = map.seed_cache(from_zoom=0, to_zoom=10, extent=[10, 20, 30, 40], workers=1, scale=1)
update_cache(from_zoom=None, to_zoom=None, extent=None, user_id=None, scale=None)[source]

Update the cache of the map.

Parameters:

  • from_zoom (int, optional) – The zoom level to start caching from.

  • to_zoom (int, optional) – The zoom level to stop caching at.

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

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

  • scale (int, optional) – The scale of the map.

Returns:

The task instance of the cache updating operation.

Return type:

List[Task]

Raises:

ValueError – If the cache updating fails.

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.update_cache(from_zoom=0, to_zoom=10, extent=[10, 20, 30, 40], scale=1)
clear_cache()[source]

Clear the cache of the map.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.clear_cache()
property cache_size: int

Get the size of the cache of the map.

Returns:

The size of the cache of the map.

Return type:

int

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.cache_size
property settings: Dict

Get the settings of the map

Returns:

the settings of the map.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(uuid="12345678-1234-5678-1234-567812345678")
>>> map.settings
update_settings(settings)[source]

Update the settings

settings (Dict): settings dictionary

Returns:

updated settings

Return type:

Dict

Parameters:

settings (Dict)

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> map1 = client.get_map(uuid="12345678-1234-5678-1234-567812345678")
>>> map2 = client.get_map(uuid="12345678-1234-5678-1234-567812345678")
>>> map1.update_settings(map2.settings)
set_settings(**kwargs)[source]

Set the settings of the map using keywords

Keyword Arguments:

  • map_unit (str) – ‘latlng’ | ‘utm’.

  • base_map (str) – ‘OSM’ | ‘google’ | ‘blank’.

  • flash_color (str) – ‘rgb(255,0,0)’ (rgb color or rgba color or hex color ).

  • highlight_color (str) – ‘rgb(255,0,0)’ (rgb color or rgba color or hex color ).

  • selection_color (str) – ‘rgb(255,0,0)’ (rgb color or rgba color or hex color ).

  • selectable_layers (str) – ‘ALL’ | null | Comma separated list of layers.

  • calendar_type (str) – The type of the calendar.

  • edit_settings (dict) – The settings of the edit.

  • snap_tolerance (int) – number of pixels for snap tolerance.

  • snap_unit (str) – pixels.

  • snap_mode (str) – ‘both’ | ‘edge’ | ‘vertex’.

  • snap_cache (int) – number of total features for snap cache.

  • controls (List[str]) – The controls of the map.

  • search_mode (str) – ‘both’ | ‘markers’ | ‘layers’.

  • search_layers (str) – ‘ALL’ | null | Comma separated list of layers.

  • geosearch (bool) – The geosearch of the map.

  • remove_unused_tags (bool) – The remove unused tags of the map.

  • terrain_layer (str) – The terrain layer of the map.

  • exaggeration (int) – The exaggeration of the terrain.

  • enable_grid (bool) – The enable grid of the map.

  • grid_unit (str) – The unit of the grid.

  • grid_width (int) – The width of the grid.

  • grid_height (int) – The height of the grid.

  • grid_minzoom (int) – The minzoom of the grid.

  • grid_maxzoom (int) – The maxzoom of the grid.

  • bearing (int) – The bearing of the map.

  • pitch (int) – The pitch of the map.

  • center (List[float]) – The center of the map.

  • zoom (int) – The zoom of the map.

  • toc_settings (List) – The settings of the toc.

  • custom_basemaps (List[str]) – The custom basemaps of the map.

  • show_maptip_on (str) – ‘ALL’ | null | Comma separated list of layers.

  • snappable_layers (str) – ‘ALL’ | null | Comma separated list of layers.

Returns:

The response of the API.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(uuid="12345678-1234-5678-1234-567812345678")
>>> map.set_settings(zoom=10)
get_markers()[source]

Get the markers of the map.

Returns:

The markers of the map.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.get_markers()
set_markers(data)[source]

Set the markers of the map.

Parameters:

data (dict) – The data of the markers.

Returns:

The response of the API.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> data = {
...     'tags': {
...         '#general': {
...             'color': '#ff0000',
...         }
...     },
...     'locations': [
...         {
...             'id': 1,
...             'tag': '#general',
...             'name': 'test',
...             'geometry': [
...                 51.13162784422988,
...                 35.766603814763045
...             ],
...             'description': 'string'
...         }
...     ]
... }
>>> map.set_markers(data)
get_models(json=False)[source]

Get the map models.

Parameters:

json (bool, optional) – If True, return the response as a dictionary.

Returns:

map models objects or the response.

Return type:

List[Model] | Dict

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.get_models(json=True)
set_models(data)[source]

Set multiple models on the map.

Parameters:

data (Dict) – the data of the models and their location on the map. check the example for the data structure.

Returns:

the map models objects

Return type:

List[Model]

Example

>>> from geobox import GeoboxClient
>>> from geobox.map inport Map
>>> client = GeoboxClient()
>>> map = Map.get_map(uuid="12345678-1234-5678-1234-567812345678")
>>> data = {'objects': [
...     {
...         "name": "transmission_tower",
...         "alias": None,
...         "desc": None,
...         "obj": "12345678-1234-5678-1234-567812345678",
...         "loc": [53.1859045261684, 33.37762747390032, 0.0],
...         "rotation": [0.0, 0.0, 0.0],
...         "scale": 1.0,
...         "min_zoom": 0,
...         "max_zoom": 22
...     }
... ]}
>>> map.set_models(data)
add_model(model, location, rotation=[0.0, 0.0, 0.0], scale=1.0, min_zoom=0, max_zoom=22, alias=None, description=None)[source]

Add a model the map.

Parameters:

  • model (Model) – The model object.

  • location (List[float]) – location of the model on the map. a list with three float values.

  • rotation (List[float], optional) – rotation of the model on the map. a list with three float vlaues. default is [0.0, 0.0, 0.0].

  • scale (float, optional) – the scale of the model on the map.

  • min_zoom (int, optional) – minimum zoom level.

  • max_zoom (int, optional) – maximum zoom level.

  • alias (str, optional) – alias of the model on the map.

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

Returns:

The map model objects

Return type:

List[‘Model’]

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> model = client.get_model(uuid="12345678-1234-5678-1234-567812345678")
>>> map.add_model(model=model,
...                 location=[53.53, 33.33, 0.0],
...                 rotation=[0.0, 0.0, 0.0],
...                 scale=1.0,
...                 min_zoom=0,
...                 max_zoom=22,
...                 alias=None,
...                 description=None)
image_tile_url(x='{x}', y='{y}', z='{z}', format='.png')[source]

Get map image tile url

Returns:

the image tile url

Return type:

str

Parameters:

  • x (str)

  • y (str)

  • z (str)

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.image_tile_url()
>>> map.image_tile_url(x=1, y=2, z=3, format='.pbf')
export_map_to_image(bbox, width, height)[source]

Export the map to image

Parameters:

  • bbox (List) – e.g. [50.275, 35.1195, 51.4459, 36.0416]

  • width (int) – minimum: 10, maximum: 10000

  • height (int) – minimum: 10, maximum: 10000

Returns:

the task object

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> task = map.export_map_to_image(bbox=[50.275, 35.1195, 51.4459, 36.0416],
...                                 width=1024,
...                                 height=1024)
get_attachments(**kwargs)[source]

Get the resouces attachments

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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> map.get_attachments()
create_attachment(name, loc_x, loc_y, file, feature=None, display_name=None, description=None)[source]

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.

  • 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
>>> from geobox.map import Map
>>> client = GeoboxClient()
>>> map = Map.get_map(client, uuid="12345678-1234-5678-1234-567812345678")
>>> file = client.get_files()[0]
>>> map.create_attachment(name='test', loc_x=10, loc_y=10, file=file)