Sunglasses Specifications and Comparison API
Structured sunglasses variant, size and lens facts, each with its source and check time, for filtering and comparison in the US market. Built first for AI assistants and agents; people can use the catalog too.
Machine entry points
- Documentation index (Markdown) and developer guide
- OpenAPI 3.0 description of the REST API under
https://sunglassesguides.com/api/v1 - MCP endpoint
https://sunglassesguides.com/mcp: Streamable HTTP, JSON-RPC over POST (a browser visit is not a connectivity test; see MCP docs) - llms.txt, ARD manifest (experimental), live coverage JSON
- Market
- US only; prices in USD (none covered yet); sizes in millimetres; en-US
- Access
- Read-only. Anonymous trial without login (30 requests/minute); optional API keys
- Data version
c1.o0(production), published 2026-09-25T08:39:44Z
What is covered right now
81 published variants across 40 models from Ray-Ban (30), Oakley (26), Maui Jim (25). Counts are computed from published records. Target: 80 variants. Offers: not covered (no approved price source connected). Specs are checked manually (target monthly); each record shows its own check time.
| Field | Known | Unknown | Conflicting |
|---|---|---|---|
| lens_width_mm | 78 (96%) | 3 | 0 |
| bridge_width_mm | 78 (96%) | 3 | 0 |
| temple_length_mm | 48 (59%) | 33 | 0 |
| manufacturer_fit_label | 39 (48%) | 42 | 0 |
| polarized | 44 (54%) | 37 | 0 |
| vlt_percent | 19 (23%) | 62 | 0 |
| lens_material | 29 (36%) | 52 | 0 |
Tools
| Tool (MCP) / operationId | REST | Use it to |
|---|---|---|
get_sunglasses_coverage | GET /api/v1/coverage | 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 | 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 | 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 | 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} | 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 | Return covered US offers for one exact variant with item price, shipping, tax, landed-total status, availability and observation time, each kept separate. |
Good for
- Finding frames near an existing size such as 52-18-140 (the numbers printed inside the temple arm), with per-dimension differences
- Requiring maker-stated polarized lenses or a maker-labeled low bridge fit, with evidence
- Identifying an exact variant when a model name has several sizes or lenses
- Comparing 2-4 variants field by field, with unknowns and conflicts shown
Not for
- Fit guarantees, face measurement, virtual try-on or prescriptions
- Prices, stock or lowest-price claims (no offer source yet)
- Purchases or any other action (read-only; Action layer not supported)
- Brands or models outside the catalog; "no match" is not a market-wide claim
Try it
Demo tasks and whether they have verified answers
| Task | Tool | Current result | Ready |
|---|---|---|---|
| Polarized alternatives for an existing 52-18-140 frame | find_sunglasses | MATCHES_FOUND (3) | yes |
| Identify an ambiguous model name | resolve_sunglasses | NEEDS_VARIANT (5) | yes |
| Compare standard and maker-labeled low bridge versions | compare_sunglasses | COMPARED (2) | yes |
| Maker-labeled low bridge fit AND polarized near 52-18-140 | find_sunglasses | MATCHES_FOUND (3) | yes |
| Composite demo plus a 150 USD item-price budget | find_sunglasses | NO_OFFER_COVERAGE (0) | no: lens_width_mm unknown for 3/81 published variants |
Computed live from the published catalog. The budget task stays not ready until a price source is connected.
Sources and freshness
Facts come from maker pages (Ray-Ban, Oakley, Maui Jim US sites), extracted automatically and recorded only when two independent extractions agree. Nothing is measured by this site. Unknown values stay unknown. See data quality and methodology. Human catalog: browse all variants.