{"openapi":"3.1.0","info":{"title":"YouMeKY Data API","version":"0.1.0","description":"Query-by-query access to the YouMeKY Kentucky business graph: 363,000+ places with category, location, narrative, attributes, and KY-specific signals. See https://youmeky.ai/developers for full documentation.","contact":{"email":"data@youmeky.ai","url":"https://youmeky.ai/developers"},"license":{"name":"Commercial — pay-as-you-go","url":"https://youmeky.ai/developers"}},"servers":[{"url":"https://youmeky.ai","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (ymky_live_*)","description":"Use your YouMeKY API key from https://youmeky.ai/developers/dashboard as a Bearer token."}},"schemas":{"Place":{"type":"object","properties":{"place_id":{"type":"string","example":"gem_1ac02b33"},"name":{"type":"string"},"category":{"type":"string","example":"amenity:restaurant"},"address":{"type":"string"},"town_slug":{"type":"string","nullable":true},"latitude":{"type":"number","format":"float","nullable":true},"longitude":{"type":"number","format":"float","nullable":true},"is_gem":{"type":"boolean"},"local_gem_score":{"type":"number","format":"float","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","format":"uri","nullable":true},"rating":{"type":"number","format":"float","nullable":true},"rating_count":{"type":"integer","nullable":true},"seo_description":{"type":"string","nullable":true},"canonical_url":{"type":"string","format":"uri"},"field_trust":{"type":"object","description":"Per-field trust metadata. During Stage 1/2 rollout these fields may be null until trust scoring is joined into the read path.","additionalProperties":{"$ref":"#/components/schemas/FieldTrust"}}},"required":["place_id","name","category","canonical_url"]},"FieldTrust":{"type":"object","properties":{"value":{},"trustTier":{"type":"string","enum":["verified","supported","thin","low"],"nullable":true},"sourceCount":{"type":"integer","nullable":true},"lastVerifiedAt":{"type":"string","format":"date-time","nullable":true}},"required":["value","trustTier","sourceCount","lastVerifiedAt"]},"Event":{"type":"object","properties":{"event_id":{"type":"string"},"title":{"type":"string"},"start_date":{"type":"string","format":"date-time"},"town_slug":{"type":"string","nullable":true},"venue_place_id":{"type":"string","nullable":true}}},"Town":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"county":{"type":"string","nullable":true},"population":{"type":"integer","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}},"ApiMeta":{"type":"object","description":"Usage metadata returned by every paid Data API response. credits_remaining is the remaining prepaid API credits after this request.","properties":{"count":{"type":"integer","nullable":true},"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"deduplicated":{"type":"boolean","nullable":true},"deduplicated_count":{"type":"integer","nullable":true},"partial":{"type":"boolean","nullable":true},"omitted_unpaid":{"type":"integer","nullable":true}},"required":["credits_used","credits_remaining"]},"PlaceListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Place"}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]},"PlaceResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Place"},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]},"TownListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Town"}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]},"EventListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]},"GenericListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]}},"parameters":{"PlaceId":{"name":"placeId","in":"path","required":true,"schema":{"type":"string"},"description":"Canonical YouMeKY place_id."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Out of credits. Purchase more at /developers/dashboard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/data/places":{"get":{"summary":"Search or list businesses","description":"Filter by town or keyword. Costs 1 credit per place returned.","parameters":[{"name":"town","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of places.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/places/{placeId}":{"get":{"summary":"Full business detail","description":"All public fields for a single place. Costs 1 credit.","parameters":[{"$ref":"#/components/parameters/PlaceId"}],"responses":{"200":{"description":"Place record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Unknown place_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/data/places/{placeId}/menu":{"get":{"summary":"Restaurant menu items","description":"Menu items scraped and normalized from the business website. Costs 3 credits.","parameters":[{"$ref":"#/components/parameters/PlaceId"}],"responses":{"200":{"description":"Menu items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No menu data for this place."}}}},"/api/data/places/{placeId}/reviews":{"get":{"summary":"AI-generated review summary","description":"Narrative review summary synthesized by YouMeKY. Costs 2 credits.","parameters":[{"$ref":"#/components/parameters/PlaceId"}],"responses":{"200":{"description":"Review summary.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/places/{placeId}/related":{"get":{"summary":"Connected businesses","description":"Related places from the YouMeKY graph edges. Costs 2 credits.","parameters":[{"$ref":"#/components/parameters/PlaceId"}],"responses":{"200":{"description":"Related places.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/search":{"get":{"summary":"Geospatial search","description":"Search for places within a radius of a point. Costs 1 credit per place returned.","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radius","in":"query","description":"Radius in kilometers.","schema":{"type":"number","default":5}}],"responses":{"200":{"description":"Matching places sorted by distance.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Place"}},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","meta"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/trending":{"get":{"summary":"Trending businesses","description":"Places trending up on YouMeKY right now. Costs 5 credits.","responses":{"200":{"description":"Trending places.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/hidden-gems":{"get":{"summary":"Hidden gem discoveries","description":"Lesser-known places with high local-gem scores. Costs 5 credits.","responses":{"200":{"description":"Hidden gems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/towns":{"get":{"summary":"All Kentucky towns","description":"Complete list of Kentucky towns with slugs. Costs 10 credits.","responses":{"200":{"description":"Towns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TownListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/data/events":{"get":{"summary":"Upcoming events","description":"Events across Kentucky. Costs 5 credits.","parameters":[{"name":"town","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Upcoming events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}}}}