Map location data with Axiom and Hex

This page exlains how to visualize geospatial log data from Axiom using Hex interactive maps.

Hex is a powerful collaborative data platform that allows you to create notebooks with Python/SQL code and interactive visualizations.

This page explains how to integrate Hex with Axiom to visualize geospatial data from your logs. You ingest location data into Axiom, query it using APL, and create interactive map visualizations in Hex.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to update the dataset you have created.

• Create a Hex account.

Send geospatial data to Axiom

Send your sample location data to Axiom using the API endpoint. For example, the following HTTP request sends sample robot location data with latitude, longitude, status, and satellite information.

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '[
    {
    "data": {
        "robot_id": "robot-001",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "num_satellites": 8,
        "status": "active"
    }
    }
]'

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Verify that your data has been ingested correctly by running an APL query in the Axiom UI.

Set up your Hex project

1. Create a new Hex project. For more information, see the Hex documentation.
2. Save your Axiom API token as a secret in Hex. This example uses the secret name AXIOM_API_TOKEN. For more information, see the Hex documentation.

Query data from Axiom

Write the Python code in your Hex notebook that retrieves data from Axiom. For example, customize the code below:

import requests
import pandas as pd
from datetime import datetime, timedelta
import os

# Retrieve the API token from Hex secrets
axiom_token = os.environ.get("AXIOM_API_TOKEN")

# Define Axiom API endpoint and headers
base_url = "https://AXIOM_DOMAIN/v1/datasets/_apl"
headers = {
    'Authorization': f'Bearer {axiom_token}',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Accept-Encoding': 'gzip'
}

# Define the time range for your query
end_time = datetime.utcnow()
start_time = end_time - timedelta(days=3)  # Get data from the last 3 days

# Construct the APL query
query = {
    "apl": """DATASET_NAME
| project ['data.latitude'], ['data.longitude'], ['data.num_satellites'], ['data.robot_id'], ['data.status']""",
    "startTime": start_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
    "endTime": end_time.strftime("%Y-%m-%dT%H:%M:%SZ")
}

try:
    # Send the request to Axiom API
    response = requests.post(
        f"{base_url}?format=tabular",
        headers=headers,
        json=query,
        timeout=10
    )
    
    # Print request details for debugging
    print("Request Details:")
    print(f"URL: {base_url}?format=tabular")
    print(f"Query: {query['apl']}")
    print(f"Response Status: {response.status_code}")
    
    if response.status_code == 200:
        data = response.json()
        if 'tables' in data:
            table = data['tables'][0]
            if table.get('columns') and len(table['columns']) > 0:
                columns = [field['name'] for field in table['fields']]
                rows = table['columns']
                
                # Create DataFrame with proper column orientation
                df = pd.DataFrame(list(zip(*rows)), columns=columns)
                
                # Ensure data types are appropriate for mapping
                df['data.latitude'] = pd.to_numeric(df['data.latitude'])
                df['data.longitude'] = pd.to_numeric(df['data.longitude'])
                df['data.num_satellites'] = pd.to_numeric(df['data.num_satellites'])
                
                # Display the first few rows to verify our data
                print("\nDataFrame Preview:")
                display(df.head())
                
                # Store the DataFrame for visualization
                robot_locations = df
            else:
                print("\nNo data found in the specified time range.")
        else:
            print("\nNo tables found in response")
            print("Response structure:", data.keys())
            
except Exception as e:
    print(f"\nError: {str(e)}")

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

Create map visualisation

Create an interactive map visualization in Hex and customize it. For more information, see the Hex documentation.