# compare_sunglasses

Side-by-side comparison of 2-4 variants: every field with its status and sources, which fields differ, conflicts, and size differences against a reference.

- REST: `POST https://sunglassesguides.com/api/v1/compare` (OpenAPI operationId `compare_sunglasses`)
- MCP: tool `compare_sunglasses` on `https://sunglassesguides.com/mcp`
- Read-only: yes. It never changes anything outside this service.
- Market / units: US, USD, millimetres. Schema version 1.0.
- Support: implemented=true, data_covered=partial, externally_verified=false. Many fields are unknown for some brands; unknowns are reported, never filled from siblings.

## When to use

- The user wants to see how 2-4 specific frames differ (fit label, lens, sizes).

## When not to use

- To search (use find_sunglasses).
- More than 4 variants (not supported).

## Input

JSON body:

| Name | Type | Required | Range | Meaning |
|---|---|---|---|---|
| `variant_ids` | array | yes | 2-4 items | 2 to 4 distinct variant_ids. |
| `reference` | object | no |  | Optional reference size; per-dimension differences are returned for each variant. Fields: `lens_width_mm` (integer 30-80), `bridge_width_mm` (integer 8-30), `temple_length_mm` (integer 100-170). |
| `reference_text` | string | no | max 40 chars |  |
| `expected_data_version` | string | no |  | data_version returned by an earlier call. If the catalog changed since, the call fails with DATA_VERSION_CHANGED instead of mixing old and new facts. |


## Output

The standard envelope (see [REST conventions](https://sunglassesguides.com/docs/rest.md)): `request_id`, `success`, `schema_version`, `data_version`, `data_mode`, `generated_at`, `request`, `result`, `sources`, `freshness`, `cache`, `next_actions`, and `error` on failure.

status COMPARED with fields[], differing_fields, size_differences (vs reference and vs the first variant).

`result.status` values: `COMPARED`. `success:true` means the request was processed; it does not mean something matched.

## Sources and time

Each field carries `field_status`, `source_ids` and evidence excerpts; `sources[]` lists each cited source once with `retrieved_at`. `checked_at` is per record. See [freshness](https://sunglassesguides.com/docs/freshness.md).

## Permissions

Anonymous read-only trial without a key; optional API key for higher quotas. See [auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md).

## Examples

### Success example (ids taken from a live find result)

```sh
# 1) get real ids
curl -sS -X POST https://sunglassesguides.com/api/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"reference_text":"52-18-140","require":{"polarized":true},"limit":2}'
# 2) compare them
curl -sS -X POST https://sunglassesguides.com/api/v1/compare \
  -H 'Content-Type: application/json' \
  -d '{"variant_ids":["mauijim-668-02","mauijim-h668-10"],"reference_text":"52-18-140"}'
```

```json
{
  "status": "COMPARED",
  "message": "Compared 2 variants on 16 fields. 0 field(s) have conflicting sources; 8 field(s) are unknown for at least one variant.",
  "differing_fields": [
    "frame_color",
    "lens_color"
  ],
  "size_differences": [
    {
      "variant_id": "mauijim-668-02",
      "vs_reference": [
        {
          "dimension": "lens_width_mm",
          "candidate_mm": 52,
          "reference_mm": 52,
          "diff_mm": 0
        },
        {
          "dimension": "bridge_width_mm",
          "candidate_mm": 19,
          "reference_mm": 18,
          "diff_mm": 1
        },
        {
          "dimension": "temple_length_mm",
          "candidate_mm": 145,
          "reference_mm": 140,
          "diff_mm": 5
        }
      ],
      "vs_first": [
        {
          "dimension": "lens_width_mm",
          "diff_mm": 0
        },
        {
          "dimension": "bridge_width_mm",
          "diff_mm": 0
        },
        {
          "dimension": "temple_length_mm",
          "diff_mm": 0
        }
      ]
    },
    {
      "variant_id": "mauijim-h668-10",
      "vs_reference": [
        {
          "dimension": "lens_width_mm",
          "candidate_mm": 52,
          "reference_mm": 52,
          "diff_mm": 0
        },
        {
          "dimension": "bridge_width_mm",
          "candidate_mm": 19,
          "reference_mm": 18,
          "diff_mm": 1
        },
        {
          "dimension": "temple_length_mm",
          "candidate_mm": 145,
          "reference_mm": 140,
          "diff_mm": 5
        }
      ],
      "vs_first": [
        {
          "dimension": "lens_width_mm",
          "diff_mm": 0
        },
        {
          "dimension": "bridge_width_mm",
          "diff_mm": 0
        },
        {
          "dimension": "temple_length_mm",
          "diff_mm": 0
        }
      ]
    }
  ]
}
```

### Failure example

An unknown id returns HTTP 404 `NOT_FOUND` with `result.missing_variant_ids`... (`error.details.missing_variant_ids`).

## Related tools

- [find_sunglasses](https://sunglassesguides.com/docs/find_sunglasses.md)
- [get_sunglasses_variant](https://sunglassesguides.com/docs/get_sunglasses_variant.md)