{"openapi":"3.1.0","info":{"title":"DC Hub \u2014 Data Center Intelligence API","version":"2.4.4","description":"DC Hub provides real-time data center intelligence: facility search (21,000+ facilities, 170+ countries), M&A deal tracking, construction pipeline data, energy pricing, and site scoring.","contact":{"name":"DC Hub Support","url":"https://dchub.cloud","email":"info@dchub.cloud"},"termsOfService":"https://dchub.cloud/terms","license":{"name":"Proprietary","url":"https://dchub.cloud/terms"},"x-dchub-envelope":"1.0"},"servers":[{"url":"https://dchub.cloud","description":"Production"}],"paths":{"/api/v1/stats":{"get":{"operationId":"getStats","summary":"Platform statistics","description":"Returns global stats: total facilities, countries, providers, capacity (MW)","responses":{"200":{"description":"Platform statistics"}},"tags":["Public"]}},"/api/v1/interconnection-queue/refined":{"get":{"operationId":"getRefinedQueue","summary":"Server-side set-reduction over the ISO interconnection queue","description":"Filters ~5,300 US interconnection-queue projects (7 ISOs) server-side so an agent ingests survivors, not the raw ~1,744 GW queue (avoids in-context-filter token blowup). Predicates: min_mw, max_ttp_months (ISO-level estimate), iso (comma union), baseload_only, fuel_type, and the Phase-2 spatial predicates max_fiber_km + geocoded_only. Returns the DCHubEnvelope with _entity=queue_results; ~83% of survivors carry lat/lng + a compact per-survivor site_evaluation_handoff (ready-to-pipe analyze_site + get_water_risk args).","parameters":[{"name":"min_mw","in":"query","schema":{"type":"number"},"description":"Minimum project capacity in MW (e.g. 1000 for 1 GW+)"},{"name":"max_ttp_months","in":"query","schema":{"type":"integer"},"description":"Max time-to-power in months (ISO-level avg interconnection wait; keeps projects in ISOs at or under this)"},{"name":"iso","in":"query","schema":{"type":"string"},"description":"Restrict to one or more ISOs (comma-separated union), from PJM/ERCOT/MISO/CAISO/SPP/NYISO/ISO-NE. e.g. iso=ERCOT,PJM. Hyphens are normalized (ISONE == ISO-NE). Combines with max_ttp_months as an intersection."},{"name":"baseload_only","in":"query","schema":{"type":"boolean","default":false},"description":"Keep only firm/dispatchable fuel; exclude wind/solar/storage. (Firm/intermittent split only \u2014 does NOT sub-divide peaker vs combined-cycle gas; the queue has no duty-cycle field.)"},{"name":"fuel_type","in":"query","schema":{"type":"string"},"description":"Inclusive substring match on the raw fuel label; comma/semicolon separated for a union (e.g. 'gas' hits GAS/Natural Gas, 'nuclear,hydro' unions both). Use to isolate a specific generation class server-side instead of post-filtering in context."},{"name":"status","in":"query","schema":{"type":"string","default":"active"},"description":"Queue status filter. Default 'active' = still progressing (excludes withdrawn/cancelled/suspended/in-commercial-operation) \u2014 cross-ISO safe, since SPP labels live projects 'IA FULLY EXECUTED/ON SCHEDULE' etc. rather than 'active'. 'all' = no filter; any other value = literal substring match."},{"name":"max_fiber_km","in":"query","schema":{"type":"number"},"description":"Keep only survivors within this many km of the nearest MAPPED long-haul fiber route endpoint (coarse backbone proximity from a sparse ~260-node dataset, over a county-centroid origin \u2014 NOT last-mile fiber distance). Implies geocoded rows only."},{"name":"geocoded_only","in":"query","schema":{"type":"boolean","default":false},"description":"Keep only survivors that carry lat/lng (~83% of the queue) \u2014 i.e. those an agent can pipe straight into analyze_site via the site_evaluation_handoff."},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":1000},"description":"Max survivors returned"}],"responses":{"200":{"description":"Refined queue survivors (_entity=queue_results)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/analyze-parcel":{"post":{"operationId":"analyzeParcel","summary":"Structured read of a GeoJSON parcel boundary (Phase 3)","description":"Geodesic acreage + largest-member centroid as representative_point (never the multi-part center) + contiguous flag + per-member breakdown + a site_evaluation_handoff, for any GeoJSON Polygon/MultiPolygon. Reads any polygon you pass; DC Hub does not yet own parcel boundaries, so get_refined_queue survivors do not auto-carry geometry. Returns the DCHubEnvelope with _entity=parcel_analysis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["geometry"],"properties":{"geometry":{"type":"object","description":"GeoJSON Polygon or MultiPolygon parcel boundary"},"capacity_mw":{"type":"number","description":"Optional target load in MW, passed into the handoff"}}}}}},"responses":{"200":{"description":"Parcel analysis (_entity=parcel_analysis)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/rank-sites":{"post":{"operationId":"rankSites","summary":"Deterministic multi-site ranking/optimization under constraints (Phase 3)","description":"Rank candidate sites under hard constraints + signed weighted objectives (+maximize/-minimize). Three scoring modes: relative (min-max within batch, default), absolute (fixed 0-100, cross-run-stable), percentile (vs the viable-site population \u2014 'better than X% of viable sites', cross-run + cross-region comparable). Returns the DCHubEnvelope with _entity=ranked_sites: rank, objective_score, per-field normalized{}, normalization_basis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidates","objectives"],"properties":{"candidates":{"type":"array","items":{"type":"object"},"description":"Pre-enriched candidate objects {id?, lat?, lng?, <metric fields>}; carry site_evaluation_handoff through"},"constraints":{"type":"object","description":"Hard filters {field: {min?, max?}}, fail-closed on a missing field"},"objectives":{"type":"object","description":"{field: signedWeight} \u2014 +weight maximizes, -weight minimizes"},"absolute":{"type":"boolean","description":"Fixed 0-100 scale (cross-run-stable)"},"percentile":{"type":"boolean","description":"Percentile vs the viable-site population (takes precedence over absolute)"},"top_k":{"type":"integer","default":3}}}}}},"responses":{"200":{"description":"Ranked sites (_entity=ranked_sites)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/facilities":{"get":{"operationId":"searchFacilities","summary":"Search data center facilities","description":"Search 21,000+ facilities by location, provider, or market","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search term (city, provider, market)"},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 country code"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Max results"}],"responses":{"200":{"description":"Facility search results"}},"tags":["Public"]}},"/api/v1/markets":{"get":{"operationId":"getMarkets","summary":"List all data center markets","description":"Returns all tracked markets with summary statistics","responses":{"200":{"description":"Market list"}},"tags":["Public"]}},"/api/v1/markets/compare":{"get":{"operationId":"compareMarkets","summary":"Compare data center markets","description":"Side-by-side comparison of two or more markets","parameters":[{"name":"markets","in":"query","schema":{"type":"string"},"description":"Comma-separated market names"}],"responses":{"200":{"description":"Market comparison"}},"tags":["Public"]}},"/api/v1/dcpi/scores/{market_slug}":{"get":{"operationId":"getMarketDcpi","summary":"DC Hub Power Index (DCPI) for one market","description":"Free per-market power-readiness scores: BUILD/CAUTION/AVOID verdict, composite_score, excess_power_score, constraint_score, time_to_power_months. Recomputed daily. Use for 'is <market> good to build a data center?'.","parameters":[{"name":"market_slug","in":"path","required":true,"schema":{"type":"string"},"description":"Market slug, e.g. phoenix, northern-virginia, dallas"}],"responses":{"200":{"description":"Per-market DCPI scores + verdict"}},"tags":["Public"]}},"/api/v1/ai-capacity-index":{"get":{"operationId":"getAiCapacityIndex","summary":"AI Compute Capacity Index","description":"Markets ranked by AI-ready deployable MW for near-term (30/60/90-day) large-load siting, with hyperscale_ready flag and an honest ai_ready_mw proxy.","parameters":[{"name":"horizon","in":"query","schema":{"type":"integer","enum":[30,60,90],"default":90},"description":"Deployment horizon in days"}],"responses":{"200":{"description":"Ranked AI-ready markets"}},"tags":["Public"]}},"/api/news":{"get":{"operationId":"getNews","summary":"Latest industry news","description":"Aggregated from 40+ data center industry sources","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Max results"}],"responses":{"200":{"description":"News articles"}},"tags":["Public"]}},"/api/v1/transactions":{"get":{"operationId":"getTransactions","summary":"M&A transactions and deals","description":"Recent acquisitions, investments, and joint ventures","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"deal_type","in":"query","schema":{"type":"string","enum":["acquisition","investment","joint_venture","lease","development"]}}],"responses":{"200":{"description":"Transaction list"}},"tags":["Public"]}},"/api/v1/pipeline":{"get":{"operationId":"getPipeline","summary":"Construction pipeline","description":"Data centers under construction or announced","responses":{"200":{"description":"Pipeline data"}},"tags":["Public"]}},"/api/site-score":{"get":{"operationId":"getSiteScore","summary":"Site suitability score","description":"Score (0-100) for data center development at a location","parameters":[{"name":"lat","in":"query","schema":{"type":"number"},"required":true},{"name":"lon","in":"query","schema":{"type":"number"},"required":true},{"name":"state","in":"query","schema":{"type":"string"},"description":"US state abbreviation"}],"responses":{"200":{"description":"Site score"}},"tags":["Public"]}},"/api/grid/fuel-mix":{"get":{"operationId":"getGridFuelMix","summary":"Real-time power grid fuel mix","parameters":[{"name":"iso","in":"query","schema":{"type":"string","enum":["ERCOT","PJM","CAISO","MISO","SPP","NYISO","ISONE"]}}],"responses":{"200":{"description":"Grid fuel mix data"}},"tags":["Public"]}},"/api/energy/prices/{state}":{"get":{"operationId":"getEnergyPrices","summary":"Electricity pricing by US state","parameters":[{"name":"state","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Energy pricing"}},"tags":["Public"]}},"/api/v1/facilities/detail/{facility_id}":{"get":{"operationId":"getFacilityDetail","summary":"Full facility record","description":"Detailed info including contacts, capacity, certifications. Requires API key.","parameters":[{"name":"facility_id","in":"path","schema":{"type":"integer"},"required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Facility detail"},"401":{"description":"API key required"}},"tags":["Pro"]}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key from https://dchub.cloud/pricing"}},"schemas":{"DCHubEnvelope":{"type":"object","description":"Universal response envelope for every DC Hub tool and endpoint. The STABLE anchor an agent branches on before parsing the entity payload: full-data, gated-preview and error responses all share it. `_entity` is the type discriminator; the entity-specific payload is passthrough (additionalProperties). Branch on `_entity` + `ok`.","required":["_entity"],"additionalProperties":true,"properties":{"_entity":{"type":"string","description":"Payload type discriminator \u2014 branch on this before parsing.","enum":["facility","market","grid","fiber","gas","deal","site","news","energy","incentives","risk","index","pipeline","infrastructure","export","changes","alert","meta","semantic_search","error","record"]},"ok":{"type":"boolean","description":"Success flag; false + _entity='error' on failure."},"_source":{"type":"string","example":"DC Hub \u2014 dchub.cloud"},"_cite":{"type":"string","description":"Attribution string (CC-BY-4.0)."},"citation":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"cite_as":{"type":"string"}}},"next_session":{"type":"object","description":"Context-aware next-step hints \u2014 the agent's state-machine menu for what to call next."}}}}},"tags":[{"name":"Public","description":"Free endpoints \u2014 no auth required"},{"name":"Pro","description":"Requires API key ($49/mo)"}]}