Analyze Site
analyze_siteUse when a user has ONE specific lat/lon (a parcel, a candidate site) and wants the full multi-factor data-center suitability read in one call. Example: "Score this Phoenix parcel for a 100MW build — power, gas, fiber, market & risk." — analyze_site lat=33.45 lon=-112.07 capacity_mw=100 state=AZ. Params: lat (-90 to 90, required unless candidate_id or location), lon (-180 to 180, required unless candidate_id or location), location (a market NAME or metro slug instead of coordinates, e.g. location="ashburn" — resolved to that market's PUBLISHED CENTROID through the DCPI market row, with a resolved_from block naming what it resolved to; a MARKET-level read, NOT the parcel you named, and a trailing state is not stripped so "Ashburn, VA" will not resolve), candidate_id (a cand_… from get_refined_queue — resolves coordinates from the frozen mint and ignores lat/lon), capacity_mw (target load in MW, e.g. 50-500 — returns a capacity_context block sizing that load against nearby installed generation; it deliberately does NOT move overall_score, and the block names where the load IS applied), state (2-letter US, optional — improves the tax-incentive/context lookup), include_grid/include_risk/include_fiber (booleans, default true). Returns (full, paid): {overall_score (aka composite_score, 0-100 composite — for the integrity-first version that never imputes a missing factor, use get_composite_site_score), interpretation (verdict string, e.g. "Excellent site"), scores{power_infrastructure, gas_pipeline_access, fiber_connectivity, market_conditions, risk_resilience — each 0-100}, nearby{substations_50km, power_plants_80km, gas_pipelines_50km, facilities_100km, fiber_carriers_in_state, generation_capacity_mw, total_capacity_mw}, power_cost{industrial_cents_kwh, commercial_cents_kwh, period, basis}, fiber{connectivity_score, nearest_carrier_km, near_net_bucket, top_carriers[], single_carrier_risk}, location, citation}. FREE tier returns a REAL, citable HEADLINE — composite_score + verdict + the single top limiting factor (the lowest sub-score) + citation; the full per-factor breakdown, nearby infrastructure, power cost, fiber carriers, and the branded Site Analysis PDF (generate_site_analysis) are Pro. For dedicated water / disaster / climate / tax reads use get_water_risk / get_disaster_risk / get_climate_intel / get_tax_incentives. Do NOT use to compare 2+ sites (use compare_sites) or to find sites that match a target (use find_alternatives).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Site latitude in decimal degrees (-90 to 90; required unless candidate_id or location given), e.g. 33.45 | |
| lng | No | Alias for lon — either name works | |
| lon | No | Site longitude in decimal degrees (-180 to 180; required unless candidate_id or location given), e.g. -112.07 | |
| state | No | US state abbreviation (optional) — improves the tax-incentive lookup, e.g. AZ | |
| mpp_pay | No | Autonomous payment (Stripe MPP), step 1: set true to receive a signed $0.50 payment challenge for this call instead of the free preview. No money moves — a challenge is a price quote. Humans never set this, so it does not affect the normal free/trial funnel. | |
| latitude | No | Alias for lat — either name works | |
| location | No | Market NAME or metro slug instead of coordinates, e.g. "ashburn", "northern-virginia", "dallas". Resolved to that market's PUBLISHED CENTROID through the DCPI market row, and the answer carries a resolved_from block saying so. This is a MARKET-level read, not the parcel you named — pass lat/lon for a specific site. Not an alias for lat/lon: a place name is not a coordinate. | |
| longitude | No | Alias for lon — either name works | |
| capacity_mw | No | Target power load for the build in megawatts (MW), e.g. 100 (typical 50-500) | |
| candidate_id | No | PREFERRED for queue survivors: a cand_… id from get_refined_queue — coordinates come from the FROZEN mint (lat/lon args are ignored; zero transcription drift; expired ids fail closed with candidate_expired). See dchub.cloud/docs/candidate-lifecycle | |
| include_grid | No | Include grid-headroom / substation analysis (default true) | |
| include_risk | No | Include water/drought/climate risk analysis (default true) | |
| include_fiber | No | Include fiber-connectivity analysis (default true) | |
| mpp_credential | No | Autonomous payment (Stripe MPP), step 2: the Shared Payment Token you minted for challenges[0]. Set it here to pay $0.50 for this single call and receive the full result — no API key, no subscription, no human. One payment covers one call. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fiber | No | Fiber read: {connectivity_score, nearest_carrier_km, near_net_bucket, top_carriers[], single_carrier_risk} (full payload) | |
| quota | No | Caller quota state (remaining calls, tier) when available. | |
| locked | No | Which sections are Pro-locked on the free headline: {per_factor_breakdown, nearby_infrastructure, power_cost, fiber_carriers, site_analysis_report} | |
| nearby | No | Nearby infrastructure counts: {substations_50km, power_plants_80km, gas_pipelines_50km, facilities_100km, fiber_carriers_in_state, generation_capacity_mw, total_capacity_mw} (full payload) | |
| scores | No | Per-factor breakdown (full/paid payload) | |
| _entity | No | Payload class discriminator (e.g. facility|market|iso_grid|queue_results|deal|report|response) — branch on this before parsing the rest. | |
| preview | No | Headline preview line (free tier) | |
| verdict | No | Verdict string, e.g. "Excellent site" / BUILD-CAUTION-AVOID read | |
| 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. | |
| location | No | Echo of the analyzed location (full payload) | |
| power_cost | No | Power cost read: {industrial_cents_kwh, commercial_cents_kwh, period, basis} (full payload) | |
| 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. | |
| overall_score | No | Alias of composite_score on the full payload | |
| site_headline | No | true when this is the free citable HEADLINE (score + verdict + limiting factor) | |
| interpretation | No | Verdict prose on the full payload | |
| composite_score | No | 0-100 composite site suitability score (free HEADLINE tier and full tier) | |
| limiting_factor | No | Single top limiting factor (the lowest sub-score) — always present on the free headline | |
| 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. |