Publish a Space-Time Patterns (VIS-STAMP) Page

This tutorial shows how to publish a Space-Time Patterns (VIS-STAMP) page using the ZillionInfo API.

Prerequisites

• A ZillionInfo account. If you don’t have one, you can sign up at ZillionInfo.
• An API key for authentication.
• Spatial data (unit data) and space-time attribute data uploaded to the platform.

Steps

1. Set up the data

   First, you need to set up the data for VIS-STAMP analysis by associating your spatial unit data with space-time attribute data.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/visstamp/app/api/setData" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "dataId": 123,       // ID of your spatial unit data
       "csvId": 456         // ID of your space-time attribute data
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/visstamp/app/api/setData"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "dataId": 123,  # ID of your spatial unit data
       "csvId": 456    # ID of your space-time attribute data
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))

   Parameters:

   • dataId: The ID of your spatial unit data (spatial data representing geographic units)
   • csvId: The ID of your space-time attribute data (containing time series data for each spatial unit)

   Response:

   {
     "csvContextId": 789,
     "featureIdField": "unit_id",
     "unitFields": ["field1", "field2", "field3"],
     "numericFields": {
       "0": "field4",
       "1": "field5",
       "2": "field6"
     }
   }

   The response provides:

   • csvContextId: A context ID for subsequent API calls
   • featureIdField: The field name that can be used to join the spatial data with attribute data
   • unitFields: Available fields in the unit data
   • numericFields: Numeric fields in the space-time attribute data that can be used for analysis

2. Set the feature ID field (optional)

   If you need to change the feature ID field used to join the spatial data with the attribute data:

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/visstamp/app/api/setFeatureIdField" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "csvContextId": 789,
       "featureIdField": "field2"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/visstamp/app/api/setFeatureIdField"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "csvContextId": 789,
       "featureIdField": "field2"
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))

   Parameters:

   • csvContextId: The context ID received from the previous step
   • featureIdField: The field name to use for joining the spatial data with attribute data

3. Submit the VIS-STAMP request

   Now submit the VIS-STAMP analysis request with your selected variables and parameters:

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/visstamp/app/api/classes" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "csvContextId": 789,
       "somSize": 3,
       "variables": {
         "vars": [0, 1, 2],
         "nors": [-1, -1, -1],
         "weights": [1.0, 1.0, 1.0]
       }
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/visstamp/app/api/classes"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "csvContextId": 789,
       "somSize": 3,
       "variables": {
           "vars": [0, 1, 2],
           "nors": [-1, -1, -1],
           "weights": [1.0, 1.0, 1.0]
       }
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))

   Parameters:

   • csvContextId: The context ID received from the first step
   • somSize: The size of the Self-Organizing Map (SOM) grid (e.g., 3 creates a 3×3 grid with 9 clusters)
   • variables: Configuration for the variables to use in the analysis:
     • vars: Array of indices for the variables to include (based on the order of fields in the data)
     • nors: Array of normalization variable indices (use -1 for no normalization)
     • weights: Array of weights for each variable (1.0 means equal weighting)

   Response:

   {
     "jobID": "abc123"
   }

   The response provides a jobID that you’ll use to check the status of your analysis.

4. Check the status of the request

   VIS-STAMP analysis may take some time to complete. You can check the status using the job ID:

   cURL

   curl -X GET "https://services.zillioninfo.com/zi/visstamp/app/api/status?jobId=abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

   Python

   import requests
   import json
   import time
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/visstamp/app/api/status"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY"
   }
   
   # Parameters
   params = {
       "jobId": "abc123"
   }
   
   # Function to check job status
   def check_job_status():
       response = requests.get(url, headers=headers, params=params)
       return response.json()
   
   # Poll for job completion
   status = "waiting"
   while status in ["waiting", "running"]:
       result = check_job_status()
       status = result.get("status")
       print(f"Current status: {status}")
   
       if status in ["finished", "failed"]:
           print(json.dumps(result, indent=2))
           break
   
       # Wait before checking again
       time.sleep(1)

   Parameters:

   • jobId: The job ID received from the previous step

   Response:

   {
     "status": "running",
     "result": null
   }

   The status can be:

   • waiting: Job is in the queue
   • running: Job is currently processing
   • finished: Job has completed successfully
   • failed: Job has failed

5. Get the result

   Once the status is finished, the response will include the results:

   {
     "status": "finished",
     "result": {
       // Classification results
     },
     "link": "https://services.zillioninfo.com/zi/visstamp/app/embedFrame?o=xyz123",
     "embedCode": "<div id='jkl'><script async src='https://services.zillioninfo.com/zi/visstamp/app/embed?o=xyz123'></script></div>"
   }

   The response provides:

   • result: The detailed classification results
   • link: A URL to view the results in a web browser
   • embedCode: HTML code to embed the results in your website

6. Use the results in your application

   HTML

   <!DOCTYPE html>
   <html>
   <head>
     <title>VIS-STAMP Results</title>
   </head>
   <body>
     <h1>Space-Time Pattern Analysis Results</h1>
   
     <!-- Embed the VIS-STAMP visualization -->
     <div id='jkl'>
       <script async src='https://services.zillioninfo.com/zi/visstamp/app/embed?o=xyz123'></script>
     </div>
   </body>
   </html>

   Python

   import requests
   import webbrowser
   import json
   import os
   
   # Save the results to a file
   def save_results(result_data, filename="visstamp_results.json"):
       with open(filename, 'w') as f:
           json.dump(result_data, f, indent=2)
       print(f"Results saved to {filename}")
   
   # Open the visualization in a web browser
   def open_visualization(link):
       webbrowser.open(link)
       print(f"Opened visualization at {link}")
   
   # Example usage with the results from the previous step
   result_data = {
       "status": "finished",
       "result": {
           # Classification results would be here
       },
       "link": "https://services.zillioninfo.com/zi/visstamp/app/embedFrame?o=xyz123",
       "embedCode": "<div id='jkl'><script async src='https://services.zillioninfo.com/zi/visstamp/app/embed?o=xyz123'></script></div>"
   }
   
   # Save the results
   save_results(result_data)
   
   # Open the visualization
   open_visualization(result_data["link"])
   
   # Print the embed code for use in web applications
   print("Embed code for your website:")
   print(result_data["embedCode"])

Next Steps

• Explore the VIS-STAMP results to identify space-time patterns in your data
• Share the results with others using the provided link or embed code
• Create additional visualizations based on the classification results