How to Capture a Google Maps Screenshot Programmatically
Choose the Google Maps Static API for parameterized images or Playwright for browser-rendered captures, with code, legal constraints, and a hosted option.

Direct answer: use the Google Maps Static API when you need a repeatable map image generated from coordinates, zoom, markers, or paths. Use Playwright when you need pixels from a browser-rendered Google Maps page, including its current UI state. These workflows produce different outputs and have different storage, attribution, and terms requirements.
Before saving or publishing anything, review the terms for the specific Google Maps service you use. Google says Static API images should be served directly from the API rather than stored and served as copies from your own website, and Google restricts tile scraping, some tile modifications, and stitching. Browser automation can technically create a file, but it does not grant rights to redistribute map content.
1. Choose the capture method
| Requirement | Use | What you receive |
|---|---|---|
| Map from parameters such as center, zoom, markers, or paths | Maps Static API | An API-produced image |
| Screenshot of maps.google.com or an embedded map as rendered in a browser | Playwright | Pixels from a browser page or element |
| Owned application with a Google map | Playwright in a controlled context | A page or map-element screenshot, with attribution preserved |
The Static API is the more direct option for a stable, parameter-driven image. It is not a screenshot of surrounding controls, search boxes, or other browser UI. Playwright is appropriate when the rendered state itself matters, but rendering can vary with browser version, operating system, viewport, localization, consent prompts, and headless mode.

2. Generate a map image with the Google Maps Static API
Google’s setup flow requires a Google Cloud project with billing, the Maps Static API enabled, and authentication credentials. Keep the key on your server or in a secret manager; do not expose unrestricted credentials in client-side code.
cURL
curl -G "https://maps.googleapis.com/maps/api/staticmap" \
--data-urlencode "center=40.7484,-73.9857" \
--data "zoom=13" \
--data "size=800x500" \
--data "maptype=roadmap" \
--data-urlencode "markers=color:red|40.7484,-73.9857" \
--data-urlencode "key=$GOOGLE_MAPS_API_KEY" \
-o map.png
Python
import os
import requests
params = {
"center": "40.7484,-73.9857",
"zoom": 13,
"size": "800x500",
"maptype": "roadmap",
"markers": "color:red|40.7484,-73.9857",
"key": os.environ["GOOGLE_MAPS_API_KEY"],
}
response = requests.get(
"https://maps.googleapis.com/maps/api/staticmap",
params=params,
timeout=30,
)
response.raise_for_status()
content_type = response.headers.get("content-type", "")
if not content_type.startswith("image/"):
raise RuntimeError(f"Expected an image, got {content_type}: {response.text[:200]}")
with open("map.png", "wb") as output:
output.write(response.content)
Node.js
import { writeFile } from "node:fs/promises";
const params = new URLSearchParams({
center: "40.7484,-73.9857",
zoom: "13",
size: "800x500",
maptype: "roadmap",
markers: "color:red|40.7484,-73.9857",
key: process.env.GOOGLE_MAPS_API_KEY,
});
const response = await fetch(`https://maps.googleapis.com/maps/api/staticmap?${params}`);
if (!response.ok) throw new Error(`Maps API returned ${response.status}`);
const type = response.headers.get("content-type") || "";
if (!type.startsWith("image/")) throw new Error(`Expected image, got ${type}`);
await writeFile("map.png", Buffer.from(await response.arrayBuffer()));
Useful Static API parameters
centerandzoomdefine the map focus and scale.sizecontrols the requested image dimensions; check current limits in Google’s documentation.maptypeselects the map style supported by the API.markersadds one or more locations.pathdraws routes or boundaries using encoded or literal coordinates.- URL-encode every parameter, especially pipes, commas, spaces, and encoded polylines.
Do not assume that an HTTP 200 response is an image. Validate the content type and inspect the response body. An API error can otherwise be written to a file named map.png.
3. Capture a rendered Google Maps page with Playwright
Playwright launches a real browser, navigates to a page, waits for the desired state, and writes a screenshot. Use a controlled viewport and browser version when repeatability matters.
Node.js
import { chromium } from "playwright";
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage({
viewport: { width: 1440, height: 900 },
deviceScaleFactor: 1,
});
await page.goto("https://www.google.com/maps/@40.7484,-73.9857,13z", {
waitUntil: "domcontentloaded",
timeout: 60_000,
});
// Add a short, explicit wait for map tiles and controls to settle.
await page.waitForTimeout(3_000);
await page.screenshot({ path: "google-maps.png", fullPage: false, type: "png" });
await browser.close();
Python
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page(viewport={"width": 1440, "height": 900}, device_scale_factor=1)
page.goto(
"https://www.google.com/maps/@40.7484,-73.9857,13z",
wait_until="domcontentloaded",
timeout=60_000,
)
page.wait_for_timeout(3_000)
page.screenshot(path="google-maps.png", full_page=False, type="png")
browser.close()
Install the runtime before running these examples:
npm install playwright
npx playwright install chromium
# Python
pip install playwright
playwright install chromium
Full-page, element, and PDF captures
// Full page (useful for an owned application, not usually maps.google.com)
await page.screenshot({ path: "full.png", fullPage: true });
// Capture a specific element in an owned page
await page.locator("#map").screenshot({ path: "map-element.png" });
// PDF output is Chromium-specific
await page.pdf({ path: "map-page.pdf", format: "A4", printBackground: true });
Selectors for Google’s public UI can change. For an application you own, prefer a stable map container selector. Preserve all required Google and third-party attribution: Google’s Maps JavaScript API policy requires attribution to remain clear, legible, unmodified, and appropriately positioned.
4. Wait for the map to be ready
A fixed delay is simple but imperfect. For an owned application, wait on an application-level selector or readiness signal, then allow a short settling period for tiles and labels. Avoid waiting forever on a network-idle condition: maps can maintain long-lived requests.
await page.goto(APP_URL, { waitUntil: "domcontentloaded" });
await page.locator("#map-ready").waitFor({ state: "visible", timeout: 30_000 });
await page.waitForTimeout(500);
await page.locator("#map").screenshot({ path: "map.png" });
5. Legal, attribution, and storage constraints
- Google’s Maps Platform FAQ states: “You may not store and serve copies of images generated using the Maps Static API from your website.” Follow the current FAQ’s guidance for serving Static API images directly.
- Do not bulk-download map tiles through undocumented mechanisms.
- Do not assume that stitching multiple Static API images, modifying tiles server-side, or creating derivative datasets is permitted.
- Maps JavaScript API policies generally restrict pre-fetching, caching, and storage of content; place IDs are treated differently under those policies.
- Keep attribution visible and unmodified. Check the service-specific policy and the current terms for your region, including EEA terms where applicable.
Technical success is not permission to retain or redistribute the result. Make the storage and publication decision after identifying whether the output came from Static API, Maps JavaScript, or a public Google Maps page.
6. Reliability and performance
- Static API: construct deterministic URLs, validate image responses, set a request timeout, and record non-image error bodies for diagnosis. Keep credentials server-side.
- Playwright: reuse a browser process for batches, create isolated contexts per job, fix viewport and device scale, and pin browser versions in CI.
- Readiness: prefer a known selector or application event over a long arbitrary sleep. Retry transient navigation failures with a bounded backoff.
- Concurrency: limit parallel browser pages to the CPU and memory available. More pages can increase failures and produce incomplete renders.
- Output: PNG preserves sharp labels; JPEG is smaller for photographic content. Choose the format and dimensions required by the consumer.
- Cost: the dossier provides no reliable speed or price comparison between Static API and browser automation. Check Google’s current pricing and quotas for your project rather than assuming one workflow is cheaper.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Image file contains JSON or text | Invalid key, quota error, or malformed parameter | Check HTTP status and content type before writing; inspect the response body. |
| “This page can’t load Google Maps correctly” | Billing, API enablement, referrer restrictions, or credential problem | Verify the Cloud project, billing account, enabled API, and key restrictions. |
| Blank or partially drawn browser screenshot | Captured before tiles or the app finished rendering | Wait for an owned readiness selector, then allow a short settling delay. |
| Playwright times out on navigation | Network latency, consent prompt, redirect, or blocked resource | Increase the bounded timeout, log the final URL, and handle the page state explicitly. |
| Screenshot differs between machines | Different browser, fonts, viewport, locale, timezone, or device scale | Pin the browser/runtime and set viewport, locale, timezone, and scale. |
| Map attribution is missing or clipped | Element crop or CSS modification removed required attribution | Capture a region that includes attribution and do not alter it. |
| Markers or paths are misplaced | Latitude/longitude order or URL encoding error | Use latitude,longitude consistently and URL-encode pipes and polyline data. |
8. Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. It can capture a rendered Google Maps URL with one request, while handling the browser setup for you. See the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://www.google.com/maps/@40.7484,-73.9857,13z -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://www.google.com/maps/@40.7484,-73.9857,13z"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://www.google.com/maps/@40.7484,-73.9857,13z' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Create a free ScreenshotNeo account.
9. FAQ
Can I capture the Google Maps UI and controls?
Yes, Playwright can capture the rendered browser viewport, subject to the page loading and the applicable Google terms. The Static API returns a map image, not the surrounding website UI.
Should I use a screenshot or the Static API for a recurring report?
Use the Static API when the report needs a parameterized map image. Use browser capture when the exact rendered state of an owned page is part of the report.
Can I cache the result?
Do not assume caching is allowed. Static API and Maps JavaScript policies have service-specific storage restrictions; consult the current documentation and terms before retaining output.
Why is my automated map different from the one I see manually?
Browser version, viewport, device scale, locale, consent state, network timing, and page changes can all affect rendering. Control those variables and wait for a defined ready state.


