Menu
Location intelligence for business — geocoding, places search, routing optimization, Google Business Profile
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Manage projects on Nulab Backlog — issues, wikis, milestones, Git, sprints for Japan's top PM tool
Automate Japan's
Unified Gmail, Calendar, Drive, Sheets, and Docs management from Claude Code
Task and project management on Jooto — create tasks, manage boards, automate workflows via PR TIMES' tool
Attendance and time tracking automation — daily/monthly data, payroll sync via Japan's leading attendance system
Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform
| name | google-maps-biz |
| description | Location intelligence for business — geocoding, places search, routing optimization, Google Business Profile |
| author | hanabi-jpn |
| version | 1.0.0 |
| tags | ["google-maps","geocoding","places-api","routing","business-profile","location-intelligence","store-locator"] |
╔═══════════════════════════════════════════════════╗
║ ┌─────────────────────────────────────────────┐ ║
║ │ G O O G L E M A P S B U S I N E S S │ ║
║ │ ━━━━━━━━━━━━━━━━━━━━ │ ║
║ │ 📍 Geocode ── Places ── Routes │ ║
║ │ 🏪 Reviews ── Competitors ── Profile │ ║
║ │ Location Intelligence for Business │ ║
║ └─────────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════════╝
google-maps-biz business-profile geocoding places-api route-optimizer
Turn raw addresses into business decisions -- geocode, search, route, and dominate your local market with the full power of Google Maps Platform.
Google Maps Business Agent transforms the Google Maps Platform into a command-line business intelligence tool. Instead of writing boilerplate API integration code, you issue natural commands like maps search "ramen near Shibuya" and receive structured, actionable data. The agent handles API key management, quota tracking, pagination, and result enrichment behind the scenes so you can focus on extracting location insights.
The architecture is built around a layered pipeline. Raw requests flow through an authentication layer that injects your API key, then through a request builder that translates human-readable commands into properly formatted API calls, and finally through a response parser that normalizes the heterogeneous outputs from Places, Directions, Geocoding, and Business Profile APIs into a consistent tabular format. A local cache layer prevents redundant API calls for repeated queries, and a quota monitor warns you before you hit billing thresholds.
USER COMMAND
|
v
+----------------+ +------------------+ +-------------------+
| Command Parser |---->| Auth & Key Mgmt |---->| Google Maps APIs |
+----------------+ +------------------+ | - Places API |
| | | - Directions API |
| | | - Geocoding API |
| | | - Business Profile |
| v +-------------------+
| +------------------+ |
| | Local Cache |<-----------+
| | (SQLite, 24h TTL)|
| +------------------+
| |
v v
+----------------+ +------------------+
| Output Render |<----| Response Parser |
| (table/json/ | | & Normalizer |
| csv/map-url) | +------------------+
+----------------+
|
v
TERMINAL OUTPUT
For businesses operating in Japan and across Asia-Pacific, the agent includes region-aware defaults such as Japanese-language place results, metric distance units, and address formatting that respects the Japanese postal system. Multi-stop route optimization uses a nearest-neighbor heuristic with optional TSP solver integration for delivery fleet planning.
You are Google Maps Business Agent, a location intelligence assistant. Follow these rules precisely:
GOOGLE_MAPS_API_KEY environment variable before making any API call. If missing, return a clear error with setup instructions.MAPS_DEFAULT_REGION (default: JP). Users can override per-command with --region.name, formatted_address, geometry, rating, user_ratings_total, business_status, opening_hours, types, price_level.lat, lng, formatted_address, place_id, and plus_code when available.--traffic flag is set. Default to best_guess departure time model.GMAP-****XXXX in logs and debug output.~/.clawhub/google-maps-biz/cache.db with a 24-hour TTL to reduce API costs.--sort rating, --sort distance, or --sort reviews is specified.GOOGLE_BUSINESS_ACCOUNT_ID. If not set, return a warning and skip profile-specific fields.--units.--no-rate-limit is explicitly passed.--format json, --format csv, and --format map-url for programmatic use.NNN-NNNN format.~/.clawhub/google-maps-biz/api.log for cost auditing.| Variable | Required | Default | Description |
|---|---|---|---|
GOOGLE_MAPS_API_KEY | Yes | -- | Google Maps Platform API key with Places, Directions, and Geocoding APIs enabled |
GOOGLE_BUSINESS_ACCOUNT_ID | No | -- | Google Business Profile account ID for profile management commands |
MAPS_DEFAULT_REGION | No | JP | ISO 3166-1 alpha-2 region code for default query bias |
maps searchSearch for places by keyword and location.
$ maps search "ramen near Shibuya Station" --limit 5
# Name Rating Reviews Address Status
1 Fuunji 4.3 4,812 3-7-2 Yoyogi, Shibuya-ku, Tokyo OPERATIONAL
2 Afuri Shibuya 4.1 3,204 1-1-7 Ebisu, Shibuya-ku, Tokyo OPERATIONAL
3 Ichiran Shibuya 3.9 6,519 1-22-7 Jinnan, Shibuya-ku, Tokyo OPERATIONAL
4 Nagi Shinjuku Golden Gai 4.4 2,891 1-1-10 Kabukicho, Shinjuku-ku, Tokyo OPERATIONAL
5 Menya Musashi Kosho 4.0 1,733 3-26-1 Yoyogi, Shibuya-ku, Tokyo OPERATIONAL
Found 5 results | Region: JP | Cached: No | API cost: ~$0.032
maps geocodeConvert an address to coordinates or coordinates to an address.
$ maps geocode "東京都渋谷区神宮前1-1-1"
Address: 1-1-1 Jingumae, Shibuya-ku, Tokyo 150-0001, Japan
Latitude: 35.6694
Longitude: 139.7027
Place ID: ChIJe_oF2COOGLARYP-hnfTHsms
Plus Code: 8Q7XMMG2+QV
Postal: 150-0001
Confidence: ROOFTOP
API cost: ~$0.005
maps routeCalculate directions between two or more points.
$ maps route "Tokyo Station" "Yokohama Station" --mode driving --traffic
Route: Tokyo Station -> Yokohama Station
Distance: 31.4 km
Duration: 42 min (in traffic: 58 min)
Toll Cost: ¥1,320 (ETC: ¥920)
Via: Shuto Expressway -> Bay Shore Route
Step Instruction Distance Duration
1 Head south on Yaesu-dori 0.8 km 3 min
2 Merge onto Shuto Expressway 18.2 km 22 min
3 Continue onto Bay Shore Route 9.1 km 12 min
4 Take exit toward Yokohama Station 3.3 km 5 min
Departure: now | Traffic model: best_guess | API cost: ~$0.010
maps businessManage your Google Business Profile listings.
$ maps business status --account my-ramen-shop
Business: Hanabi Ramen Shibuya
Status: VERIFIED
Category: Ramen Restaurant
Phone: +81-3-1234-5678
Website: https://hanabi-ramen.jp
Hours: Mon-Sat 11:00-23:00, Sun 11:00-21:00
Rating: 4.6 (823 reviews)
Photos: 34 uploaded
Posts: Last post: 3 days ago
Q&A: 12 unanswered questions
Profile completeness: 92% | Suggestion: Answer pending Q&A to improve ranking
maps nearbyFind businesses within a radius of a given location.
$ maps nearby "35.6595,139.7004" --type restaurant --radius 500 --limit 5
# Name Type Dist Rating Price
1 Trattoria Ciao Italian 120m 4.5 ¥¥
2 Sushi Dai Sushi 230m 4.7 ¥¥¥
3 CoCo Ichibanya Curry 310m 3.8 ¥
4 Wendy's First Kitchen Fast Food 380m 3.4 ¥
5 Uobei Shibuya Sushi 450m 4.1 ¥
Radius: 500m | Results: 5/47 | Region: JP
maps reviewsFetch and analyze reviews for a place.
$ maps reviews "Fuunji Ramen" --analyze
Place: Fuunji (ふうんじ)
Rating: 4.3/5.0 (4,812 reviews)
Sentiment Breakdown:
Positive: 78% ████████████████░░░░
Neutral: 14% ███░░░░░░░░░░░░░░░░░
Negative: 8% ██░░░░░░░░░░░░░░░░░░
Top Themes:
"tsukemen" mentioned 1,204 times (positive: 91%)
"queue/wait" mentioned 892 times (negative: 67%)
"fish broth" mentioned 634 times (positive: 88%)
"portion size" mentioned 412 times (positive: 72%)
Recent Trend: Rating stable at 4.3 over last 6 months
maps optimizeOptimize a multi-stop delivery or visit route.
$ maps optimize --stops "Shibuya,Shinjuku,Ikebukuro,Ueno,Tokyo,Shinagawa" --start "Shibuya"
Optimized Route (6 stops, round-trip):
Total Distance: 28.7 km | Total Time: 1h 14min
Order Stop Arrive Depart Leg Dist Leg Time
1 Shibuya -- 09:00 -- --
2 Shinjuku 09:12 09:22 4.2 km 12 min
3 Ikebukuro 09:35 09:45 5.1 km 13 min
4 Ueno 10:02 10:12 7.3 km 17 min
5 Tokyo 10:22 10:32 3.8 km 10 min
6 Shinagawa 10:44 10:54 5.2 km 12 min
-> Shibuya 11:07 -- 3.1 km 13 min
Savings vs. original order: 6.3 km / 18 min
Algorithm: nearest-neighbor | API cost: ~$0.015
maps competitorAnalyze competitor density and positioning around a location.
$ maps competitor "ramen" --center "Shibuya Station" --radius 1km
Competitor Analysis: "ramen" within 1km of Shibuya Station
Total Competitors: 23
Rating Distribution:
5.0 ░░ 1
4.0-4.9 ████████████ 12
3.0-3.9 ███████ 8
<3.0 ██ 2
Price Level:
¥ ████ 4
¥¥ ████████████ 13
¥¥¥ ████ 5
¥¥¥¥ ░ 1
Density Score: 7.3/10 (HIGH COMPETITION)
Avg Rating: 3.9 | Avg Reviews: 1,247 | Median Price: ¥¥
Opportunity: Low competition in ¥¥¥ segment with 4.5+ rating
maps bulk-geocodeGeocode a batch of addresses from a CSV file.
$ maps bulk-geocode addresses.csv --output geocoded.csv
Processing 150 addresses...
[████████████████████████████░░] 142/150 (94.7%)
Results:
Success: 142 (94.7%)
Partial: 5 (3.3%) <- low confidence matches
Failed: 3 (2.0%) <- unresolvable addresses
Failed addresses written to: geocode_errors.csv
Output saved to: geocoded.csv (columns: address, lat, lng, place_id, confidence)
Total API cost: ~$0.750 | Time: 34s | Rate: 4.4 req/s
+-----------+
| User CLI |
+-----+-----+
|
+------------+-------------+
| | |
[search] [geocode] [route]
| | |
v v v
+--------+ +--------+ +----------+
| Places | | Geocode| | Directions|
| API | | API | | API |
+---+----+ +---+----+ +-----+-----+
| | |
+------+-----+------+------+
| |
v v
+----------+ +---------+
| Cache | | Quota |
| (SQLite) | | Monitor |
+----+-----+ +----+----+
| |
v v
+----------+ +---------+
| Response | | Cost |
| Renderer | | Logger |
+----+-----+ +---------+
|
v
FORMATTED OUTPUT
(table/json/csv)
| Error | Cause | Solution |
|---|---|---|
AUTH_FAILED: Invalid API key | Expired or misconfigured API key | Run echo $GOOGLE_MAPS_API_KEY to verify. Regenerate at console.cloud.google.com if needed. |
QUOTA_EXCEEDED: Daily limit reached | API usage exceeded the $200/month free tier or daily cap | Check usage at console.cloud.google.com/billing. Set --no-rate-limit if you accept higher costs. |
ZERO_RESULTS: No places found | Query too specific or region mismatch | Broaden the search radius with --radius, or change --region to match target location. |
GEOCODE_PARTIAL: Low confidence match | Ambiguous or incomplete address | Provide full postal code and prefecture. Use --strict to reject partial matches entirely. |
ROUTE_NOT_FOUND: No route between points | Points are on different islands or unreachable by the specified mode | Try --mode transit for island-to-island routes, or verify coordinates are on road-accessible land. |
BUSINESS_UNVERIFIED: Profile not claimed | Attempting profile management on unverified listing | Complete Google Business verification flow at business.google.com before using maps business commands. |
RATE_LIMITED: Too many requests | Burst of requests exceeded per-second QPS limit | The agent automatically retries with exponential backoff. If persistent, reduce --concurrency for bulk ops. |
All persistent data is stored under ~/.clawhub/google-maps-biz/:
| Path | Purpose | Format | Retention |
|---|---|---|---|
cache.db | Geocoding and Places result cache | SQLite | 24 hours TTL, auto-pruned |
api.log | API call log with timestamps and costs | JSON lines | 90 days, rotated monthly |
favorites.json | Saved locations and frequent searches | JSON | Permanent until user deletes |
routes/ | Saved optimized routes | JSON per route | Permanent |
exports/ | CSV and GeoJSON export files | CSV / GeoJSON | Permanent |
| Feature | google-maps-biz | Google Maps Console | Mapbox CLI | OpenStreetMap / Nominatim |
|---|---|---|---|---|
| Places Search (200M+ POI) | Yes | Yes | Limited POI | Community-sourced |
| Real-time Traffic Routing | Yes | Yes | Yes | No |
| Japanese Address Parsing | Native (kanji + romaji) | Yes | Limited | Partial |
| Google Business Profile | Yes | Yes | No | No |
| Bulk Geocoding | Yes (CSV pipeline) | Manual only | Yes | Yes (rate-limited) |
| Route Optimization (TSP) | Yes (built-in) | No | Yes (Optimization API) | No |
| Competitor Analysis | Yes (density score) | No | No | No |
| Cost Tracking | Per-command breakdown | Monthly aggregate | Per-request | Free |
| Offline Cache | SQLite, 24h TTL | No | No | Self-hosted option |
| CLI-native Output | Table, JSON, CSV, map-url | Web UI only | JSON | JSON/XML |
| Price | API costs ($0.005-$0.03/req) | Same API costs | $0.005-$0.06/req | Free (self-host) |
1. How do I get a Google Maps API key? Go to console.cloud.google.com, create a project, enable Places API, Directions API, and Geocoding API, then create an API key under Credentials. Restrict the key to these three APIs for security.
2. How much does this cost to use? Google offers $200/month in free credits. A typical search costs $0.032, geocoding costs $0.005, and routing costs $0.010. The agent tracks spending per-command so you always know your burn rate.
3. Can I use this without a Google Business Profile?
Yes. All commands except maps business work without a Business Profile. The GOOGLE_BUSINESS_ACCOUNT_ID variable is optional.
4. How does the cache work?
Every geocoding and places result is cached locally in SQLite with a 24-hour TTL. Repeated queries hit the cache instead of the API, saving money. Use --no-cache to force a fresh request.
5. Can I geocode Japanese addresses in kanji? Yes. The agent accepts both kanji addresses like "東京都渋谷区神宮前1-1-1" and romaji like "1-1-1 Jingumae, Shibuya-ku, Tokyo". Postal codes in NNN-NNNN format are also supported.
6. How does route optimization work?
The maps optimize command uses a nearest-neighbor heuristic by default. For routes with 10+ stops, it applies a 2-opt improvement pass. This is not a guaranteed optimal solution for large TSP instances but produces near-optimal results in seconds.
7. What output formats are supported?
Table (default for terminal), JSON (--format json), CSV (--format csv), and map URL (--format map-url) which generates a Google Maps link you can open in a browser.
8. Can I use this for delivery fleet routing?
Yes. Combine maps optimize with --start and --end flags for depot-to-depot routing. For multiple vehicles, split stops into groups and optimize each independently.
9. How does competitor analysis calculate the density score? The density score (0-10) is based on the number of matching businesses per square kilometer, weighted by their average rating and review count. A score above 7 indicates high competition.
10. Is there a rate limit?
Google enforces 50 QPS (queries per second) by default. The agent self-limits to stay within free tier spending unless you pass --no-rate-limit. Bulk operations use configurable concurrency with --concurrency.
11. Can I export results as GeoJSON for mapping tools?
Yes. Use --format geojson on any search or geocode command to produce a GeoJSON FeatureCollection compatible with QGIS, Mapbox, or Leaflet.
12. Does the agent handle API key rotation?
Not automatically. However, the quota monitor warns you at 80% of your monthly budget. You can set up multiple keys and switch with export GOOGLE_MAPS_API_KEY=new_key.