Google Maps Business Data Fetcher

A Node.js CLI tool that fetches comprehensive business data from Google Places API and outputs structured JSON and Markdown files. Perfect for gathering information to build websites for local businesses.

Features

• Extracts business data from Google Maps URLs
• Uses the modern Google Places API (New)
• Outputs both JSON (for programmatic use) and Markdown (for website briefs)
• Handles multiple URL formats (place_id, search queries, encoded URLs)
• Includes photos, reviews, hours, contact info, and more

Quick Start

# Install dependencies
npm install

# Set your API key (see setup below)
echo "GOOGLE_MAPS_API_KEY=your_key_here" > .env

# Run the scraper
npm run scrape "https://www.google.com/maps/place/Some+Business/..."

Installation

Requires Node.js 18 or later.

# Clone the repository
git clone <repo-url>
cd google-maps-downloader

# Install dependencies
npm install

Google Cloud Setup

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one

2. Enable the Places API (New)

1. Go to APIs & Services > Library
2. Search for "Places API (New)"
3. Click Enable

Note: This tool uses the Places API (New), not the legacy Places API.

3. Create an API Key

1. Go to APIs & Services > Credentials
2. Click Create Credentials > API Key
3. Copy the generated key

4. (Recommended) Restrict the API Key

1. Click on the API key to edit it
2. Under "API restrictions", select "Restrict key"
3. Select only "Places API (New)"
4. Save

5. Set the Environment Variable

Create a .env file in the project root:

GOOGLE_MAPS_API_KEY=your_api_key_here

Or export it in your shell:

export GOOGLE_MAPS_API_KEY=your_api_key_here

Usage

npm run scrape "<google-maps-url>"

Examples

# Using a place URL
npm run scrape "https://www.google.com/maps/place/The+Coffee+Shop/@40.7484,-73.9857,17z"

# Using a URL with place_id
npm run scrape "https://maps.google.com/?place_id=ChIJN1t_tDeuEmsRUsoyG83frY4"

Output Files

The tool creates two files in the ./output directory:

• <business-name>.json - Structured data for programmatic use
• <business-name>.md - Human-readable summary for website briefs

Output Structure

JSON Format

{
  "meta": {
    "source": "google_places_api",
    "fetched_at": "2025-01-15T10:30:00.000Z",
    "google_place_id": "ChIJ...",
    "google_maps_url": "https://..."
  },
  "basic_info": {
    "name": "Business Name",
    "formatted_address": "123 Main St...",
    "categories": ["restaurant", "bar"],
    "rating": 4.5,
    "user_ratings_total": 250,
    "website": "https://...",
    "price_level": 2
  },
  "contact": {
    "phone": "(555) 123-4567",
    "opening_hours": {
      "weekday_text": ["Monday: 9:00 AM – 9:00 PM", ...],
      "open_now": true
    }
  },
  "location": {
    "lat": 40.7484,
    "lng": -73.9857
  },
  "photos": [
    {
      "photo_url": "https://places.googleapis.com/v1/...",
      "width": 1600,
      "height": 900
    }
  ],
  "reviews": {
    "summary": {
      "average_rating": 4.5,
      "total_reviews": 250,
      "stars_breakdown": { "5": 3, "4": 1, "3": 1, "2": 0, "1": 0 },
      "common_themes": ["great service", "friendly staff"]
    },
    "items": [...]
  }
}

Markdown Format

The Markdown file includes:

• Business overview
• Contact info and hours
• Service options (dine-in, takeout, delivery)
• Location with coordinates
• Why people love this place (based on reviews)
• Rating breakdown
• Customer testimonials (selected for website use)
• Photo URLs

Pricing Considerations

The Google Places API (New) has usage-based pricing:

Operation	Cost per 1,000 requests
Place Details (Basic)	~$17
Place Details (Advanced)	~$20
Text Search	~$32
Photos	~$7

This tool uses field masks to only request needed data and minimize costs. A single business lookup typically costs a few cents.

For accurate pricing, see Google Maps Platform Pricing.

Limitations

• Reviews: The Places API (New) returns up to 5 reviews per request. The total_reviews count is accurate, but the star breakdown is based on the sample returned.
• Photos: Photo URLs are time-limited. Fetch fresh URLs if using them after extended periods.
• Rate Limits: Default quota is sufficient for normal use. For high-volume usage, request a quota increase in Google Cloud Console.

Development

# Build TypeScript
npm run build

# Run directly (builds then runs)
npm run scrape "url"

File Structure

google-maps-downloader/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── config.ts          # Environment configuration
│   ├── types.ts           # TypeScript interfaces
│   ├── urlParser.ts       # Google Maps URL parsing
│   ├── placesApi.ts       # Places API client
│   ├── transformer.ts     # API response transformation
│   ├── reviewAnalyzer.ts  # Review analysis utilities
│   ├── outputJson.ts      # JSON output generator
│   ├── outputMarkdown.ts  # Markdown output generator
│   └── utils.ts           # Utility functions
├── output/                # Generated files
├── package.json
├── tsconfig.json
└── README.md

License

MIT