# Find Hipster Coffee Nearby (`mhamas/find-hipster-coffee-nearby`) Actor Find the most hipster coffee shop near you. Drop your GPS coordinates and this actor discovers nearby open coffee shops via Google Maps, uses AI to rate their hipsterness based on reviews and vibe, and returns the top places ranked by a blend of hipster score, Google rating, and walking distance. - **URL**: https://apify.com/mhamas/find-hipster-coffee-nearby.md - **Developed by:** [Matej Hamas](https://apify.com/mhamas) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Hipster Coffee Finder Paste an address from Google Maps, find the most hipster cafe nearby. This actor searches Google Maps for open cafes near your address, sends each one to an AI for a hipsterness rating, and hands you back a ranked list -- the spots with the single-origin pour-overs, the exposed brick, and the reviews that say "hidden gem." ### Quick start ```json { "location": "11266 Donner Pass Rd, Truckee, CA 96161" } ```` Paste an address and hit **Start**. You'll get a ranked list of hipster cafes in the Output tab. ### How it works ``` Address from Google Maps | v [Google Maps Scraper] ──> search "cafe" near address, up to 10 results | v [Category filter] ──> keep only actual cafes | v [Distance filter] ──> keep only cafes within walking distance | v [OpenRouter LLM x N] ──> one AI call per cafe, scored 0-100 | v [Final ranking] ──> all scored cafes ──> default dataset ``` 1. **Google Maps search** -- Passes your address directly to the [Google Maps Scraper](https://apify.com/compass/crawler-google-places) as a location query and searches for "cafe". This works exactly like typing "cafe" into Google Maps near that address. Closed places are excluded. Up to 10 results. 2. **Category filter** -- Removes non-cafe results by checking each place's Google Maps category. Only places categorized as cafes, coffee shops, bakeries, or similar are kept. 3. **Distance filter** -- Keeps only cafes within your walking distance limit (default 1 km). Walking distance is estimated as 1.3x the straight-line distance. The address is geocoded to coordinates for this calculation. 4. **AI hipsterness rating** -- Each cafe is sent to an LLM via the [OpenRouter](https://apify.com/apify/openrouter) Standby API. The model sees the name, category, rating, review snippets, and additional info, then returns a 0-100 hipster score with a one-sentence explanation. All cafes are evaluated in parallel. If a cafe's evaluation fails, it is excluded rather than guessed. 5. **Final ranking** -- A final score is computed for each cafe and all scored results are returned, ranked best first. ### Input | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `location` | String | **Yes** | -- | Address from Google Maps (e.g. "11266 Donner Pass Rd, Truckee, CA 96161") | | `maxWalkingDistanceKm` | Number | No | `1` | Only return cafes within this walking distance (km) | #### Examples **Default (1 km radius):** ```json { "location": "Shibuya, Tokyo" } ``` **Larger radius:** ```json { "location": "350 5th Ave, New York, NY 10118", "maxWalkingDistanceKm": 3 } ``` ### Output Results are saved to the **default dataset**. The Output tab shows a table with rank, name, scores, reason, rating, distance, address, and a clickable Google Maps link. | Field | Type | Description | |-------|------|-------------| | `rank` | Integer | 1 = most hipster | | `title` | String | Cafe name | | `hipsterScore` | Integer | AI-assigned hipsterness (0-100) | | `hipsterReason` | String | Why the AI gave that score | | `finalScore` | Integer | Blended ranking score (0-100) | | `googleRating` | Number | Google Maps stars (0-5) | | `reviewsCount` | Integer | Number of Google reviews | | `estimatedWalkingDistanceKm` | Number | Walking distance from your address (km) | | `address` | String | Full street address | | `categoryName` | String | Google Maps category | | `location` | Object | `{ lat, lng }` of the cafe | | `website` | String | Cafe website | | `phone` | String | Phone number | | `googleMapsUrl` | String | Direct Google Maps link | #### Example ```json [ { "rank": 1, "title": "Wild Cherries Coffee House", "hipsterScore": 68, "hipsterReason": "An indie coffee house with live music, organic/vegan offerings, local specialty focus, and a devoted local following.", "finalScore": 74, "googleRating": 4.6, "reviewsCount": 342, "estimatedWalkingDistanceKm": 0.82, "address": "11429 Donner Pass Rd, Truckee, CA 96161", "categoryName": "Coffee shop", "location": { "lat": 39.3278, "lng": -120.1893 }, "website": "https://wildcherriescoffeehouse.com", "phone": "+1-530-550-9013", "googleMapsUrl": "https://www.google.com/maps/place/..." } ] ``` ### How the final score works Each cafe gets a **final score** (0-100) that determines the ranking. It blends three signals: | Weight | Signal | Source | Normalization | |--------|--------|--------|---------------| | **50%** | Hipster score | LLM rates the cafe 0-100 based on name, reviews, and metadata | score / 100 | | **30%** | Google rating | Average star rating on Google Maps (0-5) | rating / 5 (default 3 if missing) | | **20%** | Proximity | Estimated walking distance from your address | 1 at 0 km, 0 at the max distance | ``` finalScore = round( (hipster * 0.5 + rating * 0.3 + proximity * 0.2) * 100 ) ``` #### What makes a cafe "hipster"? The LLM considers: specialty/third-wave coffee (single origin, pour-over, cold brew), artisanal food (house-made pastries, oat milk, avocado toast), aesthetic (exposed brick, reclaimed wood, vinyl, plants), indie vibes (local art, zine racks, coworking-friendly), and keywords in reviews like "hipster", "artisan", "latte art", or "hidden gem." ### Cost | Service | Per run | |---------|---------| | Google Maps Scraper | ~$0.05-$0.20 | | OpenRouter LLM (up to 10 parallel calls) | ~$0.01-$0.05 | | **Total** | **typically under $0.50** | ### Limitations - **Walking distance is approximate** -- 1.3x straight-line (Haversine), not actual walking directions. - **Closed places are excluded** by the scraper's `skipClosedPlaces` flag. In rare cases a recently-closed cafe may still appear. - **Hipster scores depend on reviews** -- cafes with few or no reviews get conservative estimates. - **Address geocoding** uses OpenStreetMap Nominatim for distance calculation. Very obscure addresses may not resolve precisely. # Actor input Schema ## `location` (type: `string`): Paste an address from Google Maps, e.g. "11266 Donner Pass Rd, Truckee, CA 96161" or "Times Square, New York". ## `maxWalkingDistanceKm` (type: `number`): Only return cafes within this walking distance. Default is 1 km. ## `onlyOpenNow` (type: `boolean`): If checked, only cafes that are open right now (based on their Google Maps opening hours) are included in results. ## Actor input object example ```json { "location": "11266 Donner Pass Rd, Truckee, CA 96161", "maxWalkingDistanceKm": 1, "onlyOpenNow": true } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "location": "11266 Donner Pass Rd, Truckee, CA 96161", "maxWalkingDistanceKm": 1 }; // Run the Actor and wait for it to finish const run = await client.actor("mhamas/find-hipster-coffee-nearby").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "location": "11266 Donner Pass Rd, Truckee, CA 96161", "maxWalkingDistanceKm": 1, } # Run the Actor and wait for it to finish run = client.actor("mhamas/find-hipster-coffee-nearby").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "location": "11266 Donner Pass Rd, Truckee, CA 96161", "maxWalkingDistanceKm": 1 }' | apify call mhamas/find-hipster-coffee-nearby --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mhamas/find-hipster-coffee-nearby", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Find Hipster Coffee Nearby", "description": "Find the most hipster coffee shop near you. Drop your GPS coordinates and this actor discovers nearby open coffee shops via Google Maps, uses AI to rate their hipsterness based on reviews and vibe, and returns the top places ranked by a blend of hipster score, Google rating, and walking distance.", "version": "0.0", "x-build-id": "YoFw83eaed4gZutwG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mhamas~find-hipster-coffee-nearby/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mhamas-find-hipster-coffee-nearby", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mhamas~find-hipster-coffee-nearby/runs": { "post": { "operationId": "runs-sync-mhamas-find-hipster-coffee-nearby", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mhamas~find-hipster-coffee-nearby/run-sync": { "post": { "operationId": "run-sync-mhamas-find-hipster-coffee-nearby", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "location" ], "properties": { "location": { "title": "Address", "type": "string", "description": "Paste an address from Google Maps, e.g. \"11266 Donner Pass Rd, Truckee, CA 96161\" or \"Times Square, New York\"." }, "maxWalkingDistanceKm": { "title": "Max walking distance (km)", "minimum": 0.5, "maximum": 50, "type": "number", "description": "Only return cafes within this walking distance. Default is 1 km.", "default": 1 }, "onlyOpenNow": { "title": "Only currently open", "type": "boolean", "description": "If checked, only cafes that are open right now (based on their Google Maps opening hours) are included in results.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```