mapping location data with Axiom and Hex (#254)

Co-authored-by: Mano Toth <[email protected]>
Co-authored-by: Mano Toth <[email protected]>

Author: thecraftman

apps/hex.mdx

@@ -0,0 +1,137 @@
+---
+title: 'Map location data with Axiom and Hex'
+description: "This page exlains how to visualize geospatial log data from Axiom using Hex interactive maps."
+sidebarTitle: 'Hex'
+---
+
+import Prerequisites from "/snippets/standard-prerequisites.mdx"
+import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
+import ReplaceDomain from "/snippets/replace-domain.mdx"
+import ReplaceDataset from "/snippets/replace-dataset.mdx"
+
+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 />
+{/* list separator */}
+- [Create a Hex account](https://app.hex.tech/).
+
+## 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.
+
+```bash
+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"
+    }
+    }
+]'
+```
+
+<ReplaceDatasetToken />
+<ReplaceDomain />
+
+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](https://learn.hex.tech/docs/getting-started/create-your-first-project).
+1. 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](https://learn.hex.tech/docs/explore-data/projects/environment-configuration/environment-views#secrets).
+
+## Query data from Axiom
+
+Write the Python code in your Hex notebook that retrieves data from Axiom. For example, customize the code below:
+
+```python
+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)}")
+```
+
+<ReplaceDomain />
+<ReplaceDataset />
+
+## Create map visualisation
+
+Create an interactive map visualization in Hex and customize it. For more information, see the [Hex documentation](https://learn.hex.tech/docs/explore-data/cells/visualization-cells/map-cells).

docs.json

@@ -284,6 +284,7 @@
               "apps/cloudflare-workers",
               "apps/cloudflare-logpush",
               "apps/grafana",
+              "apps/hex",
               "apps/netlify",
               "apps/tailscale",
               "apps/terraform",

snippets/replace-dataset.mdx

@@ -1 +1 @@
-Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
+- Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.

snippets/replace-domain.mdx

@@ -0,0 +1 @@
+- 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](/reference/regions).