---
title: "Deterministic multi-site ranking/optimization under constraints (Phase 3)"
method: POST
path: "/api/v1/rank-sites"
tags: ["Public"]
---

# Deterministic multi-site ranking/optimization under constraints (Phase 3)

`POST /api/v1/rank-sites`

## Request

- Base URL: `https://dchub.cloud`
- URL: `https://dchub.cloud/api/v1/rank-sites`
- Auth: none declared

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 — '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.

## Request body

- object
  - `candidates` object[], required: Pre-enriched candidate objects {id?, lat?, lng?, <metric fields>}; carry site_evaluation_handoff through
  - `constraints` object: Hard filters {field: {min?, max?}}, fail-closed on a missing field
  - `objectives` object, required: {field: signedWeight} — +weight maximizes, -weight minimizes
  - `absolute` boolean: Fixed 0-100 scale (cross-run-stable)
  - `percentile` boolean: Percentile vs the viable-site population (takes precedence over absolute)
  - `top_k` integer

## Response `200`

Ranked sites (_entity=ranked_sites)

- DCHubEnvelope: 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`.
  - `_entity` 'facility' | 'market' | 'grid' | 'fiber' | 'gas' | 'deal' | 'site' | 'news' | 'energy' | 'incentives' | 'risk' | 'index' | 'pipeline' | 'infrastructure' | 'export' | 'changes' | 'alert' | 'meta' | 'semantic_search' | 'error' | 'record', required: Payload type discriminator — branch on this before parsing.
  - `ok` boolean: Success flag; false + _entity='error' on failure.
  - `_source` string
  - `_cite` string: Attribution string (CC-BY-4.0).
  - `citation` object
    - `source` string
    - `url` string
    - `license` string
    - `cite_as` string
  - `next_session` object: Context-aware next-step hints — the agent's state-machine menu for what to call next.

---

[API](https://skmtc.dev/dchub/apis/dc-hub-data-center-intelligence-api.md) · [All operations](https://skmtc.dev/dchub/apis/dc-hub-data-center-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dchub/apis/dc-hub-data-center-intelligence-api/revisions/15f74d15cdeb?raw)