s2-geometry_skill

Overview

This skill indexes and queries geospatial data using Google's S2 Geometry concepts and the Python s2sphere wrapper. It emphasizes spherical-first geometry, hierarchical cell decomposition, and Hilbert-curve locality so spatial queries become efficient integer range scans. Use it to build proximity search, geofencing, sharding, and other location-based services that need robust, scalable spatial operations.

How this skill works

The skill converts latitude/longitude into S2 CellIds (64-bit integers) and operates on cells instead of raw coordinates. It builds region coverings (mixed-level cell sets) for shapes and caps, performs range queries over cell ID intervals, and uses post-filtering for exactness. Hilbert ordering preserves spatial locality so database range scans and shard routing are efficient.

When to use it

• Proximity search (find nearby places with radius queries)
• Geofencing and fast containment checks for delivery or access control
• Spatial sharding and routing to map geographic ranges to shards
• Region queries and spatial joins over irregular polygons
• When you need robust spherical geometry (avoid planar projection distortion)

Best practices

• Think in cells, not raw lat/lng; store CellIds for indexing and queries
• Pick a cell level matching real-world precision (e.g., level 16≈119m, level 12≈1.9km)
• Use RegionCoverer to approximate shapes and balance max_cells against query cost
• Always post-filter candidates from coverings to remove false positives
• Handle the antimeridian explicitly for regions crossing ±180°
• Leverage hierarchical queries: coarse-to-fine scans and ancestor prefix matching

Example use cases

• Find restaurants within 500m using a cap covering + range queries + distance post-filter
• Precompute delivery zones as cell unions and perform O(log n) containment checks
• Route requests to shards by dividing the CellId space into contiguous boundaries
• Perform spatial joins by intersecting cell unions for two datasets
• Run neighborhood analytics using a specific cell level to aggregate counts