# sunglassesguides documentation

> Read-only, source-cited sunglasses variant, size and lens facts for the US market (USD, millimetres), for AI agents and shopping assistants. Same data over HTML, Markdown, REST and MCP.

- Service: https://sunglassesguides.com/
- OpenAPI 3.0: https://sunglassesguides.com/openapi.json
- MCP (Streamable HTTP): https://sunglassesguides.com/mcp
- Coverage (live counts): https://sunglassesguides.com/api/v1/coverage
- llms.txt: https://sunglassesguides.com/llms.txt
- ARD manifest (experimental): https://sunglassesguides.com/.well-known/ard.json
- Current data_version: c1.o0; published variants: 81; data_mode: production

## Choose a tool

| Task | Tool | REST |
|---|---|---|
| Only a size like 52-18-140; want alternatives | find_sunglasses | POST /api/v1/search |
| Know brand/model/code; need the exact variant | resolve_sunglasses | POST /api/v1/resolve |
| Compare 2-4 known variants | compare_sunglasses | POST /api/v1/compare |
| All facts and evidence for one variant | get_sunglasses_variant | GET /api/v1/variants/{id} |
| Purchase options for one variant | get_sunglasses_offers | GET /api/v1/variants/{id}/offers |
| What is covered | get_sunglasses_coverage | GET /api/v1/coverage |

## Pages

- [get_sunglasses_coverage (GET /api/v1/coverage)](https://sunglassesguides.com/docs/get_sunglasses_coverage.md): Describe what this service covers right now: brands, models, published variants, field completeness, offer coverage, freshness and which demo tasks have verified answers.
- [resolve_sunglasses (POST /api/v1/resolve)](https://sunglassesguides.com/docs/resolve_sunglasses.md): Turn what a user knows (brand, model name, code on the temple, size marking, lens) into exact catalog variants, or say precisely which detail is missing.
- [find_sunglasses (POST /api/v1/search)](https://sunglassesguides.com/docs/find_sunglasses.md): Filter the covered catalog by a reference size with per-dimension tolerances and hard conditions (polarized, maker-labeled bridge fit, brand, optional offer conditions). Every condition is evaluated per candidate as pass/fail/unknown/conflict/stale with evidence.
- [compare_sunglasses (POST /api/v1/compare)](https://sunglassesguides.com/docs/compare_sunglasses.md): 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.
- [get_sunglasses_variant (GET /api/v1/variants/{variant_id})](https://sunglassesguides.com/docs/get_sunglasses_variant.md): Full record of one exact variant: every field with value, field_status, evidence excerpts, sources, check times and unknowns.
- [get_sunglasses_offers (GET /api/v1/variants/{variant_id}/offers)](https://sunglassesguides.com/docs/get_sunglasses_offers.md): Return covered US offers for one exact variant with item price, shipping, tax, landed-total status, availability and observation time, each kept separate.
- [MCP connection](https://sunglassesguides.com/docs/mcp.md): Remote MCP endpoint, protocol versions, transport, tools, authentication.
- [REST conventions](https://sunglassesguides.com/docs/rest.md): Envelope, status codes, pagination, data_version consistency, headers.
- [Data dictionary](https://sunglassesguides.com/docs/data-dictionary.md): Every field, unit, field_status value and entity.
- [Sources and methodology](https://sunglassesguides.com/docs/sources-and-methodology.md): Where facts come from, how they are verified and published.
- [Freshness, time fields and caching](https://sunglassesguides.com/docs/freshness.md): generated_at, retrieved_at, checked_at, observed_at, max_age policy, cache semantics.
- [Authentication and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md): Anonymous trial, API keys, rate-limit headers, 429 handling.
- [Errors](https://sunglassesguides.com/docs/errors.md): Error codes, HTTP status, retryable flag, recovery steps.
- [Scope and limitations](https://sunglassesguides.com/docs/limits.md): What the service does not do; coverage limits; Action and A2A status.