API Documentation

Early Access Status

If you hit a data-quality issue or bug, email api@youmeky.ai — we respond within 24 hours and often issue bonus credits while we fix the underlying problem.

Authentication

All requests require an API key passed as a Bearer token:

curl https://youmeky.ai/api/data/places?town=lexington \
  -H "Authorization: Bearer ymky_live_YOUR_KEY"

Get a key at /developers/dashboard. Keys start with ymky_live_. Save your key immediately — it is shown only once. After creation, the dashboard and all emails only show ymky_live_...abcd (prefix plus last 4). If you lose a key, rotate or create a new one — we cannot recover it.

Credits & Billing

Purchase any amount from $5 to $25,000. Credits are deducted per request. 1 credit = $0.005.

Your remaining balance is returned in every response at meta.credits_remaining. Place detail responses also include an X-Credits-Remaining header for quick inspection.

Per-place list endpoints only return rows that were charged or already deduplicated for the current UTC day. If the key runs out of credits mid-request, the response includes meta.partial and meta.omitted_unpaid.

Rate Limits

Each key has a per-minute request cap (default 60 req/min). Bursts that exceed the cap return 429 Too Many Requests with a Retry-After header indicating seconds to wait. Credit balance (hard cap) is separate: when credits hit zero you get 402 Payment Required. There is no overage billing — usage past your balance is blocked, not charged. Buy more credits to continue.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678
Retry-After: 42

Deduplication

All resources are deduplicated within a 24-hour UTC day window. Requesting the same business twice in a day is charged only once.

// First request: charged 1 credit
GET /api/data/places/overture:abc123
→ meta.credits_used: 1, meta.deduplicated: false

// Second request same day: free
GET /api/data/places/overture:abc123
→ meta.credits_used: 0, meta.deduplicated: true

Town Aliases

Kentucky's canonical town slugs can be long (e.g. lexington-fayette-urban-county). The API accepts common short names and resolves them for you.

Unknown values pass through unchanged and are matched by prefix so your queries still work if you use the canonical slug directly.

Search Places

GET /api/data/places?town=lexington&limit=50
GET /api/data/places?q=coffee&limit=20

Parameters:

• town — filter by town slug (e.g. lexington, louisville)
• q — keyword search (ILIKE match on name)
• limit — max results, 1-100 (default 50)
• offset — pagination offset (default 0)

Requires town or q. Returns data[] with place_id, name, category, address, phone, website, lat, lng, rating. Rows that cannot be charged are omitted rather than returned free.

Place Detail

GET /api/data/places/overture:abc123

Returns full business detail including hours, description, and enrichment tier. The response also includes field_trust, a per-field trust contract with value, trustTier, sourceCount, and lastVerifiedAt. 1 credit, deduplicated daily.

Geo Search

GET /api/data/search?lat=38.04&lng=-84.5&radius=10&category=cafe&limit=20

Parameters:

• lat, lng — center point (required, must be in Kentucky)
• radius — km, max 50 (default 10)
• category — optional filter
• limit — max 100 (default 20)

Returns charged or same-day deduplicated places sorted by distance with distance_km field.

Menu Items

GET /api/data/places/overture:abc123/menu

LLM-extracted menu data: item name, description, price, category, dietary tags. 3 credits per request.

Reviews

GET /api/data/places/overture:abc123/reviews

AI-generated review summary with headline, summary text, and confidence score. 2 credits.

Related Places

GET /api/data/places/overture:abc123/related

Connected businesses by proximity, category, or co-visitation. Up to 10 results. 2 credits.

Trending

GET /api/data/trending?town=lexington&category=cafe&limit=20

Top businesses by trending score. Optional town and category filters. 5 credits.

Hidden Gems

GET /api/data/hidden-gems?town=berea&limit=10

High hidden-gem-score local businesses (chains excluded). Optional town filter. 5 credits.

Towns

GET /api/data/towns

All Kentucky towns with slug, name, and county. 10 credits, deduplicated daily.

Events

GET /api/data/events?town=lexington

Upcoming events with title, type, date, venue, town. Optional town filter. 5 credits.

Error Codes

Policy & Terms

• All sales are final. Credits are non-refundable and non-transferable. Unused credits do not expire.
• No overage charges. Usage past your balance is blocked with 402. Purchase more credits to resume.
• One active production key per account. Requesting a new key rotates the old one with a 24-hour grace period; after 24 hours the old key is revoked.
• Emergency revocation. If your key is compromised, revoke it from the dashboard — this is instant and breaks any app using that key.
• Rate-limit enforcement. 429 responses are not errors on our side — back off with the Retry-After header. Sustained abuse gets your key flagged for review.
• Privacy. We log request metadata (endpoint, status, timestamp, resource_id) but never your request headers or response bodies.

Questions about the API? Email api@youmeky.ai. Policy on chargebacks, suspensions, and disputes follows our Terms of Service.