# sunglassesguides

> Read-only, source-cited sunglasses variant, size and lens facts for the US market (USD, millimetres), built for AI agents and shopping assistants. Ray-Ban, Oakley, Maui Jim: 40 models, 81 published variants (data_version c1.o0, production). No merchant offers are covered yet.

Use it to find frames by size (e.g. a temple marking like 52-18-140 (frames print a small square between the first two numbers; both forms are accepted)) with hard conditions such as maker-stated polarized or maker-labeled low bridge fit, to identify an exact variant from a model name or code, and to compare 2-4 variants field by field. Every field carries field_status, source links and check times; unknown values are null, never guessed. It does not give fit guarantees, prices, prescriptions or checkout. Anonymous read-only trial with a small quota; no login.

## Tools and APIs

- [MCP server (Streamable HTTP)](https://sunglassesguides.com/mcp): tools get_sunglasses_coverage, resolve_sunglasses, find_sunglasses, compare_sunglasses, get_sunglasses_variant, get_sunglasses_offers; see [MCP docs](https://sunglassesguides.com/docs/mcp.md)
- [OpenAPI 3.0](https://sunglassesguides.com/openapi.json): REST under https://sunglassesguides.com/api/v1
- [Documentation index (Markdown)](https://sunglassesguides.com/docs/index.md)
- [get_sunglasses_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](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](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](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](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](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.

## Data, sources and freshness

- [Live coverage](https://sunglassesguides.com/api/v1/coverage): counts, field coverage, task coverage matrix
- [Data dictionary](https://sunglassesguides.com/docs/data-dictionary.md)
- [Sources and methodology](https://sunglassesguides.com/docs/sources-and-methodology.md)
- [Freshness, time fields and caching](https://sunglassesguides.com/docs/freshness.md)
- [Auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md) and [errors](https://sunglassesguides.com/docs/errors.md)
- [Data quality and corrections](https://sunglassesguides.com/data-quality)

## Guides

- [How to Read Temple Size Markings](https://sunglassesguides.com/guides/how-to-read-temple-size-markings.md): What the three numbers in a marking such as 52-18-140 mean, where they usually appear, and why a size alone cannot identify a model.
- [Comparing Frame Sizes Dimension by Dimension](https://sunglassesguides.com/guides/comparing-frame-sizes.md): How to compare lens, bridge, temple and frame width in mm, why frame width is not 2 × lens + bridge, and what the numbers leave out.
- [Polarized Lenses in the Data](https://sunglassesguides.com/guides/polarized-lenses-in-the-data.md): What the polarized field means in this catalog, why unknown is not false, and why polarization and UV statements are kept apart.
- [Maker Bridge Fit Labels Explained](https://sunglassesguides.com/guides/bridge-fit-labels.md): How Ray-Ban, Oakley and Maui Jim fit labels map to this catalog's bridge_fit values, using only each maker's own published definitions.
- [Lens Specifications in the Catalog](https://sunglassesguides.com/guides/lens-specifications.md): How this catalog records light transmission, lens category, lens material and UV statements as cited maker claims rather than test results.
- [Data Scope, Sources and Freshness](https://sunglassesguides.com/guides/data-scope-and-sources.md): What this sunglasses catalog covers, what each field_status means, which sources it cites, and how check times and freshness work.

## Optional

- [Scope and limitations](https://sunglassesguides.com/docs/limits.md)
- [Human catalog](https://sunglassesguides.com/sunglasses)
- [ARD manifest (experimental)](https://sunglassesguides.com/.well-known/ard.json)