# GoogleMapsAPI.io — Complete LLM & AI Agent Technical Reference (llms-full.txt) > Real-time REST API for Google Maps local business search, nearby bounding-box discovery, full place details, verified customer reviews, photos, autocomplete, reverse geocoding, and website B2B email & social profile enrichment. > Base URL: `https://api.googlemapsapi.io` | Main Website: `https://googlemapsapi.io` > OpenAPI 3.1 Spec: `https://googlemapsapi.io/openapi.json` | Compact Summary: `https://googlemapsapi.io/llms.txt` ## 1. Authentication & Core Architecture - **Base URL**: `https://api.googlemapsapi.io` - **Authentication Header**: Pass either `x-api-key: gm_live_your_api_key` OR `Authorization: Bearer gm_live_your_api_key` on every request. - **Free Trial**: Every new account receives **2,000 Free Credits** immediately upon sign-up at `https://googlemapsapi.io/signup`. - **Zero Charge on Empty Searches & Errors**: Any search returning 0 results, enrichment finding 0 emails/socials, or 4xx/5xx response costs **0 Credits**. - **Latency SLA**: Warm PostgreSQL 16 + GiST Spatial Index: `15–50 ms`; Live Upstream SERP & Domain Crawl: `0.8–2.5 s`. ## 2. Pricing & Record-Based Credit System ($1 = 10,000 Credits) | Data Type / Endpoint | Credits | Base PAYG | Pro ($199/mo) | Business ($499/mo) | Batch Size | | :--- | :--- | :--- | :--- | :--- | :--- | | Place Text & Nearby Search (`/v1/places/search`, `/v1/places/nearby`) | 5 Credits / place | $0.50 / 1K places | $0.28 / 1K places | $0.20 / 1K places | Up to 100 places/call | | Customer Reviews & Photos (`/v1/places/reviews`, `/v1/places/photos`) | 2 Credits / item | $0.20 / 1K items | $0.11 / 1K items | $0.08 / 1K items | Up to 100 items/call | | Full Place Details & B2B Lead Enrich (`/v1/places/details`, `/v1/leads/enrich`) | 20 Credits / call | $2.00 / 1K calls | $1.14 / 1K calls | $0.80 / 1K calls | 1 full profile / domain | | Autocomplete & Reverse Geocode (`/v1/places/autocomplete`, `/v1/geocode/reverse`) | 5 Credits / call | $0.50 / 1K calls | $0.28 / 1K calls | $0.20 / 1K calls | 5–10 predictions | ## 3. Complete Endpoint Reference & Code Samples ### Google Maps Text Search (`GET /v1/places/search`) - **Documentation URL**: https://googlemapsapi.io/docs/places-search - **Cost**: 5 Credits / place (min 10; 0 if empty) ($0.0005 / place ($0.20–$0.50 / 1K places)) - **Description**: Search Google Maps local businesses by natural-language query (e.g., 'coffee shops in SoHo, New York' or 'emergency plumbers in Austin, TX'). Returns structured business profiles including place_id, cid, phone number, website domain, rating, review count, opening hours, price level, and GPS coordinates. - **Parameters**: - `q` (query, required): Free-text search query including business category and location (e.g., 'coffee shops in SoHo, New York'). [example: `coffee shops in SoHo, New York`] - `lat` (query, optional): Optional latitude coordinate to bias search results (-90 to 90). [example: `40.7233`] - `lng` (query, optional): Optional longitude coordinate to bias search results (-180 to 180). [example: `-74.003`] - `zoom` (query, optional): Map viewport zoom level (3 to 21, default 14). [example: `14`] - `limit` (query, optional): Maximum number of businesses to return (1 to 100, default 20). [example: `20`] - `region` (query, optional): ISO 3166-1 alpha-2 country code (e.g., 'us', 'gb', 'de'). [example: `us`] - `language` (query, optional): ISO 639-1 language code for localized names and categories (default 'en'). [example: `en`] - `fresh` (query, optional): Bypass the 30-day PostgreSQL index cache and force a live upstream Google Maps SERP fetch. [example: `false`] ```bash curl "https://api.googlemapsapi.io/v1/places/search?q=coffee+shops+in+SoHo%2C+New+York" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/search?q=coffee+shops+in+SoHo%2C+New+York", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Nearby & Bounding-Box Search (`GET /v1/places/nearby`) - **Documentation URL**: https://googlemapsapi.io/docs/places-nearby - **Cost**: 5 Credits / place (min 10; 0 if empty) ($0.0005 / place ($0.20–$0.50 / 1K places)) - **Description**: Discover Google Maps businesses inside a geographic viewport around exact GPS coordinates (lat, lng, zoom) or within an explicit bounding box (min_lat, min_lng, max_lat, max_lng). Ideal for grid-based territory scraping. - **Parameters**: - `q` (query, required): Category or keyword to search within the target coordinates (e.g., 'italian restaurant', 'HVAC contractor'). [example: `italian restaurant`] - `lat` (query, required): Center latitude coordinate (-90 to 90). [example: `40.7233`] - `lng` (query, required): Center longitude coordinate (-180 to 180). [example: `-74.003`] - `zoom` (query, optional): Map viewport zoom level (3 to 21, default 15). [example: `15`] - `limit` (query, optional): Maximum number of businesses to return (1 to 100, default 20). [example: `20`] ```bash curl "https://api.googlemapsapi.io/v1/places/nearby?q=italian+restaurant&lat=40.7233&lng=-74.003" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/nearby?q=italian+restaurant&lat=40.7233&lng=-74.003", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Place Details & Full Business Profile (`GET /v1/places/details`) - **Documentation URL**: https://googlemapsapi.io/docs/places-details - **Cost**: 20 Credits / business profile ($0.002 / profile ($0.80–$2.00 / 1K profiles)) - **Description**: Retrieve the complete Google Business Profile by place_id, cid, or google_id. Includes verified contact info, rating breakdown (1-star to 5-star counts), full weekly opening hours, service attributes, and cached website contact enrichment. - **Parameters**: - `place_id` (query, required): Google Maps Place ID (e.g., 'ChIJN5X_gWdZwokRck9rk2guJ1M'), numeric CID, or hex Google ID. [example: `ChIJN5X_gWdZwokRck9rk2guJ1M`] - `language` (query, optional): ISO 639-1 language code (default 'en'). [example: `en`] - `fresh` (query, optional): Bypass local PostgreSQL cache and fetch live from Google Maps. [example: `false`] ```bash curl "https://api.googlemapsapi.io/v1/places/details?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/details?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Place Customer Reviews & Owner Replies (`GET /v1/places/reviews`) - **Documentation URL**: https://googlemapsapi.io/docs/places-reviews - **Cost**: 2 Credits / review (min 10; 0 if empty) ($0.0002 / review ($0.08–$0.20 / 1K reviews)) - **Description**: Fetch verified customer reviews for any Google Maps business by place_id or cid. Supports sorting by newest, highest_rating, lowest_rating, or most_relevant, plus keyword filtering. - **Parameters**: - `place_id` (query, required): Google Maps Place ID or numeric CID. [example: `ChIJN5X_gWdZwokRck9rk2guJ1M`] - `sort` (query, optional): Sort order: 'most_relevant', 'newest', 'highest_rating', or 'lowest_rating'. [example: `newest`] - `limit` (query, optional): Number of reviews to return (1 to 100, default 20). [example: `20`] - `query` (query, optional): Optional keyword filter to match inside review text (e.g., 'espresso', 'service'). [example: `espresso`] ```bash curl "https://api.googlemapsapi.io/v1/places/reviews?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/reviews?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Place High-Resolution Photos (`GET /v1/places/photos`) - **Documentation URL**: https://googlemapsapi.io/docs/places-photos - **Cost**: 2 Credits / photo (min 6; 0 if empty) ($0.0002 / photo ($0.08–$0.20 / 1K photos)) - **Description**: Retrieve high-resolution photo URLs, dimensions, categories (exterior, interior, food & drink, menu), and contributor attribution for a Google Maps business. - **Parameters**: - `place_id` (query, required): Google Maps Place ID or numeric CID. [example: `ChIJN5X_gWdZwokRck9rk2guJ1M`] - `limit` (query, optional): Maximum number of photos to return (1 to 50, default 20). [example: `20`] ```bash curl "https://api.googlemapsapi.io/v1/places/photos?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/photos?place_id=ChIJN5X_gWdZwokRck9rk2guJ1M", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Website Email, Phone & Social Lead Enrichment (`GET /v1/leads/enrich`) - **Documentation URL**: https://googlemapsapi.io/docs/leads-enrich - **Cost**: 20 Credits / enriched domain (0 if none found) ($0.002 / enriched domain ($0.80–$2.00 / 1K leads)) - **Description**: Crawl a business website domain (or look up by place_id) to extract verified B2B email addresses, direct phone numbers, contact page URLs, and social media profiles across LinkedIn, Instagram, Facebook, X/Twitter, YouTube, TikTok, Pinterest, and GitHub. Charges 0 Credits if no emails or social links are found. - **Parameters**: - `domain` (query, required): Business website domain or URL (e.g., 'felixroastingco.com' or 'bluebottlecoffee.com'). [example: `felixroastingco.com`] - `place_id` (query, optional): Optional Google Maps Place ID to link enriched contacts back to the stored business profile. [example: `ChIJN5X_gWdZwokRck9rk2guJ1M`] ```bash curl "https://api.googlemapsapi.io/v1/leads/enrich?domain=felixroastingco.com" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/leads/enrich?domain=felixroastingco.com", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Place & Address Typeahead Autocomplete (`GET /v1/places/autocomplete`) - **Documentation URL**: https://googlemapsapi.io/docs/places-autocomplete - **Cost**: 5 Credits / request ($0.0005 / request ($0.20–$0.50 / 1K calls)) - **Description**: Real-time typeahead predictions for businesses, street addresses, cities, and landmarks with optional coordinate and country biasing. - **Parameters**: - `q` (query, required): Partial text input from the user (e.g., '1600 Amphitheatre' or 'Felix Roast'). [example: `1600 Amphitheatre`] - `country` (query, optional): ISO 3166-1 alpha-2 country code restriction (e.g., 'US'). [example: `US`] - `lat` (query, optional): Optional latitude for proximity biasing. [example: `37.422`] - `lng` (query, optional): Optional longitude for proximity biasing. [example: `-122.084`] ```bash curl "https://api.googlemapsapi.io/v1/places/autocomplete?q=1600+Amphitheatre" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/places/autocomplete?q=1600+Amphitheatre", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` --- ### Reverse Geocoding (Coordinates to Address) (`GET /v1/geocode/reverse`) - **Documentation URL**: https://googlemapsapi.io/docs/geocode-reverse - **Cost**: 5 Credits / request ($0.0005 / request ($0.20–$0.50 / 1K calls)) - **Description**: Convert raw GPS latitude and longitude coordinates into structured street addresses, postal codes, administrative areas, and corresponding Google Maps Place IDs. - **Parameters**: - `lat` (query, required): Latitude coordinate (-90 to 90). [example: `40.722341`] - `lng` (query, required): Longitude coordinate (-180 to 180). [example: `-74.001298`] - `language` (query, optional): ISO 639-1 language code (default 'en'). [example: `en`] ```bash curl "https://api.googlemapsapi.io/v1/geocode/reverse?lat=40.722341&lng=-74.001298" \ -H "x-api-key: gm_live_your_api_key" ``` ```python import requests res = requests.get( "https://api.googlemapsapi.io/v1/geocode/reverse?lat=40.722341&lng=-74.001298", headers={"x-api-key": "gm_live_your_api_key"}, timeout=30, ) print(res.json()) ``` ## 4. Engineering Guides & Architecture Blueprints ### How to Scrape Google Maps Local Business Leads with Python & Node.js (2026 Guide) - **URL**: https://googlemapsapi.io/guides/scrape-google-maps-python-nodejs - **Summary**: Production engineering guide to extracting Google Maps business leads, phone numbers, coordinates, and opening hours at scale using bounding-box grid pagination in Python and Node.js. - **Key Takeaways**: - Official Google Places Text Search caps results at 60 places per query (3 pages of 20) and bills $32.00 per 1,000 requests. - To capture 100% of businesses across a dense metro area (e.g., all 1,800 restaurants in Manhattan), subdivide the city into a 0.02° × 0.02° latitude/longitude grid and query GET /v1/places/nearby. - Deduplicate overlapping viewport pins using the canonical place_id (ChIJ...) or numeric cid returned on every record. - Empty grid cells (parks, water, residential blocks) return 0 records and cost 0 Credits. ### How to Extract Verified Business Emails & Social Profiles from Google Maps Leads - **URL**: https://googlemapsapi.io/guides/extract-business-emails-from-google-maps - **Summary**: Turn Google Maps business listings into verified B2B outbound leads with emails, E.164 phones, LinkedIn, and Instagram handles using /v1/places/search + /v1/leads/enrich. - **Key Takeaways**: - Step 1: Query GET /v1/places/search to collect target businesses along with their normalized root domain (e.g., felixroastingco.com) and E.164 phone number. - Step 2: Pass each unique business domain to GET /v1/leads/enrich?domain=... to crawl the website's homepage, /contact, and /about pages in real time. - Our enrichment engine extracts general, sales, and founder emails plus LinkedIn, Instagram, Facebook, X/Twitter, YouTube, and TikTok links. - If a business website has no discoverable email or social link, 0 Credits are charged. ### How to Scrape Google Maps Reviews for Sentiment Analysis & Reputation Monitoring - **URL**: https://googlemapsapi.io/guides/google-maps-reviews-sentiment-api-guide - **Summary**: Extract hundreds of verified Google Maps customer reviews per business sorted by newest or lowest rating at $0.08–$0.20 per 1,000 reviews. - **Key Takeaways**: - Official Google Places Details hard-caps the reviews[] array at 5 items and provides no pagination or sort order. - GET /v1/places/reviews supports sort=newest, sort=lowest_rating, sort=highest_rating, and sort=most_relevant, plus keyword filtering via query=... - Each review record includes review_id, rating (1–5), review_text, published_at, author Local Guide status, owner_response, and attached photo URLs. - Pricing is just 2 Credits per returned review ($0.20 per 1,000 reviews base, or $0.08 per 1,000 on Business). ### Migrating from Official Google Places API: Cut Your Bill by 95% with Zero Schema Lock-In - **URL**: https://googlemapsapi.io/guides/migrate-from-google-places-api-save-90-percent - **Summary**: Step-by-step migration guide from Google Cloud Places API ($32/1K calls) to GoogleMapsAPI.io ($0.20–$0.50/1K places) using drop-in compatibility endpoints or native /v1/places/* routes. - **Key Takeaways**: - Google Cloud Places API charges $32.00 per 1,000 Text Search Pro calls when you request phone numbers, websites, opening hours, or ratings. - GoogleMapsAPI.io includes phone, website, opening hours, rating, review count, and coordinates in every search record for $0.20–$0.50 per 1,000 places. - Use our drop-in /maps/api/place/textsearch/json and /maps/api/place/details/json compatibility aliases for a 1-line base URL migration. - Store and index returned business records in your own database or CRM without 30-day cache eviction rules. ## 5. Competitor Benchmarks ### GoogleMapsAPI.io vs Google Places API (developers.google.com/maps) - **URL**: https://googlemapsapi.io/compare/google-places-api-alternative - **Headline**: $0.20 vs $32.00 per 1,000 places (up to 98% savings). - **Summary**: Official Google Places API charges $32.00 per 1,000 Text Search Pro requests (plus $3/1K Contact Data and $5/1K Atmosphere Data SKU add-ons), hard-caps results at 60 places per query and 5 reviews per business, and forbids caching data for CRM or lead generation. GoogleMapsAPI.io delivers full business profiles, phone numbers, websites, opening hours, unlimited customer reviews, and website B2B email enrichment starting at $0.20–$0.50 per 1,000 places. ### GoogleMapsAPI.io vs Outscraper (outscraper.com) - **URL**: https://googlemapsapi.io/compare/outscraper-alternative - **Headline**: $0.20 vs $2.85 per 1,000 places (with instant synchronous JSON). - **Summary**: Outscraper relies on asynchronous background batch tasks that frequently take 30–180 seconds to queue and require webhook or status-polling loops—making it unusable for interactive user interfaces, live AI agents, or real-time CRM enrichment. GoogleMapsAPI.io returns synchronous JSON in 25ms (warm cache) to 1.8s (live SERP) at $0.20–$0.50 per 1,000 places. ### GoogleMapsAPI.io vs SerpApi (serpapi.com) - **URL**: https://googlemapsapi.io/compare/serpapi-google-maps-alternative - **Headline**: $29/mo vs $75/mo entry plan ($0.20–$0.50/1K places vs $15/1K calls). - **Summary**: SerpApi is a general-purpose search engine scraper that charges $75/month for just 5,000 searches ($15.00 per 1,000 requests), bills per request even when only a handful of places are returned, and lacks website email enrichment. GoogleMapsAPI.io is purpose-built for Google Maps intelligence—delivering up to 100 places per call at $0.20–$0.50 per 1,000 places, plus non-expiring Pay-As-You-Go packs from $10. ### GoogleMapsAPI.io vs Apify Google Maps Scraper (apify.com) - **URL**: https://googlemapsapi.io/compare/apify-google-maps-scraper-alternative - **Headline**: 25ms–1.8s vs 30s–90s response time (zero container spin-up or RAM billing). - **Summary**: Running Apify's Google Maps Scraper (compass/crawler-google-places) spins up a heavy headless Chromium container on every run—taking 30 to 90 seconds to boot and charging you for both Pay-Per-Result fees AND Actor Compute Units (RAM/CPU time). GoogleMapsAPI.io is an always-warm, low-latency REST API that returns structured Google Maps places, reviews, and enriched emails in milliseconds to 1.8 seconds. ### GoogleMapsAPI.io vs Bright Data (brightdata.com) - **URL**: https://googlemapsapi.io/compare/brightdata-google-maps-alternative - **Headline**: $10 PAYG vs $500/mo minimum commitment ($0.20/1K places vs $1.50–$3.00/1K). - **Summary**: Bright Data's Web Scraper IDE and SERP API target enterprise procurement teams with $500/month minimum commitments, complex bandwidth + request pricing, KYC compliance hurdles, and asynchronous snapshot delivery. GoogleMapsAPI.io gives developers instant self-serve access with 2,000 free credits on signup, $10 non-expiring PAYG packs, and sub-2-second synchronous JSON. ## 6. Frequently Asked Questions ### How does the $1 = 10,000 Credits pricing model work? GoogleMapsAPI.io uses a transparent record-based credit system where $1.00 = 10,000 Credits. Place search endpoints (/v1/places/search and /v1/places/nearby) cost 5 Credits per returned business record ($0.50 per 1,000 places base, or $0.20 per 1,000 places on the Business plan). Reviews and photos cost 2 Credits per record ($0.20 per 1,000 base, $0.08 per 1,000 on Business). Place details and website lead enrichment cost 20 Credits ($0.002) per profile. If a search returns 0 matching places or lead enrichment finds 0 emails/social links, you pay 0 Credits. ### How does GoogleMapsAPI.io compare to the official Google Places API ($17–$40 / 1,000 calls)? Official Google Places API charges $32.00 per 1,000 Text Search Pro requests plus Contact ($3/1K) and Atmosphere ($5/1K) SKU surcharges, restricts each query to a maximum of 60 results (3 pages of 20), caps reviews at 5 per place, and prohibits caching or storing data for more than 30 days. GoogleMapsAPI.io starts at $0.20–$0.50 per 1,000 places (up to 98% cheaper), includes phone numbers, websites, opening hours, and coordinates in every search response, supports deep review pagination, and includes built-in website email and social link enrichment. ### Where do the business emails and social media profiles come from? Google Maps listings include the business's official website domain, phone number, and address, but rarely display an email address directly on the map card. When you call GET /v1/leads/enrich?domain=example.com (or inspect contacts_enrichment on /v1/places/details), our SSRF-hardened enrichment engine crawls the business's official homepage, /contact, and /about pages in real time to extract verified email addresses and social links across LinkedIn, Instagram, Facebook, X/Twitter, YouTube, and TikTok. If 0 emails and 0 social links are found, 0 Credits are deducted. ### What is the response latency for cached vs. live real-time Google Maps queries? Queries hitting our warm PostgreSQL 16 + GiST spatial index (covering 200M+ business profiles across major US, UK, EU, and global metros) respond in 15–50 ms. Cold long-tail queries or requests with ?fresh=true execute a live pass-through to our upstream Google Maps SERP cluster in 1.2–2.8 seconds and automatically write-through to the local index. ### Can I migrate from Google Places API or Outscraper without rewriting my application? Yes. In addition to our clean /v1/places/* endpoints, our gateway supports drop-in compatibility routes for Google Places API (/maps/api/place/textsearch/json, /maps/api/place/details/json, /maps/api/place/nearbysearch/json, /maps/api/place/autocomplete/json) so you can switch your base URL to https://api.googlemapsapi.io and authenticate via x-api-key or key=gm_live_.... ### Am I charged when a search returns 0 results or when an API request fails? Never. Searches that return 0 matching places cost 0 Credits. Website lead enrichment calls that discover 0 emails and 0 social links cost 0 Credits. Invalid parameters (HTTP 400), rate-limited requests (HTTP 429), and gateway errors (HTTP 5xx) also cost 0 Credits. ### Should I choose a Monthly Subscription or a Pay-As-You-Go (PAYG) Credit Pack? Monthly subscriptions ($29 Starter / 350k credits, $79 Growth / 1.1M credits, $199 Pro / 3.5M credits, $499 Business / 12.5M credits) include +20% to +150% bonus credits, bringing your effective cost down to $0.20 per 1,000 places. PAYG Credit Packs ($10 / 100k, $50 / 550k, $100 / 1.2M, $500 / 7.5M) have zero recurring charges and your purchased credits never expire. ### What are the RPM rate limits and concurrency allowances? Free Trial accounts include 2,000 Credits and 60 RPM (2 RPS). Upgrading to any paid plan or PAYG pack unlocks high-throughput production concurrency: 300 RPM (Starter), 600 RPM (Growth), 1,200 RPM (Pro), and 3,000 RPM / 50 RPS (Business). ### What payment methods are accepted? You can top up or subscribe immediately using Cryptocurrency (USDT, USDC, BTC, ETH, SOL, BNB across Solana, Tron, Polygon, Arbitrum, BSC, and Ethereum) via NOWPayments with 0% gateway fee and an automatic +5% Bonus Credits reward. You can also configure your company legal name, billing address, and VAT / Tax ID in your dashboard for compliant billing records. ### What is your refund policy? Payments made within the last 14 days are eligible for a pro-rated refund of unused purchased credits. Promotional signup credits have no cash value.