Find Sites
find_sitesFind candidate search areas for data-center siting by state or coordinates, anchored on high-voltage substations with optional gas/fiber proximity filters. Get unranked starting points to analyze further when you need to know where to look.
Instructions
FRONT DOOR CHECK — if the question spans more than one capability ("find 200MW near Dallas with fiber, then rank the markets"), call execute_plan(intent="<the user's question, unchanged>"). find_sites is the right single call when the user has NO site yet and wants candidates to start from. THE INVERSE QUERY: every other DC Hub siting tool needs a coordinate you already have — analyze_site scores one, get_composite_site_score grades one, rank_sites orders candidates YOU already enriched, find_alternatives needs a seed facility. This one answers "where should I even be looking?". Returns candidate SEARCH AREAS anchored on real HIFLD substations at or above min_voltage_kv, spatially de-duplicated by cluster_km so a dense metro yields distinct areas instead of 40 near-identical rows, each carrying measured distance to the nearest gas pipeline and fiber route plus state-grain moratorium context, and a next_calls handoff. ★ WHAT A CANDIDATE IS NOT: a search area is NOT a parcel, NOT a listing, and NOT land known to be for sale — DC Hub holds no land-ownership or availability data, and hosted parcel boundaries cover ONE county (Loudoun VA), so analyze_parcel will 404 on most of these points BY DESIGN. Read each as "start looking here", then score the coordinate with analyze_site. ★ READ constraint_coverage BEFORE CALLING THIS A SCREENED LIST: a constraint filters ONLY when its layer actually answered. If a layer errors, the set comes back UNFILTERED with applied:false plus a reason and an instead, the names repeated in top-level unapplied_constraints and an unapplied_constraints_warning — an unevaluable constraint is never a passed constraint. fiber_distance_km is a straight-line CHORD between a route's endpoints, NOT the true polyline path; its basis is stamped on every candidate and get_fiber_readiness at the coordinate is the engineered read. hazard/moratorium are STATE grain, never a site verdict. A geography is REQUIRED — pass state, or lat+lon (+radius_km); without one you get a legible 400 (error_code geography_required), never a nationwide scan. Free tier coarsens coordinates to ~11 km and withholds operator/capacity. Answers "where should I even be looking for 200 MW in Ohio" and "which areas near Dallas sit on 230kV with gas within 5 miles". Try: find_sites state=OH min_voltage_kv=230 max_gas_km=8 — or find_sites lat=39.04 lon=-77.48 radius_km=60 min_voltage_kv=500. Do NOT use to score a site you already have (analyze_site), to rank candidates you already enriched (rank_sites), to find similar FACILITIES to a known one (find_alternatives), or for interconnection-queue survivors (get_refined_queue).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude of a search centre, e.g. 39.04 — use with lon (+ radius_km) instead of state | |
| lng | No | Alias for lon — either name works | |
| lon | No | Longitude of a search centre, e.g. -77.48 | |
| limit | No | Max results to return (1-500; default varies by tool) | |
| state | No | 2-letter US state to search, e.g. OH — required unless you pass lat + lon | |
| latitude | No | Alias for lat — either name works | |
| longitude | No | Alias for lon — either name works | |
| radius_km | No | Search radius in km around lat/lon (default 80, clamped 5-400); ignored in state mode | |
| cluster_km | No | Collapse anchors within this many km into one candidate area (default 8, max 100). Raise it for broader coverage, lower it for denser results | |
| max_gas_km | No | Drop candidates farther than this from the nearest gas pipeline. Applied ONLY if the gas layer answers — check constraint_coverage | |
| max_fiber_km | No | Drop candidates farther than this from the nearest fiber route (CHORD approximation — see fiber_distance_basis). Applied ONLY if the fiber layer answers | |
| min_voltage_kv | No | Only anchor on substations at or above this voltage in kV (default 115). 230+ for hyperscale, 500 for the largest campuses | |
| exclude_moratorium | No | true = drop candidates in a state with a published data-center moratorium. STATE grain, not jurisdiction grain |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| quota | No | Caller quota state (remaining calls, tier) when available. | |
| _entity | No | Payload class discriminator (e.g. facility|market|iso_grid|queue_results|deal|report|response) — branch on this before parsing the rest. | |
| citation | No | Machine-readable citation: how to attribute DC Hub (dchub.cloud) for this payload. Normally an OBJECT {source, url, license, cite_as, retrieved_at}; a bare string is accepted and carries the attribution line itself. | |
| provenance | No | Collection-level provenance block: {source, method, as_of, verification_counts, cite_url_template, license, cite_as}. Quote the verification level when citing. | |
| _front_door | No | In-band front-door hint (first workflow-entry tool of a session): call plan_query(intent) first for the ordered multi-step plan. | |
| _return_loop | No | Suggested next-session delta call (get_changes since=24h) so you pull only what changed. | |
| site_evaluation_handoff | No | Pre-built follow-up calls (analyze_site / get_water_risk args) when the payload carries coordinates — an array of {tool, parameters, why} entries. |