Technical tools for
the geometry spine.

Technical scope

This page is for implementation work: tool names, request shapes, bridge fields, and workflow patterns. If you want the plain-English explanation of what loc_id, the geometry spine, and sibling layers mean, start with the loc_id guide.

The short version: admin layers form the canonical spine, sibling layers overlap that spine, and these tools convert between those systems without fuzzy place-name matching.

Admin layers

Admin layers are the nested geography backbone. Each row has a loc_id, a parent, a level, names, centroid, bbox, and optional full geometry. The global base covers admin_0 through admin_2; country-specific extensions can continue to admin_3, admin_4, admin_5, or deeper where official geometry exists.

The runtime keeps serving files optimized for map and query performance. Research geometry packages are derived publication bundles built from that same spine, not a separate geography model.

Sibling layers and bridges

Some useful shapes do not fit cleanly inside that hierarchy. ZCTAs, tribal areas, watersheds, forests, parks, building footprints, and other overlays are sibling geometry families. They overlap the spine rather than nesting perfectly inside it, so they need explicit bridge artifacts before they can be compared to admin-spine data.

Bridges store measured overlap between sibling shapes and admin shapes. That is what lets a ZIP-like input map to tracts, a tribal area map to counties, or a future watershed layer map back to the administrative places used by published packs.

Conversion tools return crosswalk results first: ids, labels, overlap weights, provenance, and geometry-bank references. They do not inline polygons by default. When a matching shape bank is available, callers can ask for the boundary separately with get_geometry or get_boundary. This keeps one-off API/MCP calls small while preserving a clean path to full shape downloads.

Why loc_id ties it together

loc_id is the durable join key. Data packs do not need to carry duplicate state, county, tract, or parent columns when the geometry spine already owns that hierarchy. The same id can drive a map selection, a structured query filter, a report citation, and a downstream agent call.

Core MCP tools

These free geography tools resolve locations on the same spine used by every published pack.

Call them through MCP

Use the umbrella MCP endpoint for all tools, or the geography facade when you only want geography utilities.

POST https://app.daedalmap.com/mcp
POST https://app.daedalmap.com/mcp/geography

MCP calls use a JSON-RPC envelope. Put the tool name in params.name and the tool input in params.arguments.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "resolve_reference",
    "arguments": {
      "from_system": "zip",
      "value": "00601",
      "target_admin_level": "county",
      "limit": 5,
      "request_id": "resolve-zcta-00601-county-001"
    }
  }
}

Reference exchange

Use list_reference_systems when you are not sure what can be exchanged. Use resolve_reference for X -> loc_id, loc_id_references for loc_id -> known references, and convert_reference for X -> loc_id -> Y. Older bridge tools remain available as compatibility aliases.

The same split applies to downloads: lite releases contain the crosswalk and provenance; full releases add the shape banks and indexes. Hosted tools can serve individual shapes without requiring a user to pull a full polygon bundle.

Point to loc_id

Use resolve_point when you have coordinates from a map click, field record, sensor, asset, or event feed. The response gives the deepest known match plus the broader chain, so the caller can use the same point at county, state, or country scope.

{
  "tool": "resolve_point",
  "arguments": {
    "lat": 40.7484,
    "lon": -73.9857
  }
}

loc_id to geometry

Use get_boundary when you already have a loc_id and need map extent, clipping geometry, or a display boundary. The default response stays small with bbox and centroid. Set include_polygon only when the full perimeter is needed.

{
  "tool": "get_boundary",
  "arguments": {
    "loc_id": "USA-NY-061",
    "include_polygon": false
  }
}

Hierarchy and metadata

loc_id_hierarchy is for walking the spine. It answers questions such as "what county contains this tract?" and "what child levels exist under this place?" loc_id_info is the compact record lookup when the caller needs name, level, parent, bbox, or centroid for one id.

Sibling-layer bridges

Sibling-layer bridge tools convert between unusual shapes and administrative loc_id values using measured polygon overlap. They do not guess from a centroid when an area spans multiple places. They return the primary match and the ranked overlap list.

The USA bridge set covers overlay_zcta and overlay_tribal against admin_0 through admin_4. That means country, state, county, tract, and block group outputs are available from the same contract.

Sibling layer to admin

Use sidechain_to_admin when the input is a sibling-layer geometry id and the output should be an administrative level. This is the ZIP/ZCTA-to-tract pattern, but the tool is not ZIP-specific.

{
  "tool": "sidechain_to_admin",
  "arguments": {
    "source_family": "overlay_zcta",
    "source_loc_id": "USA-Z-10001",
    "target_admin_level": "admin_3",
    "limit": 10
  }
}

The response includes primary_match, source_area_share, target_area_share, and overlaps. For a ZCTA that crosses several tracts, the caller can use the top match for a simple answer or the overlap list for a weighted allocation.

Admin to sibling layer

Use admin_to_sidechain when the input is a canonical administrative loc_id and the output should be the overlapping sibling-layer shapes. This answers questions such as "which ZCTAs overlap this block group?" or "which tribal areas overlap this county?"

{
  "tool": "admin_to_sidechain",
  "arguments": {
    "target_loc_id": "USA-NY-061-009903-2",
    "source_family": "overlay_zcta",
    "target_admin_level": "admin_4",
    "limit": 10
  }
}

Reading overlap shares

Bridge results carry two percentages because the direction matters. source_area_share answers "how much of the sibling-layer shape falls inside this admin place?" target_area_share answers "how much of the admin place is covered by this sibling-layer shape?"

ZIP codes and ZCTAs

The bridge uses Census ZCTAs, not live USPS delivery ZIP routes. ZCTAs are polygon approximations that work well for Census-aligned analysis, site selection, demographics, market research, and bulk enrichment. For mail-delivery operations, keep the USPS distinction visible in the output.

Workflow patterns

• Map click: call resolve_point, keep the returned loc_id, then query packs with filters.region_ids.
• Boundary display: call get_boundary with include_polygon only for map rendering or exact clipping.
• ZIP enrichment: call resolve_reference with from_system: "zip", then join demographics or pack metrics at the returned loc_id.
• Cross-system lookup: call convert_reference to translate ZIP/ZCTA, NWS zones, tribal areas, and future systems through loc_id.
• Reverse lookup: call loc_id_references to find overlapping ZCTAs, tribal areas, NWS zones, or other known references for an existing loc_id.