spb/datacenterindex

1/** Nearby, explore, AI index, power, connectivity, time machine. */2import type { FastifyInstance } from "fastify";3import { z } from "zod";4import { publicGet } from "../../lib/route.js";5import { TTL, badRequest } from "../../lib/http.js";6import { boolParam, csvParam, intParam, numParam, orderParam, pageParam, strParam } from "../../lib/params.js";7import { METHODOLOGY_CONTAINMENT } from "../../lib/sql.js";8import { nearby, parseNearbyTypes, NEARBY_MAX_RADIUS_KM, NEARBY_TYPES } from "../../lib/nearby.js";9import { explore, EXPLORE_METHODOLOGY } from "../../repositories/explore.js";10import { aiIndex, AI_EVIDENCE_NOTE } from "../../repositories/ai.js";11import { powerOverview, POWER_NOTE } from "../../repositories/power.js";12import { connectivityOverview, CONNECTIVITY_NOTE } from "../../repositories/connectivity.js";13import { timeMachine, TIME_MACHINE_NOTE } from "../../repositories/time-machine.js";1415const empty = (v: unknown) => (v === "" || v === null ? undefined : v);1617const nearbyQuery = z.object({ lat: numParam.describe("latitude (-90..90)"), lng: numParam.describe("longitude (-180..180)"), radius_km: numParam.describe(`radius in km (default 25, max ${NEARBY_MAX_RADIUS_KM})`), types: csvParam.describe(`comma list of ${NEARBY_TYPES.join("|")} (default all)`) });1819export const exploreQuery = z.object({20  entity: z.preprocess(empty, z.enum(["facilities", "projects"]).optional()),21  status: csvParam,22  project_status: csvParam,23  country: csvParam,24  metro: strParam,25  operator: strParam,26  type: csvParam,27  min_mw: numParam,28  max_mw: numParam,29  ai: z.preprocess(empty, z.enum(["confirmed", "likely", "associated", "any"]).optional()),30  hyperscale: boolParam,31  expected_before: intParam,32  expected_after: intParam,33  opened_from: intParam,34  opened_to: intParam,35  announced_since: strParam,36  confidence: csvParam,37  location_precision: csvParam,38  has_mw: boolParam,39  project_class: csvParam,40  q: strParam,41  sort: z.preprocess(empty, z.enum(["name", "mw", "updated", "opened", "completeness", "announced", "opening"]).optional()),42  order: orderParam,43  page: pageParam,44  per_page: intParam,45  view: z.preprocess(empty, z.enum(["table", "map", "charts"]).optional()),46}).strict();4748export async function intelligenceRoutes(app: FastifyInstance): Promise<void> {49  publicGet(app, { url: "/nearby", ttl: TTL.detail, query: nearbyQuery, tags: ["nearby"], summary: "Infrastructure around a point (NearbyInfrastructure): facilities, live projects, IXPs, cloud regions, metros within radius_km", description: "Great-circle distances on a bbox pre-filter. Layers without a connector (landing stations, substations, power plants) are empty with a note.", response: { type: "NearbyInfrastructure", example: { center: { lat: 39.04, lng: -77.49 }, radiusKm: 25, facilities: [], projects: [], ixps: [], cloudRegions: [], metros: [], landingStations: [], substations: [], powerPlants: [], note: "…" } } }, async (q) => {50    if (q.lat == null || q.lng == null || Math.abs(q.lat) > 90 || Math.abs(q.lng) > 180) throw badRequest("lat and lng are required (lat -90..90, lng -180..180)");51    if (q.radius_km != null && (q.radius_km <= 0 || q.radius_km > NEARBY_MAX_RADIUS_KM)) throw badRequest(`radius_km must be between 0 and ${NEARBY_MAX_RADIUS_KM}`);52    const data = await nearby({ lat: q.lat, lng: q.lng, radiusKm: q.radius_km, types: parseNearbyTypes(q.types) });53    return { data, meta: { total: data.facilities.length + data.projects.length + data.ixps.length + data.cloudRegions.length + data.metros.length, methodology: data.note } };54  });5556  publicGet(app, { url: "/explore", ttl: TTL.list, query: exploreQuery, tags: ["explore"], summary: "Structured explorer (ExploreResponse): facilities or projects with facets, charts and map points; unknown query keys are rejected (400)", response: { type: "ExploreResponse", example: { query: { entity: "facilities", country: "US" }, total: 0, items: [], facets: { status: [], country: [], operator: [], type: [], ai: [] }, charts: { byStatus: [], byCountry: [], byYear: [] }, map: { points: [], total: 0, degraded: false }, mwCoverage: 0 } } }, async (q) => {57    const data = await explore(q);58    return { data, meta: { total: data.total, page: q.page, perPage: q.per_page ?? 24, mwCoverage: data.mwCoverage, methodology: `${EXPLORE_METHODOLOGY} ${METHODOLOGY_CONTAINMENT}` } };59  });6061  publicGet(app, { url: "/ai-infrastructure", ttl: TTL.detail, tags: ["ai"], summary: "AI / HPC infrastructure index (AiIndex): confirmed + likely facilities and live projects, top operators / metros / countries, pipeline by stage", response: { type: "AiIndex", example: { stats: { facilities: 0, confirmed: 0, likely: 0, associated: 0, projects: 0, plannedMw: null, constructionMw: null, countries: 0, operators: 0, mwCoverage: 0 }, topOperators: [], topMetros: [], topCountries: [], pipelineByStage: [], recentAnnouncements: [], recentProjects: [], facilities: [], evidenceNote: "…" } } }, async () => {62    const data = await aiIndex();63    return { data, meta: { total: data.stats.facilities, mwCoverage: data.stats.mwCoverage, methodology: AI_EVIDENCE_NOTE } };64  });6566  publicGet(app, { url: "/power", ttl: TTL.detail, tags: ["power"], summary: "Power overview (PowerOverview): grid constraints, power / grid events, large loads (utility, grid, planned ≥ 200 MW), national energy context, utilities", response: { type: "PowerOverview", example: { gridConstraints: [], powerEvents: [], largeLoads: [], countryEnergy: [], utilities: [], note: "…" } } }, async () => {67    const data = await powerOverview();68    return { data, meta: { total: data.largeLoads.length, methodology: POWER_NOTE } };69  });7071  publicGet(app, { url: "/connectivity", ttl: TTL.detail, tags: ["connectivity"], summary: "Connectivity overview (ConnectivityOverview): IXPs, cloud regions, carrier hotels, per-metro interconnection density", response: { type: "ConnectivityOverview", example: { ixps: [], cloudRegions: [], carrierHotels: [], landingStations: [], byMetro: [], note: "…" } } }, async () => {72    const data = await connectivityOverview();73    return { data, meta: { total: data.ixps.length, methodology: CONNECTIVITY_NOTE } };74  });7576  publicGet(app, { url: "/time-machine", ttl: TTL.detail, tags: ["time-machine"], summary: "Yearly frames of the index from published opening dates (TimeMachine) with earliestReliableYear and openingDateCoverage", response: { type: "TimeMachine", example: { frames: [{ year: 2020, facilities: 120, knownMw: 950.5, announced: 12, construction: 4, opened: 9 }], earliestReliableYear: 2005, openingDateCoverage: 0.12, note: "…" } } }, async () => {77    const data = await timeMachine();78    return { data, meta: { total: data.frames.length, openingDateCoverage: data.openingDateCoverage, methodology: TIME_MACHINE_NOTE } };79  });80}81