# GolfDataAPI

Golf equipment data for AI agents, with dated observations: canonical
product catalog with source-backed specs, stored advertised multi-retailer prices,
and dated price history observations. History coverage varies by product and retailer and may contain gaps.

Catalog: 21228 canonical products across 31 categories, of which 2459 carry at least one source-backed field (958 fully enriched). Price history: 312796 snapshots, latest 2026-11-14T09:15:53.582976+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://www.golfdata.co

## MCP

POST https://www.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
  or operationally paused; product discovery remains available.

## Commerce agent contract

Search yields canonical product IDs; offer discovery resolves source IDs and exact
variant selection. Selection metadata is not an offer. verified_offer means evidence
passed the current commerce gate, not a checkout guarantee or purchase authority.
Read price.observed_at, verification.valid_until, unknown_fields and actionability
when present. Absence of actionability never means purchase-ready. Currency is
currently null; never infer USD from a dollar sign. Stock is an observation at the
reported time. affiliate.click_attribution is not_created: this read does not issue
an attributed purchase capability. Do not reconstruct private /go/ links or expose
internal signing tokens. Expired evidence requires a new verification.

An external personal agent retains responsibility for user approval and execution.
There is currently no public purchase, attributed issuance or outcome-reporting
endpoint. Source access does not establish redistribution or automated-purchase
permission. Multiple retailers are independent merchant transactions; never promise
one cross-merchant cart. A future handoff must preserve exact identity, freshness,
merchant rights and attribution before any authorized purchase is attempted.
- /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: dated advertised observations 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.
Usage is limited by the configured key quota. This is not a supplier-dollar spending 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.
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.
  Not the paid program; see Paid work below.
- 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.

## Paid work (27aDay partner pilot)

27aDay, the shopper site built on this data, pays people for golf work.
Full terms: https://27aday.com/llms.txt . Apply: https://27aday.com/partners .
- Fix golf facts: $3 to $5 per accepted task (confirm a spec, find a missing
  loft, check a dead link), even when the answer is "no change needed".
- Lend a photo: $25 flat, or $1 plus 10% of 27aDay's commission on that product.
- Share a list: 20% of 27aDay's commission on purchases through the list.
- The pilot is capped at $200 in total payouts; fact bounties draw from a pool
  of up to $40. Each task shows its reward before it is taken.
- Payouts go only to a verified person who applied and accepted written terms.
AI agents may do fact tasks for the person they work for; that person is paid.
Agents are paid for verifiable work only, never for steering purchases.

## 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://www.golfdata.co/openapi.json