API Navigation

Introduction

Welcome to the Blockbax Python SDK Reference. The SDK enables Python developers to speed up and ease the integration with Blockbax. It makes interfacing with our HTTP API even easier where you can easily get, create, update and delete resources without the intricacies of having to deal with HTTP requests and responses.

The Blockbax Python SDK exposes a HttpClient class and resources as Python dataclasses. The HttpClient automatically injects the given access token and project ID per HTTP call and has built in mechanisms to catch and present any errors returned by the Blockbax API.

Getting Started

Installation

Installation

pip install blockbax-sdk

You can easily install the Blockbax Python SDK through pip.

Client setup

Client setup

import blockbax_sdk

project_id = "75ef0782-c63b-4afe-8e59-091f33cd88dd"
access_token = "0eVKlsqYH4QauFyij2LP6gfkFwZnK5Ta"

http_client = blockbax.HttpClient(
    project_id = project_id,
    access_token = access_token
    )

To start using the Blockbax Python SDK you first have to setup a HTTP client for your Blockbax project. Make sure you have created an access token with the appropriate permissions. Currently, you can interact with the following resource types:

Errors

Errors usage

from blockbax_sdk import errors

try:
  http_client.update_subject(subject = new_subject)
except errors.BlockbaxHTTPError as error:
  # Handle error

The Blockbax Python SDK defines the following errors.

The most common error is the BlockbaxHTTPError which is thrown whenever the HTTP client encounters an error. This error is also used as the base class for all other errors that can occur during HTTP requests. Two subtypes of the BlockbaxHTTPError class are the BlockbaxClientError & BlockbaxServerError which are thrown for HTTP status codes 4xx and 5xx respectively. Additionally the BlockbaxUnauthorizedError error is thrown for every failed request whenever the configured access token is unauthorized to do so.

BlockbaxHTTPError provides you with information such as:

ValueError is used whenever a numeric value is given that could not be stored as a Decimal. The Blockbax Python SDK automatically rounds decimals to 8 digits after the decimal point and throws the ValueError for any numeric value given with more than 20 digits before the decimal point. It’s important to note that the built in Python float in some rare occasions can not always be precise enough when dealing with very big values.

Property Types

Methods to create, update, delete and get property types.

Get property types

Get all property types:

all_property_types = http_client.get_property_types()

Get a select list of property types:

property_type_name_of_interest = "My Property type"
select_list_of_property_types = http_client.get_property_types(
    name = property_type_name_of_interest
    )

Gets property types, optionally with arguments for filtering.

Arguments

Returns: List of PropertyType

Get a property type

Get a property type by ID:

my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
single_property_type = http_client.get_property_type(
    id_ = my_property_type_id
    )

Gets a specific property type.

Arguments

Returns: PropertyType

Create a property type

Create values:

# values for "TEXT" data_type
my_text_property_values = ["text_value"]
# values for "NUMBER" data_type
my_number_property_values = [1, "2"]
# values for "LOCATION" data_type
my_location_property_values = [{
    "lat": 51.92517,
    "lon": 4.475660,
    "alt": 0            # Optional
}]

my_map_layer_property_values = [
    {
    "typeId": "d237162d-6da6-455e-8921-ba0c4bae4fc5",
    "mapLayer": {
        "imagePath" : "/projects/715b6935-e3d8-48b1-86a3-a6e2a268e1f/propertyTypes/d237162d-6da6-455e-8921-ba0c4bae4fc5/values/8a75002b-0c63-4fe8-afc0-2c05e428a76a/files/efa6753f-4981-417f-aabd-be0f43c6e4f6.png",
        "leftBottom" : {
            "lat": 52.37403,
            "lon": 4.88969
        },
        "leftTop" : {
            "lat": 52.37404,
            "lon": 4.88969
        },
        "rightBottom" : {
            "lat": 52.37403,
            "lon": 4.88970
        },
        "rightTop" : {
            "lat": 52.37404,
            "lon": 4.88970
        }
    }
}]

my_image_property_values = [{
    "typeId": "bae083a4-fb3a-490a-8025-312112066b66",
    "image": {
        "imagePath": "/projects/715b6935-e3d8-48b1-86a3-a6e2a268e1f/propertyTypes/bae083a4-fb3a-490a-8025-312112066b66/values/a8c52571-b882-4bf0-b013-f38f9621e7b6/files/ada6753f-4981-417f-aabd-be0f43c6e4c9.png"
    }
}]

Create a property type:

my_property_type = http_client.create_property_type(
    name = "My Property type",            # Required
    data_type = "NUMBER",                 # Required
    predefined_values = True,             # Required
    values = my_number_property_values    # Optional, default = []
)

Creates a property type

Arguments

Returns: PropertyType

Update a property type

Update predefined property values:

my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
my_property_type = http_client.get_property_type(
    id_ = my_property_type_id
    )

new_value = 3
my_property_type.add_value(new_value)

old_value = 2
my_property_type.remove_value(old_value)

Update attributes

my_property_type.name = "My new Property value name"

Update property type:

my_property_type = http_client.update_property_type(my_property_type)

Updates a property type.

Arguments

Returns: PropertyType

Delete a property type

Delete a property type:

my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
http_client.delete_property_type(
    id_ = my_property_type_id
    )

Deletes a property type.

Arguments

Returns: None

Subject Types

Methods to create, update, delete and get subject types.

Get subject types

Get all Subject types

all_subject_types = http_client.get_subject_types()

Get a select list of Subject types

subject_type_name_of_interest = "My Subject Type"
property_types_ids_of_interest = [
    "e85f1b55-07bd-40d5-85a5-04c07dd3f12f",
    "5c2df77a-b700-460b-a87d-5adc03f915bb"
    ]

select_list_of_subject_types = http_client.get_subject_types(
    name = subject_type_name_of_interest,
    property_types_ids = property_types_ids_of_interest
    )

Gets subject types, optionally with arguments for filtering.

Arguments

Returns: List of SubjectType

Get a subject type

Get a single Subject type

my_subject_type_id = "526e8fee-ded2-410d-b562-888724d58183"
single_subject = http_client.get_subject_type(
    id_ = my_subject_type_id
    )

Gets a specific subject type.

Arguments

Returns: SubjectType

Create a subject type

Create Primary location (PROPERTY_TYPE):

my_primary_location = {
    "type" : "PROPERTY_TYPE",
    "id" : "5c2df77a-b700-460b-a87d-5adc03f915bb"
    }

Create Property Types:

my_property_types = [
    {
        "id": "e85f1b55-07bd-40d5-85a5-04c07dd3f12f",
        "required": True,
    },{
        "id": "e5f7ec09-4af4-4ac1-8837-124a0b7c9e37",
        "required": False,
        "visible": True
    },{
        "id": "5c2df77a-b700-460b-a87d-5adc03f915bb",
        "required": False,
        "visible" : False
    }]

Create Subject Type:

my_parent_subject_type_id = "f8874ab2-1695-4e11-a7f1-47eba57f0053"

my_subject_type = http_client.create_subject_type(
    name = "My subject type",               # Required
    parent_id = my_parent_subject_type_id,  # Optional
    primary_location = my_primary_location, # Optional
    property_types = my_property_types      # Optional
    )

Creates a subject type

Arguments

Returns: SubjectType

Update a subject sype

Update Property types:

my_subject_type_id = "526e8fee-ded2-410d-b562-888724d58183"
my_subject_type = http_client.get_subject_type(
    subject_type_id = my_subject_type_id
    )

# Add new property types
my_new_property_types = [{
    "id" : "54a6850f-a7ae-40ba-8934-aba1fbddbeab",
    "required" : True,
    "visible" : True
    }]

my_subject_type.add_property_types(my_new_property_types)

# Remove property types
property_type_ids_to_remove = ["e5f7ec09-4af4-4ac1-8837-124a0b7c9e37"]
my_subject_type.remove_property_types(property_type_ids_to_remove)

Create Primary location (METRIC):

my_primary_location = {
    "type" : "METRIC",
    "id" : "a6e924d7-885b-4045-baab-4d5e7bae1641"
    }

Update attributes

# Update Primary location
my_subject_type.primary_location = my_primary_location
# Update name
my_subject_type.name = "My New Subject Type"
# update parent subject type ID
my_subject_type.parent_id = "d1b01ef9-868b-43c5-b3c0-10a884105899"

Update Subject Type:

my_subject_type = http_client.update_subject_type(my_subject_type)

Updates a subject type.

Arguments

Returns: SubjectType

Delete a subject type

Delete Subject Type

my_subject_type_id = "526e8fee-ded2-410d-b562-888724d58183"
http_client.delete_subject_type(
    id_ = my_subject_type_id
    )

Deletes a subject type.

Arguments

Returns: None

Metrics

Methods to create, update, delete and get metrics.

Get metrics

Get all Metrics

all_metrics = http_client.get_metrics()

Get a select list of Metrics

metrics_name_of_interest = "My Metric"

metrics_external_id_of_interest = "my-metric"

subject_type_ids_of_interest = [
    "526e8fee-ded2-410d-b562-888724d58183",
    "5dc020a2-e43c-49d7-a294-838108e8021a"
    ]

select_list_of_metrics = http_client.get_metrics(
    name = metrics_name_of_interest,
    external_id = metrics_external_id_of_interest,
    subject_type_ids = subject_type_ids_of_interest
    )

Gets metrics, optionally with arguments for filtering.

Arguments

Returns: List of Metric

Get a metric

Get a single Metric

my_metric_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
single_metric = http_client.get_metric(
    id_ = my_metric_id
    )

Gets a specific metric.

Arguments

Returns: Metric

Create metrics

Create Metric:

subject_type_id = "526e8fee-ded2-410d-b562-888724d58183"
my_metric = http_client.create_metric(
    subject_type_id = subject_type_id,  # Required
    name = "My metric",                 # Required
    data_type = "NUMBER",               # Required
    type_ = "INGESTED"                  # Required
    unit = "K",                         # Optional, default = ""
    precision = 2,                      # Optional, default = 8
    visible = True,                     # Optional, default = True
    discrete = False,                   # Optional, default = False
    external_id = "example"             # Optional, default: derived from name
)

Creates a metric.

Arguments

Returns: Metric

Update a metric

Update Attributes

my_metric_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
my_metric = http_client.get_metric(
    id_ = my_metric_id
    )

my_metric.name = "Updated Metric name"
my_metric.unit = "K"
my_metric.precision = 2
my_metric.visible = False
my_metric.external_id = "updated-metric-external-id"

Update Metric

http_client.update_metric(my_metric)

Updates a metric.

Arguments

Returns: Metric

Delete a metric

Delete Metric

my_metric_id = "3c47681d-c782-45b2-8544-55eba5b398af"
http_client.delete_metric(
    id_ = my_metric_id
    )

Deletes a metric.

Arguments

Returns: None

Subjects

Methods to create, update, delete and get subjects.

Get subjects

Get all Subjects:

all_subjects = http_client.get_subjects()

Get a select list of Subjects:

subject_name_of_interest = "My Subject"
subject_external_id_of_interest = "my-subject"
subject_ids_of_interest = ["fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"]
subject_type_ids_of_interest = ["my-subject-external-id"]
property_value_id_1 = "c287dc1c-0715-4fe5-a693-224f80b6fde3"
property_value_id_2 = "5666c0d6-e984-4bf4-af78-abd23fd660bc"
property_value_id_3 = "5c02e7ae-217c-4f36-b684-6797d2af2034"
property_value_ids_of_interest = f"{property_value_id_1},{property_value_id_2};{property_value_id_3}"
# Or
property_value_ids_of_interest = [(property_value_id_1,property_value_id_2),property_value_id_3]

select_list_of_subjects = http_client.get_subjects(
    name = subject_name_of_interest,
    external_id = subject_external_id_of_interest,
    subject_ids = subject_ids_of_interest,
    subject_type_ids = subject_type_ids_of_interest,
    property_value_ids_of_interest = property_value_ids_of_interest
    )

Gets subjects, optionally with arguments for filtering.

Arguments

Returns: Subject

Get a subject

Get a single Subject:

my_subject_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
single_subject = http_client.get_subject(
    id_ = my_subject_id
    )

Gets a specific subject.

Arguments

Returns: Subject

Create a subject

Create ingestion ID’s to overwrite:

my_metric_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
ingestion_ids_to_override = {
    my_metric_id: "my-new-ingestion-id"
}

Create Property values:

# "TEXT" data_type defined by property_type
my_property_type_id = "59e4dd81-5704-4973-8bc4-8f377f9c487c"
text_property = {
    "typeId": my_property_type_id,
    "text": "my_property_value"
}

# "NUMBER" data_type defined by property_type
my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
number_property = {
    "typeId": my_property_type_id,
    "number": 1
}

# "LOCATION" data_type defined by property_type
my_property_type_id = "5c2df77a-b700-460b-a87d-5adc03f915bb"
location_property = {
    "typeId": my_property_type_id,
    "location": {
        "lat": 51.925171,
        "lon": 4.475660,
        "alt": 0             # Optional
    }
}

my_property_type_id = "d237162d-6da6-455e-8921-ba0c4bae4fc5"
map_layer_property = {
    "typeId": my_property_type_id,
    "mapLayer": {
        "imagePath" : "/projects/715b6935-e3d8-48b1-86a3-a6e2a268e1f/propertyTypes/d237162d-6da6-455e-8921-ba0c4bae4fc5/values/8a75002b-0c63-4fe8-afc0-2c05e428a76a/files/efa6753f-4981-417f-aabd-be0f43c6e4f6.png",
        "leftBottom" : {
            "lat": 52.37403,
            "lon": 4.88969
        },
        "leftTop" : {
            "lat": 52.37404,
            "lon": 4.88969
        },
        "rightBottom" : {
            "lat": 52.37403,
            "lon": 4.88970
        },
        "rightTop" : {
            "lat": 52.37404,
            "lon": 4.88970
        }
    }
}

my_property_type_id = "bae083a4-fb3a-490a-8025-312112066b66"
image_property = {
    "typeId": my_property_type_id,
    "image": {
        "imagePath": "/projects/715b6935-e3d8-48b1-86a3-a6e2a268e1f/propertyTypes/bae083a4-fb3a-490a-8025-312112066b66/values/a8c52571-b882-4bf0-b013-f38f9621e7b6/files/ada6753f-4981-417f-aabd-be0f43c6e4c9.png"
    }
}

my_property_type_id ="fc13e380-aee1-46c3-a125-2a7831b6d492"
inherited_property = {
    "typeId": my_property_type_id,
    "inherit": True
}

new_properties = [
    text_property,
    number_property,
    location_property,
    map_layer_property,
    image_property,
    inherited_property,
]

Create Subject

my_subject_type_id = "526e8fee-ded2-410d-b562-888724d58183"
my_parent_subject_id = "8e9e140c-3223-493a-bbfc-cc214fa44ae6"

my_subject = http_client.create_subject(
    subject_type_id = my_subject_type_id,               # Required
    name = "My Subject",                                # Required
    parent_id = my_parent_subject_id                    # Optional
    properties = new_properties,                        # Optional
    ingestion_id_overrides = ingestion_ids_to_override, # Optional
    external_id = "my-subject-external-id"              # Optional
)

Creates a subject.

Arguments

Returns: Subject

Update a subject

Update properties

my_subject_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
my_subject = http_client.get_subject(
    id_ = my_subject_id
    )

# Create new or update already existing properties

# "TEXT" data_type defined by property_type
my_property_type_id = "a8c89d3f-8fa2-480d-a013-8ff9adc16a4c"
text_property = {
    "typeId": my_property_type_id,
    "text": "my_property_value"
}

# "NUMBER" data_type defined by property_type
my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
number_property = {
    "typeId": my_property_type_id,
    "number": 6
}

# "LOCATION" data_type defined by property_type
my_property_type_id = "5c2df77a-b700-460b-a87d-5adc03f915bb"
location_property = {
    "typeId": my_property_type_id,
    "location": {
        "lat": 51.997903,
        "lon": 4.3721174,
        "alt": 0             # Optional
    }
}

updated_properties = [
    text_property,
    number_property,
    location_property
]

# You can add or update property values like this
my_subject.set_properties(updated_properties)

# You can remove property values like this
my_property_type_ids_to_remove = ["e85f1b55-07bd-40d5-85a5-04c07dd3f12f"]
my_subject.remove_properties(my_property_type_ids_to_remove)

Update ingestion IDs

# You can add or update already existing ingestion IDs like this
my_metric_id = "3c47681d-c782-45b2-8544-55eba5b398af"
my_updated_ingestion_id = "my-updated-ingestion-id"
my_subject.set_ingestion_id(my_metric_id, my_ingestion_id)

# You can remove an ingestion ID like this:
my_metric_id_to_remove = "9a754b09-311c-4f80-b94e-1d36f6e81e26"
my_subject.remove_ingestion_id(my_metric_id_to_remove)

Update attributes

# Update name
my_subject.name = "New Name"
# Update external ID
my_subject.external_id = "New external ID"
# Update parent subject ID
my_subject.parent_id = "261d7154-04d6-4333-bd73-33e0f1592840"

update Subject

my_subject = http_client.update_subject(my_subject)

Updates a subject.

Arguments

Returns: Subject

Delete a subject

Delete Subject

my_subject_id = "fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"
http_client.delete_subject(
    id_ = my_subject_id
    )

Deletes a subject.

Arguments

Returns: None

Measurements

Methods to queue, send and get measurements

Queue a measurement

queue a number value:

# add number
my_number = 1
my_date = datetime.utcnow()
ingestion_id = "my_number_ingestion"

http_client.queue_measurement(
    ingestion_id = ingestion_id,
    date = date,
    number = my_number
)

queue a location value:

# add location
my_location = {
    "lat":51.925171,
    "lon":4.475660,
    "alt":0             # Optional
}
my_date = datetime.utcnow()
ingestion_id = "my_location_ingestion"

http_client.queue_measurement(
    ingestion_id = ingestion_id,
    date = date,
    location = my_location
)

Queues measurements to send.

Arguments

Returns: None

Raises: ValueError: Raised when given number could not be converted to a Decimal

Sending measurements

Send All Measurements

http_client.send_measurements()

Send select list of ingestions

ingestion_ids_to_send = ["my-first-ingestion", "my-second-ingestion"]

http_client.send_measurements(
    ingestion_ids = ingestion_ids_to_send,
    )

Sends queued measurements.

Arguments

Returns: None

Get measurements

Get all latest measurements:

my_series = http_client.get_measurements()

Get specific measurements:

subject_ids = ["fca1f5c9-e78a-48a3-b5b0-e0ee969a743b"]
metric_ids = ["3c47681d-c782-45b2-8544-55eba5b398af"]
# measurements from last two hours
to_date = datetime.datetime.utcnow()
from_date = to_date - datetime.timedelta(hours=2)
order = "asc"

my_series = http_client.get_measurements(
    subjects=subjects,  # Optional iff 'from_date' or 'to_date' is None else only 1 allowed
    metrics=metrics,    # Optional iff 'from_date' or 'to_date' is None else only 1 allowed
    from_date=from_date,# Optional
    to_date=to_date,    # Optional
    order=order,        # Optional, default = asc
)

Gets measurements with arguments for filtering.

Arguments

Returns: List of Series

Data Classes

Python data classes used within the SDK.

Property Type

Example

# Add a value
my_new_number_value = 2
caption = "two"
PropertyType.add_value(my_new_number_value, caption)

# Change a value 
old_value = 2
new_value = 3

PropertyType.change_value(old_value, new_value)

value = 3
caption = "Three"
PropertyType.change_caption(value, caption)

# Check if the property type contains a value
existing_value = 3

PropertyType.contains_value(existing_value)
> True

# Remove a value
my_old_location_value = {
    "lat":51.925171,
    "lon":4.475660,
}
PropertyType.remove_value(my_old_location_value)

A PropertyType dataclass representing a property type.

Attributes

Methods

Property Value

Example

my_value = PropertyValue.get_value()

data_type = PropertyValue.get_data_type()

A PropertyValue dataclass representing a single predefined property value.

Depending on the data type a subclass of the PropertyValue will be returned. This subclass will only contain either one of the following attributes: text, number, location, map_layer, image or area.

Attributes

Methods

Subject Type

Example

my_new_property_types = [{
    "id" : "54a6850f-a7ae-40ba-8934-aba1fbddbeab",
    "required" : True,
    "visible" : True
    }]

SubjectType.add_property_types(my_new_property_types)


property_type_ids_to_remove = ["e5f7ec09-4af4-4ac1-8837-124a0b7c9e37"]
SubjectType.remove_property_types(property_type_ids_to_remove)

existing_property_type_id = "54a6850f-a7ae-40ba-8934-aba1fbddbeab"

SubjectType.contains_property_type(existing_property_type_id)
> True

A SubjectType dataclass representing a subject type

Attributes:

Methods

Metric

A Metric dataclass representing a Blockbax Metric

Attributes:

Subject

Property value Example

# dictionary's representing different types to property values:

# "TEXT" data_type defined by property_type
my_property_type_id = "a8c89d3f-8fa2-480d-a013-8ff9adc16a4c"
text_property = {
    "typeId": my_property_type_id,
    "text": "my_property_value"
}

# "NUMBER" data_type defined by property_type
my_property_type_id = "e85f1b55-07bd-40d5-85a5-04c07dd3f12f"
number_property = {
    "typeId": my_property_type_id,
    "number": 6
}

# "LOCATION" data_type defined by property_type
my_property_type_id = "5c2df77a-b700-460b-a87d-5adc03f915bb"
location_property = {
    "typeId": my_property_type_id,
    "location": {
        "lat": 51.997903,
        "lon": 4.3721174,
        "alt": 0             # Optional
    }
}

updated_properties = [
    text_property,
    number_property,
    location_property
]

# You can add property values like this
Subject.set_properties(updated_properties)

# You can remove property values like this
my_property_type_ids_to_remove = ["e85f1b55-07bd-40d5-85a5-04c07dd3f12f"]
Subject.remove_properties(my_property_type_ids_to_remove)

Property value Example

# add ingestion IDs
my_metric_id = "f4870f59-2e4b-4fc5-8d83-477fcf1f4fe2"
my_new_ingestion_id = "my-ingestion-id"
Subject.set_ingestion_id(my_metric_id, my_ingestion_id)

# Remove ingestion ID:
my_metric_id_to_remove = "9a754b09-311c-4f80-b94e-1d36f6e81e26"
Subject.remove_ingestion_id(my_metric_id_to_remove)

A Subject dataclass representing a Blockbax Subject

Attributes:

Methods

Series

Example

# Iterate over measurements
for measurement in my_series:
    date = measurement.date
    value = measurement.get_value()

An Iterable Series dataclass representing a series of measurements that belong to a combination of a subject and metric ID.

Attributes:

Measurement

Example

my_value = PropertyValue.get_value()

A Measurment dataclass representing either a number or location measurement.

Depending on the data type a subclass of the Measurment will be returned. This subclass will only contain either one of the following attributes: text, number or location.

Attributes:

Methods