# GolfDataAPI

Golf equipment data for AI agents, recorded every day: canonical
product catalog with source-backed specs, stored advertised multi-retailer prices,
and daily price history snapshots, unbroken and not backfillable.

Catalog: 10021 canonical products across 31 categories, of which 2459 carry at least one source-backed field (958 fully enriched). Price history: 380486 snapshots, latest 2026-09-18T09:45:00+00:00. Live figures: /v1/meta.

Coverage is published honestly: enrichment_status on every product tells you
whether its specs are sourced. Do not treat an unenriched row as verified.

Base URL: https://golfdata.co

## MCP

POST https://golfdata.co/mcp speaks MCP over streamable HTTP. Tools: search_products,
get_product, get_current_prices, get_price_history, compare_prices, get_verified_offer, get_verified_offers. Same
x-api-key as REST, sent as a header. initialize and tools/list are free;
search_products and get_product work keyless under the same per-IP limit;
the other tools are metered.

## Endpoints (GET, JSON)

- /v1/meta
  Free. Catalog stats: product counts by category, enrichment coverage,
  snapshot count, data freshness.
- /v1/pricing
  Free. The price ladder below as JSON, plus lookup costs and machine URLs.
- /v1/limits
  Free. Your lane and remaining quota with a key, else the keyless limits.
- /openapi.json
  Free. OpenAPI 3.1 for every route here.
- POST /v1/keys
  Free. Body {"email": "..."}. Returns a free key once. See Pricing and payment.
- /v1/keys/claim?session_id={cs_...}
  Free. Claims the paid key for a completed Stripe Checkout Session, once.
  201 with the key, 200 claimed with key null after that, 402 while unpaid.
- POST /v1/alerts
  Free. Body {"email": "...", "product_id": "uuid"}. Stores a price alert once
  per email and product. Returns 201 subscribed or 200 exists.
- POST /v1/contact
  Free. Body {"company": "...", "email": "...", "feed_url": "...", "message": "...", "reason": "..."}.
  Stores one audience contact request. Returns 201 received.
- /v1/products?brand=&category=&q=&limit=
  Keyless. Search canonical products. Returns enriched fields (model, release_year,
  msrp, specs jsonb) and enrichment_status. Costs 0 lookups.
- /v1/products/{id}
  Keyless. One product plus its enrichment_sources provenance rows: every enriched
  field carries the source URL, confidence, and checked_at it came from. Costs 1 lookup.
- /v1/prices/current?product_id={id}
  Latest stored advertised prices, stock observations and stored links. Not exact-variant verified offers.
- /v1/offers/discover?canonical_product_id={uuid}&variant_id={uuid|null}&offset=0
  Resolve eligible source IDs and verify offers through Chip's same gate. Optional
  variant_id returns selection options first when needed, not guessed variants.
  Two sources per page, bounded 16-source live window; next_offset continues within
  that window. No exhaustive coverage or stable snapshot claim.
- /v1/offers/verified?source_kind={deal|product}&source_id={source_uuid}&canonical_product_id={uuid}&variant_id={uuid|null}
  Opt-in verified offer contract golf-offer.v1 through Chip's commerce gate.
  Requires a known marketplace deal/product source UUID; canonical search does not
  discover source IDs. Explicit null only for sources without selectable variants.
  Unavailable or stale evidence never becomes a verified current price. No member
  authority or purchase attribution is created by this read. May return 503 while disabled.
- /v1/prices/history?product_id={id}&days=30
  Daily price snapshots per retailer (days up to 365). Costs 2 lookups.
- /v1/compare?product_id={id}
  Cross-retailer comparison: current prices plus min/max/median and
  30/90-day lows from history. Costs 2 lookups.

## Pricing and payment

One unit price: $0.005 USD per lookup, metered per key, same number in
every x-price-usd header and at https://golfdata.co/v1/pricing. Lookup costs: search 0,
product 1, current prices 1, history 2, compare 2, verified offers 2.
Overage $0.005 per lookup with a per-key spend cap.

- keyless: $0, search and product only, 10 per minute. No key. Search and single product lookup only.
- free: $0, 1000 lookups, 10 per minute. 1,000 lookups per month, renews. Key from POST /v1/keys. Attribution required for commercial use.
- pack: $20, 4000 lookups, 60 per minute. Prepaid, never expires.
- builder: $49, 10000 lookups, 60 per minute. Per month, self-serve.
- pro: $149, 50000 lookups, 300 per minute. Per month. Bulk history, CSV export, Parquet drops.
- enterprise: custom, custom lookups, custom per minute. Custom. MAP monitoring, feeds, SLA.

Keyless lane needs no signup: /v1/products and /v1/products/{id}, 10 per
minute per IP. Every other /v1 route and MCP tool needs an x-api-key header.
Free key: POST https://golfdata.co/v1/keys with {"email": "you@example.com"} (JSON or
form-encoded). Issued instantly, shown once, one per email, 1000 lookups per month.
Pay: https://buy.stripe.com/14A3cvfQ93hmeQvgfceQM03
A 402 (no key) or 429 (rate limit or quota) body is JSON with error, message,
pricing_url, free_key_url, docs_url, checkout_url when available, and
retry_after_seconds on 429.

## Price Index (golfdata.co)

Monthly Golf Equipment Price Index by category from the same data: matched
products, base June 2026 = 100. Editions with data.csv and data.json:
https://golfdata.co/price-index/ . History per category:
https://golfdata.co/categories/ . Method: https://golfdata.co/methodology/ .
Free to cite with a link.

## Consumer pages (golfdata.co)

Free worker rendered pages built from observed prices:
- https://golfdata.co/drops/ and https://golfdata.co/drops/{category}/
  The biggest current direct price drops, grouped by category.
- https://golfdata.co/partners/
  Partner kit: free key terms, price badge embed, and Price Index citation rules.
- https://golfdata.co/brands/ and https://golfdata.co/brands/{brand}/
  Observed prices for major golf brands, grouped by category.
- https://golfdata.co/retailers/ and https://golfdata.co/retailers/{retailer}/
  Retailers with fresh priced products and the products they price lowest.
- https://golfdata.co/badge/{productId}.svg
  Embeddable live price badge for one product.

## Notes

- Read-only. GET and OPTIONS, plus POST /mcp, POST /v1/keys, POST /v1/alerts, and POST /v1/contact. CORS: all origins.
- Product ids are UUIDs from /v1/products.
- Every response includes an x-price-usd header.
- Machine docs: https://golfdata.co/v1/pricing and https://golfdata.co/openapi.json