Skip to main content
Coffee Finder is a SaaS web application that helps users discover nearby coffee shops using real-time geolocation and interactive maps powered by OpenStreetMap data.
This quickstart guide will take you from installation to viewing your first interactive coffee shop map in under 5 minutes.

​
Prerequisites

Before you begin, ensure you have one of the following package managers installed:
1

Clone and install dependencies

First, navigate to your project directory and install all required dependencies.
bun install
Coffee Finder uses modern technologies including Next.js 16, TypeScript 5, Tailwind CSS 4, and Leaflet for interactive maps.
2

Start the development server

Launch the development server on port 3000.
bun run dev
Open http://localhost:3000 in your browser to see the application running.
The development server includes hot module replacement (HMR), so changes to your code will automatically refresh in the browser.
3

Grant location permissions

When you first load the application, your browser will request permission to access your location.
Location access is required for Coffee Finder to work. The app uses the Geolocation API to find coffee shops near you.
Click Allow when prompted. The app will:
  1. Request your current coordinates using navigator.geolocation
  2. Center the map on your location
  3. Automatically fetch nearby coffee shops within an 8km radius
If you deny permission, you’ll see an error message with an option to retry.
4

Explore the coffee shop map

Once your location is detected, Coffee Finder displays:
  • Interactive map - Powered by Leaflet with OpenStreetMap tiles
  • Coffee shop markers - Each marker represents a nearby café
  • Shop details panel - Shows ratings, distance, hours, and contact info
The app offers three discovery modes:
  • All - Shows all nearby coffee shops sorted by distance
  • Popular - Highlights top-rated shops with most reviews
  • Trending - Smart algorithm combining ratings, hours, and engagement
5

Search and filter coffee shops

Use the search bar at the top to find specific coffee shops by name.
src/app/page.tsx
const handleSearch = () => {
  if (location.lat && location.lng) {
    fetchCoffeeShops(location.lat, location.lng, searchQuery)
  }
}
The search:
  • Filters results in real-time using the Overpass API
  • Supports case-insensitive matching
  • Maintains your current location context
  • Press Enter or click the search button to execute
Try searching for specific chains, roasters, or keywords like “artisan” or “organic” to narrow your results.
6

Interact with the map

Click on any coffee shop in the sidebar or on a map marker to:
  • Pan the map to that location with smooth animation
  • Zoom in for a closer view (zoom level 17)
  • Highlight the shop in the sidebar
  • View detailed information including contact options
src/app/page.tsx
const handleShopSelect = (shop: CoffeeShop) => {
  setSelectedShop(shop)
  panToLocation(shop.location.lat, shop.location.lng, 17)
}
Click phone icons to call directly or globe icons to visit shop websites.

​
Understanding the API

Coffee Finder uses the Overpass API to fetch real coffee shop data from OpenStreetMap.
The /api/coffee-shops endpoint accepts the following parameters:
ParameterTypeRequiredDescription
latnumberYesYour latitude coordinate
lngnumberYesYour longitude coordinate
querystringNoSearch term to filter shop names
radiusnumberNoSearch radius in meters (default: 8000m)
Example request:
src/app/api/coffee-shops/route.ts
const params = new URLSearchParams({
  lat: lat.toString(),
  lng: lng.toString(),
  ...(query && { query })
})

const response = await fetch(`/api/coffee-shops?${params}`)
const data = await response.json()
Response format:
{
  "shops": [
    {
      "id": "osm-123456789",
      "name": "The Cozy Bean",
      "address": "123 Main Street, San Francisco",
      "rating": 4.5,
      "totalRatings": 328,
      "isOpen": true,
      "phone": "+1 (555) 123-4567",
      "website": "https://example.com/cozy-bean",
      "distance": 450,
      "location": {
        "lat": 37.7749,
        "lng": -122.4194
      },
      "priceLevel": 2,
      "types": ["cafe"]
    }
  ]
}
The API automatically:
  • Queries OpenStreetMap via Overpass API
  • Calculates distances using the Haversine formula
  • Sorts results by proximity
  • Limits results to 60 shops
  • Falls back to mock data if Overpass is unavailable

​
Common features

Real-time geolocation

Uses the browser’s native Geolocation API with high accuracy mode enabled

Live data from OpenStreetMap

Fetches real coffee shop data including hours, ratings, and contact info

Smart discovery modes

Filter by all shops, popular spots, or trending cafés with custom scoring

Interactive Leaflet maps

Pan, zoom, and click markers to explore coffee shops visually

​
Troubleshooting

If you accidentally denied location access:
  1. Click the location icon in your browser’s address bar
  2. Change the permission to Allow
  3. Refresh the page or click the Refresh button in the app header
Alternatively, you can manually enable location in your browser settings under Privacy & Security → Site Settings → Location.
If the map loads but shows no coffee shops:
  • Check your location - The app searches within 8km radius
  • Verify internet connection - Overpass API requires connectivity
  • Wait a moment - Initial queries can take 5-10 seconds
  • Try a different search - Use broader terms or clear the search field
If problems persist, the app will automatically fall back to mock data for testing.
If you see a blank map area:
  • Check console for errors - Open browser DevTools (F12)
  • Verify Leaflet loaded - Look for JavaScript errors
  • Try a hard refresh - Press Ctrl+Shift+R (Cmd+Shift+R on Mac)
  • Clear browser cache - Old cached assets may cause issues
The map uses OpenStreetMap tiles which require internet access.
If bun run dev fails:
# Clear node_modules and reinstall
rm -rf node_modules
bun install

# Check if port 3000 is in use
lsof -i :3000
kill -9 <PID>  # If another process is using port 3000

# Try starting on a different port
next dev -p 3001

​
Next steps

Now that you have Coffee Finder running, explore these resources:

Customize the UI

Learn how to modify colors, themes, and component styles

Deploy to production

Deploy your Coffee Finder instance to Vercel, Netlify, or Docker

API reference

Explore the full API documentation and integration options

Configuration guide

Configure search radius, map settings, and data sources

Build docs developers (and LLMs) love

Get started for freeTalk to us