This API is in Early Access. Service may experience downtime, data gaps, or changes to endpoints. By purchasing, you acknowledge the service is under active development.
Credits purchased during Early Access do not expire and will remain valid when the service reaches general availability. If the API is down for more than 24 hours, we proactively add bonus credits to all active accounts.
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.
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.
Purchase any amount from $5 to $25,000. Credits are deducted per request. 1 credit = $0.005.
| Endpoint | Credits |
|---|---|
| Place search / detail / geo search | 1 per place |
| Menu items | 3 |
| Reviews | 2 |
| Related places | 2 |
| Trending / Hidden gems / Events | 5 |
| Towns list | 10 |
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.
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: 42All 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: trueKentucky's canonical town slugs can be long (e.g. lexington-fayette-urban-county). The API accepts common short names and resolves them for you.
| You send | We query |
|---|---|
| lexington | lexington-fayette-urban-county |
| louisville | louisville-jefferson-county-metro-government-balance |
| bowling green | bowling-green |
| frankfort, berea, paducah, ... | same slug |
Unknown values pass through unchanged and are matched by prefix so your queries still work if you use the canonical slug directly.
GET /api/data/places?town=lexington&limit=50
GET /api/data/places?q=coffee&limit=20Parameters:
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.
GET /api/data/places/overture:abc123Returns 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.
GET /api/data/search?lat=38.04&lng=-84.5&radius=10&category=cafe&limit=20Parameters:
lat, lng — center point (required, must be in Kentucky)radius — km, max 50 (default 10)category — optional filterlimit — max 100 (default 20)Returns charged or same-day deduplicated places sorted by distance with distance_km field.
GET /api/data/places/overture:abc123/reviewsAI-generated review summary with headline, summary text, and confidence score. 2 credits.
GET /api/data/trending?town=lexington&category=cafe&limit=20Top businesses by trending score. Optional town and category filters. 5 credits.
GET /api/data/townsAll Kentucky towns with slug, name, and county. 10 credits, deduplicated daily.
GET /api/data/events?town=lexingtonUpcoming events with title, type, date, venue, town. Optional town filter. 5 credits.
| Status | Meaning |
|---|---|
| 401 | Missing API key |
| 402 | Insufficient credits — buy more at /developers/dashboard |
| 403 | Invalid or revoked API key |
| 400 | Bad request (missing required params) |
| 404 | Resource not found |
| 429 | Rate limited — wait and retry |
| 500 | Server error |
402. Purchase more credits to resume.Retry-After header. Sustained abuse gets your key flagged for review.Questions about the API? Email api@youmeky.ai. Policy on chargebacks, suspensions, and disputes follows our Terms of Service.