---
title: "Comparison Detail"
method: GET
path: "/api/v1/comparisons/{pair_key}"
tags: ["comparisons"]
---

# Comparison Detail

`GET /api/v1/comparisons/{pair_key}`

## Request

- Base URL: `https://statsmapped.com`
- URL: `https://statsmapped.com/api/v1/comparisons/{pair_key}`
- Auth: none declared

The curated cross-dataset "Compared with" section (correlation-feature-proposal.md).

Deliberately no `?search=` or arbitrary-pair form -- `pair_key` is one of a small,
hand-registered set (`databeat/comparisons.py`'s `PAIR_KEY`), enumerable and
finite by design (proposal §3.3): if this endpoint cannot answer "compare arbitrary
series A to arbitrary series B", nobody can build a discovery UI on top of it later
without a deliberate decision to add one.

r, rho and the leave-one-out range are computed here, not in the browser, so any
future consumer (an alert email, a newsletter) gets the number and its qualification
together rather than reconstructing them.

404 for an unknown key OR a known one with too little data to say anything: the
status is the same on purpose, matching `renderCompanion()`'s existing "a bonus, never
a blocker" rule (the frontend and the MCP client both branch on `!ok` and degrade either
case to nothing shown). The two are told apart by the error envelope's `code` only
(#589 S2 / #1120, EA-approved distinction, built non-breaking): "unknown_pair" for a key
that is not a registered comparison, "insufficient_data" for a registered pair with too
little data right now, so an agent can tell "never will exist" from "check back later".

## Path parameters

- `pair_key` string, required

## Response `200`

Successful Response

- ComparisonResponse
  - `country` string
  - `permalink` string, nullable
  - `points` ComparisonPoint[], required
    - `country` string
    - `area_id` string, required
    - `area_name` string, required
    - `x` number, required
    - `y` number, required
  - `x` ComparisonAxis, required
    - `country` string
    - `label` string, required
    - `unit` string, nullable
    - `series_key` string, nullable
    - `period` string, nullable
    - `periodicity` string, nullable
    - `publisher` string, nullable
    - `readable_slug` string, nullable
    - `licence_class` string, nullable
    - `licence_restrictions` string[]
    - `attribution` string, nullable
  - `y` ComparisonAxis, required
    - `country` string
    - `label` string, required
    - `unit` string, nullable
    - `series_key` string, nullable
    - `period` string, nullable
    - `periodicity` string, nullable
    - `publisher` string, nullable
    - `readable_slug` string, nullable
    - `licence_class` string, nullable
    - `licence_restrictions` string[]
    - `attribution` string, nullable
  - `stats` ComparisonStats, required
    - `country` string
    - `n` integer, required
    - `r` number, required
    - `rho` number, required
    - `loo_min` number, required
    - `loo_max` number, required
    - `most_influential_area` string, required
  - `caveats` Caveat[]
    - `country` string
    - `kind` string, required
    - `severity` string, required
    - `label` string, required
    - `body` string, required
    - `source_url` string, nullable
    - `origin` string, required
    - `interpretive` boolean
    - `stats` CaveatStats
      - `country` string
      - `median` number, required
      - `n` integer, required
      - `modified_z` number, required
      - `peer_basis` string, required
  - `province_groups` ProvinceGroup[], nullable
    - `country` string
    - `province_id` string, required
    - `province_name` string, required
    - `points` ComparisonPoint[], required
      - `country` string
      - `area_id` string, required
      - `area_name` string, required
      - `x` number, required
      - `y` number, required

## Other responses

- `400`: Bad request
- `401`: Missing or invalid credentials
- `403`: Not authorized for this request
- `404`: Not found
- `422`: Validation error
- `429`: Rate limited

---

[API](https://skmtc.dev/statsmapped/apis/statsmapped-api.md) · [All operations](https://skmtc.dev/statsmapped/apis/statsmapped-api/llms.txt) · [OpenAPI document](https://skmtc.dev/statsmapped/apis/statsmapped-api/revisions/7c5b264d05b7?raw)