Manage Workspaces

This tutorial shows how to create and manage interactive workspaces using the ZillionInfo API. You’ll learn how to create a workspace with multiple data layers using different classification methods.

Prerequisites

• A ZillionInfo account. If you don’t have one, you can sign up at ZillionInfo.
• An API key for authentication.
• Spatial data and attribute data already uploaded to the platform (see the Data Management tutorial if needed)

Steps

1. Get your data IDs

   Before creating a workspace, you need the IDs of the spatial and attribute data you want to include. You can get these using the getDataLists API.

   cURL

   curl -X GET "https://services.zillioninfo.com/zi/data/app/api/getDataLists" \
     -H "Authorization: Bearer YOUR_API_KEY"

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/getDataLists"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY"
   }
   
   # Make the GET request
   response = requests.get(url, headers=headers)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store data IDs for use in creating the workspace
   data_list = response.json().get("data", {})
   
   # Example: Find data IDs by name
   spatial_data_id = None
   attribute_data_id = None
   
   for data_id, data_name in data_list.items():
       if data_name == "My Spatial Data":
           spatial_data_id = int(data_id)
       elif data_name == "My Attribute Data":
           attribute_data_id = int(data_id)
   
   print(f"Spatial Data ID: {spatial_data_id}")
   print(f"Attribute Data ID: {attribute_data_id}")

   Response:

   {
     "data": {
       "1234": "My Spatial Data",
       "5678": "My Attribute Data"
     }
   }

2. Create a workspace with multiple layers

   Now, create a workspace with two layers: one using multivariate classification and one using univariate classification.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/createWorkspace" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Multi-Layer Workspace",
       "accessType": "private",
       "params": [
         {
           "dataId": 1234,
           "classification": {
             "type": "multivariate",
             "param": {
               "variables": [
                 {
                   "vars": [0, 1, 2],
                   "nors": [-1, -1, -1],
                   "weights": [1.0, 1.0, 1.0]
                 }
               ],
               "method": "SOM",
               "somSize": 3
             }
           }
         },
         {
           "dataId": 1234,
           "classification": {
             "type": "univariate",
             "param": {
               "mode": "numeric",
               "field": "population",
               "type": "getClassJenks",
               "numClasses": 5
             }
           }
         }
       ],
       "showAttributeTable": true,
       "showFieldTable": true,
       "showPcp": true,
       "showRightPanel": true
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/createWorkspace"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "name": "My Multi-Layer Workspace",
       "accessType": "private",
       "params": [
           {
               # First layer - Multivariate classification
               "dataId": 1234,  # Spatial data ID
               "classification": {
                   "type": "multivariate",
                   "param": {
                       "variables": [
                           {
                               "vars": [0, 1, 2],  # Indices of variables to use
                               "nors": [-1, -1, -1],  # Normalization variables (-1 for none)
                               "weights": [1.0, 1.0, 1.0]  # Equal weights for each variable
                           }
                       ],
                       "method": "SOM",  # Self-Organizing Map method
                       "somSize": 3  # 3x3 grid (9 clusters)
                   }
               }
           },
           {
               # Second layer - Univariate classification
               "dataId": 1234,  # Same spatial data ID
               "classification": {
                   "type": "univariate",
                   "param": {
                       "mode": "numeric",  # Numeric field classification
                       "field": "population",  # Field name to classify
                       "type": "getClassJenks",  # Jenks natural breaks classification
                       "numClasses": 5  # Number of classes
                   }
               }
           }
       ],
       "showAttributeTable": True,
       "showFieldTable": True,
       "showPcp": True,  # Show parallel coordinate plot
       "showRightPanel": True
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store the workspace key and job ID for checking status
   result = response.json()
   workspace_key = result.get("workspaceKey")
   job_id = result.get("jobID")
   
   print(f"Workspace Key: {workspace_key}")
   print(f"Job ID: {job_id}")

   Parameters:

   • name: Name of the workspace
   • accessType: Sharing scope of the workspace (private, public, etc.)
   • params: Array of layer parameters
     • dataId: Spatial data ID
     • csvDataId: Attribute data ID
     • classification: Classification settings
       • For multivariate classification:
         • type: “multivariate”
         • param.variables.vars: Array of variable indices
         • param.variables.nors: Array of normalization variable indices
         • param.variables.weights: Array of weights
         • param.method: Classification method (e.g., “SOM”)
         • param.somSize: Size of the SOM grid
       • For univariate classification:
         • type: “univariate”
         • param.mode: “numeric” or “categorical”
         • param.field: Field name to classify
         • param.type: Classification method
         • param.numClasses: Number of classes
   • showAttributeTable: Whether to show the attribute table
   • showFieldTable: Whether to show the field table
   • showPcp: Whether to show the parallel coordinate plot
   • showRightPanel: Whether to show the right panel

   Response:

   {
     "jobID": 9876,
     "workspaceKey": "abc123xyz456",
     "error": null
   }

   The response provides:

   • jobID: The ID of the job to create the workspace
   • workspaceKey: The key of the created workspace
   • error: Error message if the creation failed

3. Check the status of the workspace creation job

   Creating a workspace may take some time. You can check the status of the job using the workspace key and job ID.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/statusWorkspace" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "jobID": 9876,
       "workspaceKey": "abc123xyz456"
     }'

   Python

   import requests
   import json
   import time
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/statusWorkspace"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "jobID": 9876,  # Job ID from previous step
       "workspaceKey": "abc123xyz456"  # Workspace key from previous step
   }
   
   # Function to check job status
   def check_workspace_status():
       response = requests.post(url, headers=headers, json=payload)
       return response.json()
   
   # Poll for job completion
   status = 444  # Initial status: waiting
   while status in [333, 444]:  # 333: running, 444: waiting
       result = check_workspace_status()
       status = result.get("status")
   
       status_text = {
           111: "finished",
           222: "failed",
           333: "running",
           444: "waiting"
       }.get(status, "unknown")
   
       print(f"Current status: {status_text}")
   
       if status in [111, 222]:  # 111: finished, 222: failed
           print(json.dumps(result, indent=2))
           break
   
       # Wait before checking again
       time.sleep(3)

   Parameters:

   • jobID: The job ID from the previous step
   • workspaceKey: The workspace key from the previous step

   Response:

   {
     "status": 111,
     "result": "Job result",
     "error": null
   }

   The status codes are:

   • 111: Finished
   • 222: Failed
   • 333: Running
   • 444: Waiting

4. Get data list in the workspace

   You can retrieve a list of data resources in the workspace.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/getDataListInWorkspace" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "workspaceKey": "abc123xyz456"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/getDataListInWorkspace"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "workspaceKey": "abc123xyz456"  # Workspace key from previous steps
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Process the data lists
   result = response.json()
   spatial_data = result.get("spatialData", [])
   attribute_data = result.get("attributeData", [])
   
   print("Spatial data in workspace:")
   for data in spatial_data:
       print(f"ID: {data['id']}, Name: {data['name']}")
   
   print("\nAttribute data in workspace:")
   for data in attribute_data:
       print(f"ID: {data['id']}, Name: {data['name']}")

   Parameters:

   • workspaceKey: The key of the workspace

   Response:

   {
     "spatialData": [
       {
         "id": 1234,
         "name": "My Spatial Data"
       }
     ],
     "attributeData": [
       {
         "id": 5678,
         "name": "My Attribute Data"
       }
     ],
     "error": null
   }

5. Update a workspace

   You can update a workspace to replace data resources or modify settings.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/updateWorkspace" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "dashboardKey": "abc123xyz456",
       "oldDataId": 1234,
       "newDataId": 4321,
       "keepUrl": true
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/updateWorkspace"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "dashboardKey": "abc123xyz456",  # Workspace key
       "oldDataId": 1234,  # ID of the spatial data to replace
       "newDataId": 4321,  # ID of the new spatial data
       "keepUrl": True  # Keep the same URL for the workspace
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store the workspace key and job ID for checking status
   result = response.json()
   workspace_key = result.get("workspaceKey")
   job_id = result.get("jobID")
   
   print(f"Updated Workspace Key: {workspace_key}")
   print(f"Job ID: {job_id}")

   Parameters:

   • dashboardKey: The key of the workspace to update
   • oldDataId: The ID of the spatial data to replace
   • newDataId: The ID of the new spatial data
   • oldCsvDataId: (Optional) The ID of the attribute data to replace
   • newCsvDataId: (Optional) The ID of the new attribute data
   • keepUrl: Whether to keep the same URL for the workspace

   Response:

   {
     "jobID": 9877,
     "workspaceKey": "abc123xyz456",
     "error": null
   }

   The response provides:

   • jobID: The ID of the job to update the workspace
   • workspaceKey: The key of the updated workspace
   • error: Error message if the update failed

6. Share the workspace

   Once your workspace is created, you can find it in the workspace list. It’s private by default. You can edit it to share it with your groups, your organization, or the public. Then they can access it via the workspace URL.

   https://services.zillioninfo.com/zi/workspace/abc123xyz456

Next Steps

• Explore your workspace to analyze patterns in your data
• Create additional layers with different classification methods