Developer Platform

Coffee Intelligence API

A clean REST API for discovering nearby coffee shops, fetching rich shop metadata, and querying real-time crowd intelligence. Powered by Google Places and blended weather, traffic, and time-of-day signals.

Base URL

https://your-domain.com

Version

v1 (stable)

Live · Charleston, SC

Quick Start

Get a key

Request a free demo key in the Authentication section. No card needed.

Send a request

Pass your key in the x-api-key header. All responses are JSON.

Use the data

Each shop includes coordinates, rating, hours, and a live crowd score.

curl "https://your-domain.com/api/shops/nearby?lat=32.7765&lng=-79.9311&radius=8000" \
  -H "x-api-key: caff_demo_YOUR_KEY"

Authentication & API Keys

All requests require an x-api-key header. Demo keys are issued instantly. Full account auth — dashboards, usage graphs, key rotation — is in active development. Keys issued now carry forward.

Header

x-api-key

Demo prefix

caff_demo_…

Pro prefix

caff_pro_…

Auth roadmap

Demo keys work today — rate-limit enforcement ships with account auth
Account sign-up, key dashboard & usage graphs — coming next sprint
Webhook support, Pro tier enforcement, billing — planned

Endpoints

GET/api/shops/nearby

Search coffee shops near coordinates

Returns an array of shops within radius metres of the given coordinates, each enriched with a live crowd insight score.

Param	Type	Req	Description
`lat`	number	✱	Latitude of search origin
`lng`	number	✱	Longitude of search origin
`radius`	number	—	Radius in metres. Default: 10000

GET/api/shops/nearby

lat— latitude

lng— longitude

radius— metres

curl "https://your-domain.com/api/shops/nearby?lat=32.7765&lng=-79.9311&radius=8000" \
  -H "x-api-key: caff_demo_YOUR_KEY"

Example response

{
  "data": [
    {
      "id": "ChIJxxxxxxxxxxxxxxx",
      "name": "Kudu Coffee & Craft Beer",
      "address": "4 Vanderhorst St, Charleston, SC",
      "lat": 32.776,
      "lng": -79.938,
      "rating": 4.6,
      "userRatingsTotal": 1204,
      "distanceMiles": 0.4,
      "insight": {
        "score": 73,
        "label": "Busier Than Usual",
        "updatedAt": "2026-03-14T15:30:00.000Z"
      }
    }
  ],
  "meta": { "lat": 32.7765, "lng": -79.9311, "radius": 8000, "mockMode": false }
}

GET/api/shops/:id

Full shop profile

Returns the complete Shop object for a Google Place ID — photos, hours, contact info, editorial summary, and price level.

Param	Type	Req	Description
`id`	string	✱	Google Place ID from the nearby endpoint (e.g. ChIJ…)

GET/api/shops/ChIJl_lBhJYGoYgRe6mGgLdOBGQ

curl "https://your-domain.com/api/shops/ChIJ_PLACE_ID" \
  -H "x-api-key: caff_demo_YOUR_KEY"

GET/api/shops/:id/insights

Real-time crowd intelligence

Returns a busyness score (0–100), a label, and the full signal breakdown. Scores blend weather, traffic, time-of-day, and day-of-week. Refreshes every 60 s.

Param	Type	Req	Description
`id`	string	✱	Google Place ID

GET/api/shops/ChIJl_lBhJYGoYgRe6mGgLdOBGQ/insights

curl "https://your-domain.com/api/shops/ChIJ_PLACE_ID/insights" \
  -H "x-api-key: caff_demo_YOUR_KEY"

Response schema

{
  "score": 73,
  "label": "Busier Than Usual",
  "breakdown": {
    "weatherScore": 61,
    "trafficScore": 78,
    "timeScore": 82,
    "dayScore": 64,
    "eventScore": 0,
    "rawInputs": { "temperatureF": 68, "precipProbability": 0.05 }
  },
  "explanation": [
    "Traffic near this location is above average for the time of day.",
    "Current weather (partly cloudy, 68°F) slightly favours indoor café visits.",
    "Saturday afternoon is historically a peak period."
  ],
  "updatedAt": "2026-03-14T15:30:00.000Z"
}

GET/api/health

Service health check

Returns service status and timestamp. Useful for uptime monitoring and key validation.

GET/api/health

curl

curl "https://your-domain.com/api/health" \
  -H "x-api-key: caff_demo_YOUR_KEY"

Rate Limits

Rate-limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) ship with full account auth.

Tier	Req / min	Req / day	Price
Demo	20	500	Free
Pro	200	50,000	$99 / mo
Enterprise	Custom	Custom	Contact us