H3 Tools

The @openassistant/h3 package provides hexagonal spatial indexing using Uber's H3 library.

Installation

npm install @openassistant/h3

Features

• Convert coordinates to H3 indexes
• Get H3 cell children
• Generate H3 cells from polygons
• Multi-resolution spatial analysis

Available Tools

h3Cell

Convert a latitude/longitude coordinate to an H3 cell at a given resolution.

h3CellToChildren

Get the children of a given H3 cell at the next resolution level.

h3CellsFromPolygon

Get all H3 cells that cover a polygon at a given resolution.

Basic Usage

H3 Cell Tool

import { h3Cell } from '@openassistant/h3';
import { convertToVercelAiTool } from '@openassistant/utils';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const h3CellTool = {
  ...h3Cell,
};

const result = await generateText({
  model: openai('gpt-4'),
  prompt: 'Get the H3 cell for coordinates 37.7749, -122.4194 at resolution 9',
  tools: {
    h3Cell: convertToVercelAiTool(h3CellTool),
  },
});

console.log(result.text);

H3 Cell to Children Tool

import { h3CellToChildren } from '@openassistant/h3';
import { convertToVercelAiTool } from '@openassistant/utils';
import { generateText } from 'ai';

const h3CellToChildrenTool = {
  ...h3CellToChildren,
};

const result = await generateText({
  model: openai('gpt-4'),
  prompt: 'Get the children of H3 cell 89283082837ffff',
  tools: {
    h3CellToChildren: convertToVercelAiTool(h3CellToChildrenTool),
  },
});

H3 Cells From Polygon Tool

import { h3CellsFromPolygon } from '@openassistant/h3';
import { convertToVercelAiTool, ToolCache } from '@openassistant/utils';
import { Assistant } from '@openassistant/assistant';

const toolResultCache = ToolCache.getInstance();

const h3CellsFromPolygonTool = {
  ...h3CellsFromPolygon,
  context: {
    getGeometries: async (datasetName: string) => {
      // Return GeoJSON FeatureCollection(s) containing polygons
      if (toolResultCache.hasDataset(datasetName)) {
        const data = toolResultCache.getDataset(datasetName);
        // Make sure to return array of FeatureCollections
        return [data.content];
      }
      throw new Error(`Dataset ${datasetName} not found`);
    },
  },
};

const config = {
  ai: {
    getInstructions: () => `You can generate H3 cells from polygon datasets.`,
    tools: {
      h3CellsFromPolygon: h3CellsFromPolygonTool,
    },
  },
};

export function App() {
  return <Assistant options={config} />;
}

Usage with Assistant

import { h3Cell, h3CellToChildren, h3CellsFromPolygon } from '@openassistant/h3';
import { Assistant, type AssistantOptions } from '@openassistant/assistant';

const POLYGON_DATASETS = {
  neighborhoods: {
    type: 'FeatureCollection',
    features: [
      {
        type: 'Feature',
        geometry: {
          type: 'Polygon',
          coordinates: [[[-122.4, 37.7], [-122.4, 37.8], [-122.3, 37.8], [-122.3, 37.7], [-122.4, 37.7]]],
        },
        properties: { name: 'Downtown' },
      },
    ],
  },
};

const h3CellsFromPolygonTool = {
  ...h3CellsFromPolygon,
  context: {
    getGeometries: async (datasetName: string) => {
      return [POLYGON_DATASETS[datasetName]];
    },
  },
};

const config: AssistantOptions = {
  ai: {
    getInstructions: () => `
      You can work with H3 hexagonal spatial indexing.
      Available datasets: neighborhoods (polygon dataset)
    `,
    tools: {
      h3Cell: { ...h3Cell },
      h3CellToChildren: { ...h3CellToChildren },
      h3CellsFromPolygon: h3CellsFromPolygonTool,
    },
  },
};

export function App() {
  return <Assistant options={config} />;
}

H3 Resolution Levels

H3 provides 16 resolution levels (0-15):

• Resolution 0: ~4,250 km² per cell (continent scale)
• Resolution 5: ~252 km² per cell (large city scale)
• Resolution 9: ~0.1 km² per cell (neighborhood scale)
• Resolution 12: ~307 m² per cell (building scale)
• Resolution 15: ~0.9 m² per cell (room scale)

Choose resolution based on your analysis needs - higher resolutions provide more detail but generate more cells.

Context Options

h3CellsFromPolygon Context

type H3ToolContext = {
  // Required: Get GeoJSON FeatureCollection(s) containing polygon geometries
  getGeometries: (datasetName: string) => Promise<GeoJSON.FeatureCollection[]>;
};

Example User Prompts

The AI can respond to prompts like:

• "What is the H3 cell for San Francisco City Hall at resolution 9?"
• "Get the children cells of H3 index 89283082837ffff"
• "Generate H3 cells for the downtown polygon at resolution 10"
• "Cover the neighborhoods dataset with resolution 8 hexagons"

Use Cases

Spatial Aggregation

Use H3 cells to aggregate point data into hexagonal bins:

1. Convert points to H3 cells at desired resolution
2. Count points per H3 cell
3. Visualize as hexbin map

Multi-Resolution Analysis

Use H3's hierarchical structure to analyze data at multiple scales:

1. Start with H3 cells at coarse resolution
2. Get children cells for areas of interest
3. Perform detailed analysis at finer resolution

Coverage Analysis

Use h3CellsFromPolygon to:

• Calculate coverage area in hexagonal units
• Generate regular grids over irregular polygons
• Create service areas at standard distances

API Reference

For detailed API documentation, see the H3 API Reference.

Next Steps

• Map Tools - Visualize H3 cells on maps
• GeoDA Tools - Spatial analysis with H3 aggregated data