@studnicky/geo-layer-county

Geohash-indexed point-to-US-county-name lookup layer, built from US Census TIGER county boundary data.

CountyBuilder fetches US county boundaries via an AdministrativeSystemAdapterInterface (in production, USCensusTigerAdapter from @studnicky/geo-adapters) and encodes them into a compact geohash-indexed artifact through @studnicky/geo-boundary-layer-kit. CountyLookup decodes that artifact and answers lookup(lat, lon) in O(1), returning the containing county's name or null.

Install

pnpm add @studnicky/geo-layer-county

Requires @studnicky:registry=https://npm.pkg.github.com in .npmrc.

Basic lookup

CountyLookup.default() loads a small, entirely synthetic bundled artifact — enough to prove the lookup path end-to-end, not a real production dataset:

import { CountyLookup } from '../src/index.js';

function demonstrateBasicLookup(): { 'alpha': string | null; 'outside': string | null; 'synthetic': boolean } {
  // coverage reports which regions this layer's data source covers.
  console.log('coverage:', CountyLookup.coverage);

  const lookup = CountyLookup.default();

  // lookup resolves a point to a county name, or null outside every fixture county.
  const alpha = lookup.lookup(35, -119.5);
  console.log('lookup(35, -119.5):', alpha);

  const outside = lookup.lookup(0, 0);
  console.log('lookup(0, 0):', outside);

  // metadata.synthetic flags the bundled default as placeholder data, not real TIGER data.
  console.log('metadata.synthetic:', lookup.metadata.synthetic);

  return { 'alpha': alpha, 'outside': outside, 'synthetic': lookup.metadata.synthetic };
}

Building from a FeatureCollection

CountyBuilder builds a layer directly from a FeatureCollection, and BoundaryLayerLookup decodes the resulting artifact:

import { BoundaryLayerLookup, CountyBuilder } from '../src/index.js';

function demonstrateBuildFromFeatureCollection(): { 'east': string | null; 'mixedCellCount': number; 'tupleCount': number; 'west': string | null } {
  // Two side-by-side rectangular "counties" — small enough to build instantly, no network access.
  const featureCollection = {
    'features': [
      {
        'geometry': { 'coordinates': [[[-120, 34], [-119, 34], [-119, 36], [-120, 36], [-120, 34]]], 'type': 'Polygon' },
        'properties': { 'NAME': 'West County' },
        'type': 'Feature'
      },
      {
        'geometry': { 'coordinates': [[[-119, 34], [-118, 34], [-118, 36], [-119, 36], [-119, 34]]], 'type': 'Polygon' },
        'properties': { 'NAME': 'East County' },
        'type': 'Feature'
      }
    ],
    'type': 'FeatureCollection'
  };

  const result = CountyBuilder.buildFromFeatureCollection(featureCollection, {
    'maxDescentDepth': 2,
    'metadata': { 'fetchedAt': new Date().toISOString(), 'license': 'example', 'sourceId': 'example-fixture', 'synthetic': true }
  });

  console.log('tuple count:', result.tupleCount);
  console.log('mixed cell count:', result.mixedCellCount);

  const lookup = BoundaryLayerLookup.fromArtifact(result.artifact);

  const west = lookup.lookup(35, -119.5);
  console.log('lookup(35, -119.5):', west);

  const east = lookup.lookup(35, -118.5);
  console.log('lookup(35, -118.5):', east);

  return { 'east': east, 'mixedCellCount': result.mixedCellCount, 'tupleCount': result.tupleCount, 'west': west };
}

Source on GitHub