@brianfunk/areapi 1.0.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@brianfunk/areapi",
+  "version": "1.0.0",
+  "description": "Which FCC market area is this point in? CMA, BTA, MTA, EA, MEA, REAG, PEA lookup by latitude/longitude. Zero dependencies, no database.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "browser": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./data/*": "./data/*"
+  },
+  "bin": {
+    "areapi": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "data/*.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "build:data": "node scripts/build-data.js",
+    "build:site": "node scripts/build-site.js",
+    "dev": "netlify dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brianfunk/areapi.git"
+  },
+  "keywords": [
+    "fcc",
+    "cma",
+    "bta",
+    "mta",
+    "pea",
+    "market-area",
+    "geocoding",
+    "point-in-polygon",
+    "spectrum",
+    "wireless"
+  ],
+  "author": "Brian Funk",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/brianfunk/areapi/issues"
+  },
+  "homepage": "https://areapi.netlify.app",
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "mapshaper": "^0.7.72"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * areapi CLI
+ *
+ *   npx areapi 38.9907 -77.0261
+ *   npx areapi 38.9907 -77.0261 --types cma,bta --format json
+ *   npx areapi --types            # list area types
+ */
+import { parseArgs } from 'node:util';
+import { find, types, TYPES, TYPE_NAMES, AreapiError } from './index.js';
+import { format } from './format.js';
+
+const HELP = `areapi - which FCC market area is this point in?
+
+Usage:
+  areapi <lat> <lon> [--types cma,bta,...] [--format table|json|xml]
+  areapi --list
+
+Options:
+  -t, --types   comma-separated area types (default: all of ${TYPES.join(',')})
+  -f, --format  table (default on a terminal), json (default when piped), xml
+  -l, --list    list area types with counts and vintages
+  -h, --help    show this help
+`;
+
+// Negative coordinates look like flags to parseArgs; lift numeric args out first.
+const argv = process.argv.slice(2);
+const numeric = argv.filter((a) => /^-?\d+(\.\d+)?$/.test(a));
+const rest = argv.filter((a) => !numeric.includes(a));
+
+let args;
+try {
+  args = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      types: { type: 'string', short: 't' },
+      format: { type: 'string', short: 'f' },
+      list: { type: 'boolean', short: 'l' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+} catch (err) {
+  fail(err.message);
+}
+
+const { values } = args;
+const positionals = [...numeric, ...args.positionals];
+
+if (values.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+if (values.list) {
+  const m = await types();
+  const rows = Object.entries(m.types).map(([k, t]) => `${k.padEnd(5)} ${String(t.count).padStart(4)}  ${t.vintage}  ${TYPE_NAMES[k]}`);
+  process.stdout.write(rows.join('\n') + '\n');
+  process.exit(0);
+}
+
+if (positionals.length !== 2) fail('Expected <lat> <lon>.\n\n' + HELP);
+
+try {
+  const result = await find({ lat: positionals[0], lon: positionals[1] }, { types: values.types });
+  const fmt = values.format || (process.stdout.isTTY ? 'table' : 'json');
+  const { body } = format(result, fmt);
+  process.stdout.write(body + '\n');
+  process.exit(result.status === 'OK' ? 0 : 3);
+} catch (err) {
+  fail(err instanceof AreapiError ? err.message : err.stack);
+}
+
+function fail(msg) {
+  process.stderr.write(`areapi: ${msg}\n`);
+  process.exit(2);
+}

package/src/format.js

@@ -0,0 +1,66 @@
+/** Output serializers shared by the CLI and the HTTP function. */
+
+export const FORMATS = ['json', 'xml', 'jsonp', 'table'];
+
+export function toJSON(result) {
+  return JSON.stringify(result);
+}
+
+export function toJSONP(result, callback = 'callback') {
+  const cb = /^[A-Za-z_$][\w$.]*$/.test(callback) ? callback : 'callback';
+  return `/**/ typeof ${cb} === 'function' && ${cb}(${JSON.stringify(result)});`;
+}
+
+export function toXML(result, root = 'response') {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n${node(root, result)}`;
+}
+
+function node(name, value) {
+  if (Array.isArray(value)) {
+    const item = singular(name);
+    return `<${name}>${value.map((v) => node(item, v)).join('')}</${name}>`;
+  }
+  if (value && typeof value === 'object') {
+    return `<${name}>${Object.entries(value)
+      .map(([k, v]) => node(k, v))
+      .join('')}</${name}>`;
+  }
+  if (value == null) return `<${name}/>`;
+  return `<${name}>${escape(String(value))}</${name}>`;
+}
+
+function singular(name) {
+  if (name === 'areas') return 'area';
+  if (name === 'types') return 'type';
+  return name.endsWith('s') ? name.slice(0, -1) : 'item';
+}
+
+function escape(s) {
+  return s.replace(/[<>&'"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' })[c]);
+}
+
+export function toTable(result) {
+  const lines = [];
+  lines.push(`point   ${result.point.lat}, ${result.point.lon}`);
+  lines.push(`status  ${result.status}`);
+  if (result.areas.length) {
+    const w = Math.max(...result.areas.map((a) => a.id.length), 2);
+    for (const a of result.areas) {
+      lines.push(`${a.type.toUpperCase().padEnd(5)} ${a.id.padStart(w)}  ${a.name}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function format(result, fmt = 'json', callback) {
+  switch ((fmt || 'json').toLowerCase()) {
+    case 'xml':
+      return { body: toXML(result), contentType: 'application/xml; charset=utf-8' };
+    case 'jsonp':
+      return { body: toJSONP(result, callback), contentType: 'application/javascript; charset=utf-8' };
+    case 'table':
+      return { body: toTable(result), contentType: 'text/plain; charset=utf-8' };
+    default:
+      return { body: toJSON(result), contentType: 'application/json; charset=utf-8' };
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,87 @@
+export type AreaType = 'cma' | 'bta' | 'mta' | 'ea' | 'mea' | 'reag' | 'pea';
+
+export const TYPES: readonly AreaType[];
+export const TYPE_NAMES: Readonly<Record<AreaType, string>>;
+
+export interface Point {
+  lat: number;
+  lon: number;
+}
+
+export interface PointInput {
+  lat: number | string;
+  lon: number | string;
+}
+
+export interface Area {
+  type: AreaType;
+  /** Market number as a string, e.g. "8" */
+  id: string;
+  name: string;
+  vintage: string | null;
+}
+
+export interface FindOptions {
+  /** Subset of area types, as an array or comma-separated string. Default: all. */
+  types?: AreaType | string | readonly (AreaType | string)[];
+}
+
+export interface FindResult {
+  status: 'OK' | 'NONE';
+  point: Point;
+  types: AreaType[];
+  areas: Area[];
+  /** Milliseconds */
+  executionTime: number;
+}
+
+export interface AreaFeature {
+  type: 'Feature';
+  id: number;
+  bbox: [number, number, number, number];
+  properties: { id: string; name: string };
+  geometry: { type: 'Polygon'; coordinates: number[][][] } | { type: 'MultiPolygon'; coordinates: number[][][][] };
+}
+
+export interface Manifest {
+  generated: string;
+  simplify: string;
+  precision: string;
+  geometrySources: string[];
+  crosswalk: string;
+  names: string;
+  types: Record<AreaType, {
+    name: string;
+    vintage: string;
+    note: string;
+    count: number;
+    defined: number;
+    missing: { id: string; name: string }[];
+    bytes: number;
+  }>;
+}
+
+export class AreapiError extends Error {
+  name: 'AreapiError';
+  /** HTTP-style status, 400 for bad input, 404 for unknown routes. */
+  status: number;
+  constructor(message: string, status?: number);
+}
+
+/** Find every requested area type that contains the point. */
+export function find(point: PointInput, opts?: FindOptions): Promise<FindResult>;
+
+/** All features of one type containing the point (normally 0 or 1). */
+export function findType(type: AreaType, point: Point): Promise<Area[]>;
+
+/** GeoJSON Feature for one area, or null if the id is unknown. */
+export function feature(type: AreaType | string, id: string | number): Promise<AreaFeature | null>;
+
+/** The data manifest: counts, vintages, sources, missing ids. */
+export function types(): Promise<Manifest>;
+
+export function normalizeTypes(types?: FindOptions['types'] | null): AreaType[];
+export function normalizePoint(point: PointInput): Point;
+
+/** Browser only: base URL where <type>.json files are served from (default "data/"). */
+export function setDataUrl(url: string): void;

package/src/index.js

@@ -0,0 +1,117 @@
+/**
+ * areapi: which FCC market area is this point in?
+ *
+ *   import { find } from 'areapi';
+ *   const r = await find({ lat: 38.9907, lon: -77.0261 });
+ *   r.areas -> [{ type: 'cma', id: '8', name: 'Washington, DC-MD-VA', ... }, ...]
+ */
+
+import { inFeature } from './pip.js';
+import { load, loadManifest, setDataUrl } from './load.js';
+
+export { setDataUrl };
+
+/** Area types in display order. Keep in sync with data/manifest.json. */
+export const TYPES = ['cma', 'bta', 'mta', 'ea', 'mea', 'reag', 'pea'];
+
+export const TYPE_NAMES = {
+  cma: 'Cellular Market Area',
+  bta: 'Basic Trading Area',
+  mta: 'Major Trading Area',
+  ea: 'Economic Area',
+  mea: 'Major Economic Area',
+  reag: 'Regional Economic Area Grouping',
+  pea: 'Partial Economic Area',
+};
+
+export class AreapiError extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.name = 'AreapiError';
+    this.status = status;
+  }
+}
+
+export function normalizeTypes(types) {
+  if (types == null || types === '' || types === 'all') return [...TYPES];
+  const list = Array.isArray(types) ? types : String(types).split(',');
+  const out = [];
+  for (const raw of list) {
+    const t = String(raw).trim().toLowerCase();
+    if (!t) continue;
+    if (!TYPES.includes(t)) {
+      throw new AreapiError(`Unknown area type "${raw}". Valid types: ${TYPES.join(', ')}`);
+    }
+    if (!out.includes(t)) out.push(t);
+  }
+  if (out.length === 0) return [...TYPES];
+  return out;
+}
+
+export function normalizePoint({ lat, lon }) {
+  const la = Number(lat);
+  const lo = Number(lon);
+  if (lat == null || lat === '' || Number.isNaN(la) || la < -90 || la > 90) {
+    throw new AreapiError(`Invalid latitude "${lat}". Must be a number from -90 to 90.`);
+  }
+  if (lon == null || lon === '' || Number.isNaN(lo) || lo < -180 || lo > 180) {
+    throw new AreapiError(`Invalid longitude "${lon}". Must be a number from -180 to 180.`);
+  }
+  return { lat: la, lon: lo };
+}
+
+/** All features of one type that contain the point (normally 0 or 1). */
+export async function findType(type, { lat, lon }) {
+  const data = await load(type);
+  const hits = [];
+  for (const f of data.features) {
+    if (inFeature(lon, lat, f)) {
+      hits.push({
+        type,
+        id: String(f.properties.id),
+        name: f.properties.name,
+        vintage: data.vintage ?? null,
+      });
+    }
+  }
+  return hits;
+}
+
+/**
+ * @param {{lat: number|string, lon: number|string}} point
+ * @param {{types?: string|string[]}} [opts]
+ */
+export async function find(point, opts = {}) {
+  const start = now();
+  const p = normalizePoint(point);
+  const types = normalizeTypes(opts.types);
+  const perType = await Promise.all(types.map((t) => findType(t, p)));
+  const areas = perType.flat();
+  return {
+    status: areas.length ? 'OK' : 'NONE',
+    point: p,
+    types,
+    areas,
+    executionTime: round(now() - start),
+  };
+}
+
+/** Geometry for one area, for drawing. */
+export async function feature(type, id) {
+  const [t] = normalizeTypes(type);
+  const data = await load(t);
+  return data.features.find((f) => String(f.properties.id) === String(id)) ?? null;
+}
+
+/** Manifest: vintages, counts, sources. */
+export function types() {
+  return loadManifest();
+}
+
+function now() {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function round(ms) {
+  return Math.round(ms * 1000) / 1000;
+}

package/src/load.js

@@ -0,0 +1,74 @@
+/**
+ * Loads a market-area dataset by type. Works in Node (reads from the package's
+ * data/ directory) and in the browser (fetches from `dataUrl`, default "data/").
+ * Results are cached per type for the life of the process/page.
+ */
+
+const cache = new Map();
+const isBrowser = typeof window !== 'undefined' && typeof window.fetch === 'function';
+
+let dataUrl = 'data/';
+
+/** Browser only: where the <type>.json files live, relative or absolute. */
+export function setDataUrl(url) {
+  dataUrl = url.endsWith('/') ? url : url + '/';
+  cache.clear();
+}
+
+let nodeDataDir = null;
+
+/**
+ * Locate the data directory. Normally it sits next to src/ in the package, but
+ * bundlers (e.g. Netlify's esbuild) move this module, so fall back to the data/
+ * directory of the working directory or the Lambda task root.
+ */
+async function findDataDir() {
+  if (nodeDataDir) return nodeDataDir;
+  const { access } = await import('node:fs/promises');
+  const { fileURLToPath } = await import('node:url');
+  const path = await import('node:path');
+  const candidates = [
+    fileURLToPath(new URL('../data/', import.meta.url)),
+    path.join(process.cwd(), 'data'),
+    process.env.LAMBDA_TASK_ROOT && path.join(process.env.LAMBDA_TASK_ROOT, 'data'),
+    process.env.AREAPI_DATA_DIR,
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    try {
+      await access(path.join(dir, 'manifest.json'));
+      nodeDataDir = dir;
+      return dir;
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(`areapi: data directory not found (tried ${candidates.join(', ')})`);
+}
+
+async function readNode(name) {
+  const { readFile } = await import('node:fs/promises');
+  const path = await import('node:path');
+  const dir = await findDataDir();
+  return JSON.parse(await readFile(path.join(dir, `${name}.json`), 'utf8'));
+}
+
+async function readBrowser(name) {
+  const res = await fetch(`${dataUrl}${name}.json`);
+  if (!res.ok) throw new Error(`areapi: failed to load ${name}.json (${res.status})`);
+  return res.json();
+}
+
+export function load(name) {
+  if (!cache.has(name)) {
+    const p = (isBrowser ? readBrowser(name) : readNode(name)).catch((err) => {
+      cache.delete(name);
+      throw err;
+    });
+    cache.set(name, p);
+  }
+  return cache.get(name);
+}
+
+export function loadManifest() {
+  return load('manifest');
+}

package/src/pip.js

@@ -0,0 +1,77 @@
+/**
+ * Point-in-polygon for GeoJSON geometries. Ray casting, no dependencies.
+ *
+ * Coordinates are [lon, lat] as in GeoJSON. A point on an edge is treated as
+ * inside, which is what you want for "which market am I in" (never "none"
+ * just because you stood exactly on a county line).
+ */
+
+/** @param {number[]} bbox [minX, minY, maxX, maxY] */
+export function inBbox(x, y, bbox) {
+  return x >= bbox[0] && x <= bbox[2] && y >= bbox[1] && y <= bbox[3];
+}
+
+/** Is (x, y) inside a single linear ring? Even-odd rule. */
+export function inRing(x, y, ring) {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [xi, yi] = ring[i];
+    const [xj, yj] = ring[j];
+    // Edge touch: treat as inside.
+    if (onSegment(x, y, xi, yi, xj, yj)) return true;
+    const crosses = (yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+    if (crosses) inside = !inside;
+  }
+  return inside;
+}
+
+function onSegment(px, py, ax, ay, bx, by) {
+  const cross = (bx - ax) * (py - ay) - (by - ay) * (px - ax);
+  if (Math.abs(cross) > 1e-12) return false;
+  return (
+    px >= Math.min(ax, bx) - 1e-12 &&
+    px <= Math.max(ax, bx) + 1e-12 &&
+    py >= Math.min(ay, by) - 1e-12 &&
+    py <= Math.max(ay, by) + 1e-12
+  );
+}
+
+/** Polygon = [outerRing, ...holes]. Inside outer and not inside any hole. */
+export function inPolygon(x, y, rings) {
+  if (!inRing(x, y, rings[0])) return false;
+  for (let i = 1; i < rings.length; i++) {
+    if (inRing(x, y, rings[i])) return false;
+  }
+  return true;
+}
+
+/** Any GeoJSON Polygon or MultiPolygon geometry. */
+export function inGeometry(x, y, geometry) {
+  if (!geometry) return false;
+  if (geometry.type === 'Polygon') return inPolygon(x, y, geometry.coordinates);
+  if (geometry.type === 'MultiPolygon') {
+    return geometry.coordinates.some((rings) => inPolygon(x, y, rings));
+  }
+  return false;
+}
+
+/** Feature with optional precomputed bbox. */
+export function inFeature(x, y, feature) {
+  if (feature.bbox && !inBbox(x, y, feature.bbox)) return false;
+  return inGeometry(x, y, feature.geometry);
+}
+
+/** Compute a [minX, minY, maxX, maxY] bbox for a Polygon/MultiPolygon. */
+export function bboxOf(geometry) {
+  const b = [Infinity, Infinity, -Infinity, -Infinity];
+  const polys = geometry.type === 'Polygon' ? [geometry.coordinates] : geometry.coordinates;
+  for (const rings of polys) {
+    for (const [x, y] of rings[0]) {
+      if (x < b[0]) b[0] = x;
+      if (y < b[1]) b[1] = y;
+      if (x > b[2]) b[2] = x;
+      if (y > b[3]) b[3] = y;
+    }
+  }
+  return b;
+}