Automating platform actions using the REST API with Python

Got feedback? Additional questions? Just want to have a friendly chat? Get in touch!

Available parts

Goal
Generate Python code to interact with xyzt.ai
Setup and run your first API query with Python
Automating platform actions using the REST API with Python (current)
Uploading data using the REST API with Python
Next steps

Step 3: Using the REST API

Now that you have successfully used the generated Python code and accessed the xyzt.ai platform through the REST API, let’s explore some of the available capabilities.

In this step of the tutorial, we will create a new project, attach an existing data set and create a custom dashboard.

Step 3.1: Creating a new project

We will build on our previous script, and extend it to create a new project. This is done through the generated ProjectsApi:

main2.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36 import openapi_client
from openapi_client.rest import ApiException
from pprint import pprint

userName = "replace with your API user name"
password = "replace with your API password"

# Enter a context with an instance of the API client
with openapi_client.ApiClient() as api_client:
    # Create an instance of the API class
    api_instance = openapi_client.AuthenticationJWTTokenApi(api_client)
    login_request = openapi_client.LoginRequest(userName=userName, password=password)

    try:
        # Retrieve a JWT token
        token_response = api_instance.obtain_token(login_request)
        print("The response of AuthenticationJWTTokenApi->obtain_token:\n")
        pprint(token_response)

        # Set the obtained token in the headers for subsequent requests
        api_client.default_headers["Authorization"] = f"Bearer {token_response.jwt_token}"

        # Query all data sets
        datasets_api = openapi_client.DataSetsApi(api_client)
        datasets_response = datasets_api.get_all_data_sets()
        pprint(datasets_response)

        # Create a new project
        projects_api = openapi_client.ProjectsApi(api_client)
        create_project_response = projects_api.create_project(openapi_client.CreatePublicProjectRequest(
        name="My first project",
        description="My first project created through the REST API"))
        pprint(create_project_response)

    except ApiException as e:
        print("Exception when calling the REST API: %s\n" % e)

This prints the JWT token, the data sets as before, and finally the information about the created project, like this:

PublicProjectDTO(id='5ebab81e-d5d0-4637-90ce-b174f4b47290', name='My first project', description='My first project created through the REST API', owned=True)

Step 3.2: Attaching an existing data set

You can create and upload your own data set. See DataSetsApi or the API documentation website for the different steps needed to create a data set and upload data records.

In this step, however, you will be using an existing data set, and attaching it to the project we just created.

In the example code below, we take the first data set returned, but of course you can attach any of the returned data sets.

Copy-paste the below code and save it in a file src/main3.py:

main3.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44 import openapi_client
from openapi_client.rest import ApiException
from pprint import pprint

userName = "replace with your API user name"
password = "replace with your API password"

# Enter a context with an instance of the API client
with openapi_client.ApiClient() as api_client:
    # Create an instance of the API class
    api_instance = openapi_client.AuthenticationJWTTokenApi(api_client)
    login_request = openapi_client.LoginRequest(userName=userName, password=password)

    try:
        # Retrieve a JWT token
        token_response = api_instance.obtain_token(login_request)
        print("The response of AuthenticationJWTTokenApi->obtain_token:\n")
        pprint(token_response)

        # Set the obtained token in the headers for subsequent requests
        api_client.default_headers["Authorization"] = f"Bearer {token_response.jwt_token}"

        # Query all data sets
        datasets_api = openapi_client.DataSetsApi(api_client)
        datasets_response = datasets_api.get_all_data_sets()
        pprint(datasets_response)

        # Create a new project
        projects_api = openapi_client.ProjectsApi(api_client)
        create_project_response = projects_api.create_project(openapi_client.CreatePublicProjectRequest(
        name="My first project",
        description="My first project created through the REST API"))
        pprint(create_project_response)

        # Attach the first data set to the project
        projects_resources_datasets_api = openapi_client.ProjectResourcesDataSetsApi(api_client)
        projects_resources_datasets_api.add_data_set_to_project(
            project_id=create_project_response.id,
            public_add_data_set_to_project_request=openapi_client.PublicAddDataSetToProjectRequest(
                data_set_id=datasets_response[0].id
            ))

    except ApiException as e:
        print("Exception when calling the REST API: %s\n" % e)

Run this code and verify that a data set is now attached to the last created project by navigating to your platform account in a browser and opening the last created project. Note that the project card now mentions that 1 data set is attached.

Step 3.3: Populating a dashboard

As a final step, you will create a dashboard and populate it with a widget.

Each project has a single dashboard. Each dashboard can be populated with different widgets, grouped in so-called widget groups.

Widgets can be a map, a timeline, a bar chart,… . Such widgets always relate to one of the analytical pages, such as the Visual Analytics or Trend Analytics page. A widget is created by defining the state of the relevant page, e.g., should there be one or two maps? Which styling should be used on the map? What property and time filters should be applied? Etc.

Because there are many configuration possibilities for each of the analytical pages, the REST API is extensive. However, not all properties need to be defined. For example, if you don’t want to filter your data, you don’t need to define any (empty) filters.

The below code extends main3.py and creates a widget group and populates the group with a map widget of the Visual Analytics page.

Copy-paste the code and save it as main4.py. Don’t forget to adjust the userName and password with the API username and password.

main4.py

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103 import openapi_client
from openapi_client.rest import ApiException
from pprint import pprint

userName = "replace with your API user name"
password = "replace with your API password"

# Enter a context with an instance of the API client
with openapi_client.ApiClient() as api_client:
    # Create an instance of the API class
    api_instance = openapi_client.AuthenticationJWTTokenApi(api_client)
    login_request = openapi_client.LoginRequest(userName=userName, password=password)

    try:
        # Retrieve a JWT token
        token_response = api_instance.obtain_token(login_request)
        print("The response of AuthenticationJWTTokenApi->obtain_token:\n")
        pprint(token_response)

        # Set the obtained token in the headers for subsequent requests
        api_client.default_headers["Authorization"] = f"Bearer {token_response.jwt_token}"

        # Query all data sets
        datasets_api = openapi_client.DataSetsApi(api_client)
        datasets_response = datasets_api.get_all_data_sets()
        pprint(datasets_response)

        # Create a new project
        projects_api = openapi_client.ProjectsApi(api_client)
        create_project_response = projects_api.create_project(openapi_client.CreatePublicProjectRequest(
            name="My first project",
            description="My first project created through the REST API"))
        pprint(create_project_response)

        # Attach the first data set to the project
        projects_resources_datasets_api = openapi_client.ProjectResourcesDataSetsApi(api_client)
        projects_resources_datasets_api.add_data_set_to_project(
            project_id=create_project_response.id,
            public_add_data_set_to_project_request=openapi_client.PublicAddDataSetToProjectRequest(
                data_set_id=datasets_response[0].id
            ))

        # Widgets can only be added to a group, so first create a new widget group
        project_resources_widgets_api = openapi_client.ProjectResourcesWidgetsApi(api_client)
        create_widget_group_response = project_resources_widgets_api.create_widget_group(
            project_id=create_project_response.id,
            create_public_widget_group_request=openapi_client.CreatePublicWidgetGroupRequest(
                name="My API created widget group"
            )
        )

        # Create the properties for the dataset
        properties_per_data_set = {
            datasets_response[0].id: openapi_client.PublicVisualAnalyticsDataSetProperties(
                gridded_display_options=openapi_client.PublicVisualAnalyticsGriddedDisplayOptions(
                    mode='COLOR_BY_NUMBER_OF_RECORDS',
                    color_by_number_of_records_color_map={
                        "heat_map": {
                            "name": 'RAINBOW'
                        }
                    }
                )
            )
        }

        # Add a visual analytics widget to the group
        project_resources_widgets_api.create_visual_analytics_widget(
            project_id=create_project_response.id,
            widget_group_id=create_widget_group_response.id,
            create_public_visual_analytics_widget_request=openapi_client.CreatePublicVisualAnalyticsWidgetRequest(
                title="Map fitted on entire area",
                properties=openapi_client.PublicVisualAnalyticsWidgetProperties(
                    widget_type='SPATIAL_MAP',
                    map_index=0
                ),
                state={
                    "individual_map_states": [
                        {
                            "temporal_range_filter": {
                                "end_time_type": 'BEFORE_END_OF_DATA',
                                "end_time_delta_in_seconds": 0,
                                "start_time_type": 'BEFORE_END_OF_FILTER',
                                "start_time_delta_in_seconds": 60 * 60 * 24 * 7,
                                "end_time_in_seconds": 0,
                                "start_time_in_seconds": 0
                            },
                            "data_set_properties": properties_per_data_set,
                            "time_line_properties": {
                                "properties": [
                                    {
                                        "data_set_id": datasets_response[0].id,
                                        "mode": 'DISPLAY_NUMBER_OF_ASSETS'
                                    }
                                ]
                            }
                        }
                    ]
                }
            )
        )

    except ApiException as e:
        print("Exception when calling the REST API: %s\n" % e)

This script creates a single widget on the dashboard with a map showing the last week of data colored with the Rainbow heatmap. Open the dashboard in your browser. Notice how clicking on the widget will bring you to the Visual Analytics page with the state configured in the main4.py script.

In the next step of the tutorial you will use the API to create a new project and upload new data to the platform.

Next part

Go to the next part: Uploading data using the REST API with Python

Got feedback? Additional questions? Just want to have a friendly chat? Get in touch!