{"_id":"gmaps-place-reader","_rev":"5-417e34b5c53f345816860bb9e213820f","name":"gmaps-place-reader","dist-tags":{"latest":"0.5.0"},"versions":{"0.1.0":{"name":"gmaps-place-reader","version":"0.1.0","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews"],"author":{"name":"Alper Samur"},"license":"MIT","_id":"gmaps-place-reader@0.1.0","maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"bin":{"gmaps-scan":"bin/scan.js","gmaps-login":"bin/login.js","gmaps-place":"bin/place.js"},"dist":{"shasum":"2aad1bb7b7caeadfbbc83fb83c5d7391564bc400","tarball":"https://registry.npmjs.org/gmaps-place-reader/-/gmaps-place-reader-0.1.0.tgz","fileCount":10,"integrity":"sha512-+Dd1KveauMgDiQNOr21XQb2v1LIxuh8Z08FBTDy31+qnBg697AfWkbXow7xi0/UiDsUy/dPumqNJ4+y+G6nsmQ==","signatures":[{"sig":"MEQCIEIUar53yoHj2VkTNMulDUA5OXkRoy/8se+fPHR7lcU7AiAhebC23RLBT7kfS6cGjVqSlxkzqhv2gie5mYCYXbFCZQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":86001},"main":"./src/maps.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/maps.js","./media":"./src/media.js","./cookies":"./src/cookies.js","./details":"./src/details.js","./package.json":"./package.json"},"gitHead":"a66f1330c45f55ecfd6df53f4116ec54320cc796","scripts":{"scan":"node bin/scan.js","test":"node --test","login":"node bin/login.js"},"_npmUser":{"name":"alpersamur3","email":"alpersamur0705@gmail.com"},"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"_npmVersion":"10.9.2","description":"Read Google Maps places with a real browser: search results, business details, the full menu photo album (with photo dates), menu items and photos — no Places API key.","directories":{},"_nodeVersion":"22.17.0","dependencies":{"puppeteer-core":"^24.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gmaps-place-reader_0.1.0_1790623029790_0.6347329338296035","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"gmaps-place-reader","version":"0.3.0","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews"],"author":{"name":"Alper Samur"},"license":"MIT","_id":"gmaps-place-reader@0.3.0","maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"bin":{"gmaps-scan":"bin/scan.js","gmaps-view":"bin/view.js","gmaps-place":"bin/place.js"},"dist":{"shasum":"2c039b110d4dd1cc57e4ad52001da9e71f8765fa","tarball":"https://registry.npmjs.org/gmaps-place-reader/-/gmaps-place-reader-0.3.0.tgz","fileCount":10,"integrity":"sha512-QOpfBXlKTyhD3b503Qbg2ruolSahgy0S5Ti9Ub5fP5/pS0Oj0wx7bZvUtsEEBcLdcKS3WN6sJs2AeildRvxH3g==","signatures":[{"sig":"MEQCIBHHOT+nQa4CzjLPnEkm4Q2Oc03pN5q/qc8BI4PnbQMMAiBdo6vSPoRDeYVHOYT6k+65Aq2WkXS2ymZ2cpGBGhCL2g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIEIuSU5db/fjVcsfMr5wImNp9x88hCW6aS2v7K2X6R1KAiAPuTyJnXdniTT4n1szEogZfLtIgexdsPrcc+VnwKdzww==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":146919},"main":"./src/maps.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/maps.js","./media":"./src/media.js","./details":"./src/details.js","./reviews":"./src/reviews.js","./package.json":"./package.json"},"gitHead":"2d0e2822e89cf3355095f9dac58d08c8ba08b829","scripts":{"scan":"node bin/scan.js","test":"node --test","view":"node bin/view.js"},"_npmUser":{"name":"alpersamur3","email":"alpersamur0705@gmail.com"},"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"_npmVersion":"10.9.2","description":"Read Google Maps places by URL: business details, menu items and photos, galleries, and dated reviews with Puppeteer.","directories":{},"_nodeVersion":"22.17.0","dependencies":{"puppeteer-core":"^24.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gmaps-place-reader_0.3.0_1791209995333_0.6194384922415939","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"gmaps-place-reader","version":"0.3.1","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews"],"author":{"name":"Alper Samur"},"license":"MIT","_id":"gmaps-place-reader@0.3.1","maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"bin":{"gmaps-scan":"bin/scan.js","gmaps-view":"bin/view.js","gmaps-place":"bin/place.js"},"dist":{"shasum":"6f3d3bcfa330c3dc38f2f8eef45a740783ddc1b8","tarball":"https://registry.npmjs.org/gmaps-place-reader/-/gmaps-place-reader-0.3.1.tgz","fileCount":10,"integrity":"sha512-VK/l1tQugyn1KdqPTLFaA6rL4do2NxpV+3oG+KwBESMigC5J058c4J8HsbTKhd+9KtuI0xPiVZ+Gtoncx7Tmqw==","signatures":[{"sig":"MEUCIQCDN7UnqJxT1eOpsVb6n0mrGHmcPiTYTD0zlwRyHhT2wQIgJAAdaxMsHbAP4enxcYtQcvVPXdERUM3k9ntURlaypmY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIExF2TpMtDoBX9dw0IJaYgd3mbSPOXaybADOyjUlS4rVAiEAzXyu4mpLo1mMJYgaqrbGqf3XtIAA8ehMAsw1mPB5hYA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":147467},"main":"./src/maps.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/maps.js","./media":"./src/media.js","./details":"./src/details.js","./reviews":"./src/reviews.js","./package.json":"./package.json"},"gitHead":"98fbf21b639de4bcf41ab958153b7e5ee7c3b153","scripts":{"scan":"node bin/scan.js","test":"node --test","view":"node bin/view.js"},"_npmUser":{"name":"alpersamur3","email":"alpersamur0705@gmail.com"},"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"_npmVersion":"10.9.2","description":"Read Google Maps places by URL: business details, menu items and photos, galleries, and dated reviews with Puppeteer.","directories":{},"_nodeVersion":"22.17.0","dependencies":{"puppeteer-core":"^24.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gmaps-place-reader_0.3.1_1791374813345_0.7594959565114805","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"gmaps-place-reader","version":"0.4.0","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews","mcp","mcp-server","ai-agents"],"author":{"name":"Alper Samur"},"license":"MIT","_id":"gmaps-place-reader@0.4.0","maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"bin":{"gmaps-mcp":"bin/mcp.js","gmaps-scan":"bin/scan.js","gmaps-view":"bin/view.js","gmaps-place":"bin/place.js"},"dist":{"shasum":"a7155356181b2fe712ecb15ab9f871bf3dd16547","tarball":"https://registry.npmjs.org/gmaps-place-reader/-/gmaps-place-reader-0.4.0.tgz","fileCount":12,"integrity":"sha512-DLE3vgoi2OWoruXQ95+081+QvHmKH6z534m++vIW80xR3s4ubHVr2PjXzqDqzRomo+WB7ak/pbyEAD9ihccZGw==","signatures":[{"sig":"MEYCIQDkvLkhwMLY7LkuuG9ILVifrLPRfYoWQWrYKN0QKEgVqgIhAJhNO+izX6KPXpG/NADQL6wT4aSVgxq4XXGpz6ahChzY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDRipkS4sqgtfr5ER2Z+SlmGJzJ1dPshLAUPfu/iNzGVAIhAP+2LsgTKcOlDSY/4C+i3pSUjbLV9QK9J3UkbdDS2r1Z","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":170246},"main":"./src/maps.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/maps.js","./mcp":"./src/mcp.js","./media":"./src/media.js","./details":"./src/details.js","./reviews":"./src/reviews.js","./package.json":"./package.json"},"gitHead":"0d53bf021da2543a602bc7bcde8ea001878786f5","scripts":{"mcp":"node bin/mcp.js","scan":"node bin/scan.js","test":"node --test","view":"node bin/view.js"},"_npmUser":{"name":"alpersamur3","email":"alpersamur0705@gmail.com"},"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"_npmVersion":"10.9.2","description":"Read Google Maps places by URL: business details, menu items and photos, galleries, and dated reviews with Puppeteer. Includes an MCP server for AI agents.","directories":{},"_nodeVersion":"22.17.0","dependencies":{"puppeteer-core":"^24.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gmaps-place-reader_0.4.0_1791375963142_0.8913130066187411","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"_id":"gmaps-place-reader@0.5.0","bin":{"gmaps-mcp":"bin/mcp.js","gmaps-scan":"bin/scan.js","gmaps-view":"bin/view.js","gmaps-login":"bin/login.js","gmaps-place":"bin/place.js"},"bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"dist":{"shasum":"b11dcd669e18b02f289213983139a07cd4f277c8","tarball":"https://registry.npmjs.org/gmaps-place-reader/-/gmaps-place-reader-0.5.0.tgz","fileCount":14,"integrity":"sha512-MwELeEO61+VLQD0VEElFqU3zQNDpQ3WQlMDJ0BfXW3KNnA06bgMFJiSKpBCNSEPQrGzXmnCrqX09D1klNm8ohg==","signatures":[{"sig":"MEYCIQCxKzErwssV+BAqOOZXKdcLzHvcGPI5eTaFPir00CnAxAIhAJNOZMbFTNNnUdg0ebWeXC5XNt6TBmuYxBBmWhJX5Vi8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDP38Y8VtUD0ITLN3GRWHSSFdqzLYYg4d1FrPNfkfHS4AiEAqinYJjQSmBKFbkhY9MdwzDKEl3WyrmGxggPtyqf4Vrg="}],"unpackedSize":187621},"main":"./src/maps.js","name":"gmaps-place-reader","type":"module","author":{"name":"Alper Samur"},"engines":{"node":">=20"},"exports":{".":"./src/maps.js","./mcp":"./src/mcp.js","./login":"./src/login.js","./media":"./src/media.js","./details":"./src/details.js","./reviews":"./src/reviews.js","./package.json":"./package.json"},"gitHead":"fbe96a19fbd9151cdc19b1c0cd5481043f29fd7a","license":"MIT","scripts":{"mcp":"node bin/mcp.js","scan":"node bin/scan.js","test":"node --test","view":"node bin/view.js","login":"node bin/login.js"},"version":"0.5.0","_npmUser":{"name":"alpersamur3","email":"alpersamur0705@gmail.com"},"homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews","mcp","mcp-server","ai-agents"],"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"_npmVersion":"10.9.8","description":"Read Google Maps places by URL: business details, menu items and photos, galleries, and dated reviews with Puppeteer. Optional Google sign-in for the full view. Includes an MCP server for AI agents.","directories":{},"maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"_nodeVersion":"22.23.2","dependencies":{"puppeteer-core":"^24.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gmaps-place-reader_0.5.0_1793552767012_0.4869117624454262"}}},"time":{"created":"2026-09-28T19:17:09.582Z","modified":"2026-11-01T17:06:07.257Z","0.1.0":"2026-09-28T19:17:09.927Z","0.3.0":"2026-10-05T14:19:55.434Z","0.3.1":"2026-10-07T12:06:53.431Z","0.4.0":"2026-10-07T12:26:03.227Z","0.5.0":"2026-11-01T17:06:07.107Z"},"bugs":{"url":"https://github.com/alpersamur3/gmaps-place-reader/issues"},"author":{"name":"Alper Samur"},"license":"MIT","homepage":"https://github.com/alpersamur3/gmaps-place-reader#readme","keywords":["google-maps","maps","places","restaurant","menu","scraper","puppeteer","headless-chrome","photos","reviews","mcp","mcp-server","ai-agents"],"repository":{"url":"git+https://github.com/alpersamur3/gmaps-place-reader.git","type":"git"},"description":"Read Google Maps places by URL: business details, menu items and photos, galleries, and dated reviews with Puppeteer. Optional Google sign-in for the full view. Includes an MCP server for AI agents.","maintainers":[{"name":"alpersamur3","email":"alpersamur0705@gmail.com"}],"readme":"<div align=\"center\">\r\n\r\n# gmaps-place-reader\r\n\r\n**Read Google Maps places with a real browser: business details, menu items and the complete dated menu album, and dated reviews. No Places API key; one Google sign-in (`gmaps-login`) for the full view. Includes an MCP server for AI agents.**\r\n\r\n[![npm version](https://img.shields.io/npm/v/gmaps-place-reader.svg)](https://www.npmjs.com/package/gmaps-place-reader)\r\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alpersamur3/gmaps-place-reader/blob/main/LICENSE)\r\n[![node](https://img.shields.io/node/v/gmaps-place-reader.svg)](https://nodejs.org)\r\n\r\n**[🇬🇧 English](#english)** &nbsp;·&nbsp; **[🇹🇷 Türkçe](#turkce)**\r\n\r\n[npm](https://www.npmjs.com/package/gmaps-place-reader) · [GitHub](https://github.com/alpersamur3/gmaps-place-reader) · [Issues](https://github.com/alpersamur3/gmaps-place-reader/issues)\r\n\r\n</div>\r\n\r\n---\r\n\r\n<details open>\r\n<summary><h2 id=\"english\">🇬🇧 English</h2></summary>\r\n\r\n### Contents\r\n\r\n[Features](#features) · [Install](#install) · [Quick start](#quick-start) · [Documentation](#documentation) · [API](#api) · [Command line](#command-line) · [MCP server](#mcp-server) · [Configuration](#configuration) · [Full view and signing in](#full-view-and-signing-in) · [Limitations](#limitations) · [Disclaimer](#disclaimer)\r\n\r\n### Features\r\n\r\n- **Search** Google Maps by keyword and location and collect up to 60 places per query (scrolling and de-duplication included).\r\n- **Business details:** name, address, phone, website, rating, review count, opening hours per day, business type, price level, coordinates, place id and CID.\r\n- **About content:** business description when Google provides one and categorized attributes such as access, service, atmosphere and payment options.\r\n- **The complete menu photo album.** The Menu strip on the overview only renders a few thumbnails even when it says \"Photo 1/12\", so the album is read in the full-screen photo viewer. Every photo comes with its full-size URL, **original dimensions** and **the month it was taken** (`taken_at`, e.g. `2026-01`), which lets you prefer the newest menu when older photos show outdated prices.\r\n- **Menu items and prices** from the Menu tab, by category.\r\n- **Full view with one sign-in.** Since late October 2026 Google shows anonymous browsers only a limited place page (no Menu tab, no menu items, usually no menu album). `gmaps-login` signs the reader's profile in once, in an ordinary Chrome window, also on a server without a screen (SSH tunnel + `chrome://inspect`); the headless reader then gets the full view, and every result says which view and account state it got (`view`, `account`). See [Signing in](docs/sign-in.md) and [Full view](docs/full-view.md).\r\n- **Detailed, dated reviews on request:** reviewer, rating (rating-only reviews included), full text, owner response, likes, attached photos, sub-ratings and other details (`Yiyecek: 5`, price per person …), edit and \"translated by Google\" markers. Each review gets its **exact posting date** (`date_iso`) read from the data Google sends to the page, checked against the \"2 months ago\" label; otherwise an approximate date (`date_estimate`) with its precision. Optional **newest-first** order (`reviewSort: 'newest'`); the list is paged to the end, so every review can be read.\r\n- **One-link lookup:** pass a Google Maps link to `readPlaceUrl` or `gmaps-place --url ...` — `maps.app.goo.gl` share links, links on any Google country domain (`google.com.tr`, …), `?cid=` links, and links copied while the Menu or Reviews tab was open.\r\n- **MCP server for AI agents** (`gmaps-mcp`): Claude Code, Claude Desktop and other MCP clients can search places, read details, menus and reviews, and look at photos, e.g. to read a menu page. See [MCP server](docs/mcp.md).\r\n- **General photos** from the place gallery; menu photos, avatars and size variants of the same image are removed.\r\n- **EU cookie consent** is handled by choosing **\"Reject all\"**; nothing is ever accepted.\r\n- **Honest results:** missing data is never reported as \"absent\". Statuses and warnings (`limited_view`, `consent_required`, `blocked`, `truncated`, …) tell you exactly what could not be read.\r\n- Plain ESM on top of [`puppeteer-core`](https://pptr.dev) and your own Chrome or Chromium. No API keys, no browser download.\r\n\r\n### Install\r\n\r\n```bash\r\nnpm install gmaps-place-reader\r\n```\r\n\r\nRequires **Node.js 20+** and an installed **Chrome or Chromium**. The package uses `puppeteer-core` and never downloads a browser. On Windows the default Chrome location is used automatically; on Linux and macOS set `MAPS_CHROME_PATH`:\r\n\r\n```bash\r\nexport MAPS_CHROME_PATH=/usr/bin/google-chrome   # or /usr/bin/chromium\r\n```\r\n\r\n### Quick start\r\n\r\n```js\r\nimport { launchBrowser, newMapsPage, searchPlaces, readPlace } from 'gmaps-place-reader';\r\n\r\n// A persistent profile, signed in once with gmaps-login, keeps Google's full view.\r\nconst browser = await launchBrowser({ userDataDir: '/absolute/path/gmaps-profile' });\r\ntry {\r\n  const page = await newMapsPage(browser);\r\n  const found = await searchPlaces(page, { location: 'Kadıköy, İstanbul', keyword: 'cafe', limit: 5 });\r\n\r\n  const place = await readPlace(page, found.places[0], { maxMenuImages: 20, maxImages: 12, includeReviews: true, maxReviews: 100 });\r\n  console.log(place.status, place.view, place.name, place.phone, place.rating, place.review_count);\r\n  console.log(place.reviews.reviews[0]?.date_iso, place.reviews.reviews[0]?.text);\r\n\r\n  // Newest menu photos first\r\n  const menu = [...place.menu.images].sort((a, b) => (b.taken_at || '').localeCompare(a.taken_at || ''));\r\n  for (const photo of menu) console.log(photo.taken_at, `${photo.width}x${photo.height}`, photo.url);\r\n} finally {\r\n  await browser.close();\r\n}\r\n```\r\n\r\n### Documentation\r\n\r\nDetailed documentation lives in [`docs/`](docs/README.md): [signing in for the full view](docs/sign-in.md) · [full view](docs/full-view.md) · [API reference](docs/api.md) · [data reference](docs/data.md) (every field) · [command line](docs/cli.md) · [MCP server](docs/mcp.md) · [statuses, warnings and troubleshooting](docs/troubleshooting.md).\r\n\r\n### API\r\n\r\n| Function | Returns |\r\n|---|---|\r\n| `launchBrowser(options?)` | A Puppeteer browser. Options: `executablePath`, `userDataDir` (persistent profile, recommended), `headless` (default `true`). |\r\n| `newMapsPage(browser)` | A page prepared for Maps (desktop user agent, Turkish UI). |\r\n| `searchPlaces(page, { location, keyword?, limit?, maxScrolls? })` | `{ status, places: [{ source_id, name, google_maps_url }], truncated }`. `limit` is capped at 60. |\r\n| `readPlace(page, place, { includeReviews?, maxReviews?, maxReviewScrolls?, reviewSort?, maxImages?, maxMenuImages?, maxScrolls?, includeMenu?, includePhotos?, recoverView?, onProgress? })` | Business details and About attributes, plus `menu`, `photos`, optional `reviews`, `view`, `warnings` and `data_quality`. Reviews default off; the limit defaults to 100 and can be raised to 10,000. `includeMenu` / `includePhotos` (default `true`) skip the menu or the gallery when `false`. `recoverView` (default `true`) repairs a limited view. |\r\n| `readPlaceUrl(browser, url, options?)` | Opens a Maps place URL, reads the same details, then closes its page. Accepts regular Maps links and `maps.app.goo.gl` share links. |\r\n| `readReviews(page, { reviewCount?, maxReviews?, maxScrolls?, sort?, onProgress? })` | Opens the Reviews tab, expands full review text and scrolls the list. Returns review records and explicit truncation/coverage fields. `maxScrolls` defaults to 25 and can be raised to 1,000. |\r\n| `readMenuPhotos(page, { overviewUrl, maxImages? })` | Only the menu album: `{ status: 'found' \\| 'empty' \\| 'unavailable', images: [{ url, width, height, taken_at, label }], truncated }`. |\r\n| `scan(browser, { location, keyword?, limit?, known?, maxImages?, maxMenuImages?, includeReviews?, maxReviews?, maxReviewScrolls? })` | Search and details in one call; optionally collects reviews and returns `{ status, items, skipped_known }` with normalized records. Places listed in `known` (`{ source: 'google_maps_browser', source_id }`) are skipped. |\r\n| `toObservation(place, detail)` | Flattens a `readPlace` result into one record (`schema_version: 'gmaps.place.v1'`) with `assets`, `menu_assets` and optional reviews. |\r\n\r\nHelpers: `normalizePlaceUrl(url)` (check a link before launching a browser), `fullImageUrl(url)` (large variant of a Google photo URL), `placeIdentity(url)`, `pageStatus(page)`, `passConsent(page)`, `parseRelativeAge(label)`, `estimateReviewDate(label)`, `checkView(browser, url?, { repair? })` (`{ view, renewed, account }`), `accountState(page)`; `signIn(options)` from `gmaps-place-reader/login` (the `gmaps-login` flow).\r\nSubpath exports: `gmaps-place-reader/media`, `/details`, `/reviews`, `/login`, `/mcp`.\r\n\r\nReview options: `includeReviews` (default `false`), `maxReviews` (100, up to 10,000), `maxReviewScrolls` (25, up to 1,000 — each step loads about 10 reviews), `reviewSort` (`relevant` · `newest` · `highest` · `lowest`). Review fields: `review_id`, `author`, `author_summary`, `rating`, `text`, `date_label`, `date_iso`, `date_estimate`, `date_precision` (`exact`, `day`, `week`, `month`, `year` …), `edited`, `edited_estimate` (approximate edit date of an edited review), `translated`, `photos`, `owner_response`, `likes`, `language`, `details` (the structured lines under a review: sub-ratings such as `{ name: 'Yiyecek', value: '5' }` and rows such as `{ name: 'Kişi başı fiyat', value: '₺400–600' }`). The `reviews` result also reports `sort_label` and `sort_applied`; when the requested order could not be chosen, `warnings` contains `REVIEW_SORT_NOT_APPLIED`.\r\n\r\nEvery result carries `view` (`full` · `limited` · `unknown`) and `account` (`signed_in` · `signed_out` · `unknown`). Every function, option and field: [docs/api.md](docs/api.md), [docs/data.md](docs/data.md).\r\n\r\n**Statuses:** `ok`, `incomplete` (some parts could not be read, see `warnings`), `limited_view`, `auth_required`, `consent_required`, `blocked`, `unavailable`. Common warnings: `MENU_PHOTOS_UNAVAILABLE` (menu items were read but the menu photo album could not be opened), `REVIEWS_UNAVAILABLE`, `REVIEW_SORT_NOT_APPLIED`, `LIMITED_VIEW`, and `…_LIMIT_OR_SCROLL_LIMIT` when your own limits stopped a list.\r\n\r\n### Command line\r\n\r\nThe commands write one JSON response to stdout (exit code `2` on failure, with an `error_code`). Set `MAPS_PROFILE_DIR` to a persistent profile and sign it in once with `gmaps-login`; no cookie files are used. All flags and fields: [docs/cli.md](docs/cli.md).\r\n\r\n```bash\r\n# Once: sign the profile in (a window opens; on a server add --port 9222 and use an SSH tunnel, see docs/sign-in.md)\r\nMAPS_PROFILE_DIR=/absolute/private/profile npx gmaps-login\r\n\r\n# One place by link: details, menu, photos and the 300 newest reviews with dates\r\nMAPS_PROFILE_DIR=/absolute/private/profile npx gmaps-place --url \"https://maps.app.goo.gl/your-place-link\" --reviews --sort newest --max-reviews 300 --max-review-scrolls 40\r\n\r\n# Search + details for several places (JSON request on stdin)\r\necho '{\"schema_version\":\"gmaps.scan.request.v1\",\"location\":\"Kadıköy, İstanbul\",\"keyword\":\"cafe\",\"limit\":5}' \\\r\n  | MAPS_PROFILE_DIR=/absolute/private/profile npx gmaps-scan\r\n\r\n# Check the profile (cron, hourly): exit code 0 = full view, 3 = limited; reports view and account\r\nMAPS_PROFILE_DIR=/absolute/private/profile npx gmaps-view --no-repair\r\n```\r\n\r\n### MCP server\r\n\r\n`gmaps-mcp` lets AI agents (Claude Code, Claude Desktop and other MCP clients) use the reader through four tools: `search`, `place`, `reviews` (without reviewer names) and `photos` (Google photos returned as images, e.g. to read a menu page). It runs locally with your Chrome; no API key. Sign the profile in once with `gmaps-login` for the full view.\r\n\r\n```bash\r\n# Claude Code\r\nclaude mcp add gmaps -e MAPS_PROFILE_DIR=/absolute/path/gmaps-profile -- npx -y -p gmaps-place-reader gmaps-mcp\r\n```\r\n\r\nClaude Desktop and other clients, every tool argument and the limits (`MAPS_MCP_MAX_READS`, `MAPS_MCP_MAX_PHOTOS`, `MAPS_MCP_PAUSE_MS`): [docs/mcp.md](docs/mcp.md).\r\n\r\n### Configuration\r\n\r\n| Environment variable | Option | Purpose |\r\n|---|---|---|\r\n| `MAPS_CHROME_PATH` | `executablePath` | Chrome or Chromium binary |\r\n| `MAPS_PROFILE_DIR` | `userDataDir` | Persistent, private browser profile (absolute path). **Recommended:** it keeps the session (`gmaps-login`) and the full view. |\r\n\r\nCommand-line flags and JSON request fields take priority over the environment. The MCP server adds its own limits ([MCP server](docs/mcp.md)).\r\n\r\n### Full view and signing in\r\n\r\nGoogle Maps shows a place page either as a **limited view** (no Menu tab, no menu items or prices, often no menu album, fewer details) or as the **full view**. Until October 2026 the browser's anonymous id cookie decided it (`__Secure-ENID` in the EU, `NID` elsewhere) and about half of all new profiles got the full view; **since late October 2026 every anonymous browser gets the limited view**, while a browser signed in to a Google account still gets the full view.\r\n\r\n- **Use a persistent profile** (`MAPS_PROFILE_DIR` / `userDataDir`). It keeps the session and the anonymous id.\r\n- **Sign in once with `gmaps-login`.** It opens an ordinary Chrome window on the profile; sign in, and the window closes when Maps opens. On a server without a screen it runs the window on a virtual display (`xvfb-run`) and you drive it from your computer through an SSH tunnel and `chrome://inspect`. Create the session on the machine that runs the reader: Chrome binds Google sessions to the device, and sessions copied from another computer are signed out within hours. Use a dedicated account.\r\n- **Run `gmaps-view --no-repair` hourly** (cron). It reports `\"view\"` and `\"account\"`, keeps the session fresh, and exits with `0` only for the full view. Without `--no-repair` it also repairs a limited *anonymous* view (reload, then a full-view id from up to six temporary profiles, which finds none since October 2026).\r\n- **No cookie files.** The reader never loads exported cookies; the session lives only in the profile folder.\r\n\r\nThe procedure, measurements and tips: [docs/sign-in.md](docs/sign-in.md) and [docs/full-view.md](docs/full-view.md).\r\n\r\nChrome or Chromium is needed in every case. Reading runs headless, so no desktop is required; on Linux run it as a normal user, not root. Keep the profile folder private.\r\n\r\n### Limitations\r\n\r\n- Reads the **Turkish** Google Maps interface: every Maps URL is opened with `hl=tr`, so the server locale and the browser language do not matter. English labels are recognized as well.\r\n- Google changes the Maps markup regularly, so selectors may need updates. When that happens you get `unavailable` or `incomplete` instead of wrong data.\r\n- Search radius is not an exact filter; Maps text search decides what is \"nearby\".\r\n- Exact review dates come from Google's own page data and are accepted only when they agree with the visible label; when they cannot be matched, `date_estimate` is derived from the label and `date_precision` says how coarse it is. For an edited review the label shows the edit age, while `date_iso` is the original posting date. Paging limits are reported through `truncated` and `coverage_complete`. Reading thousands of reviews takes minutes (about 10 per step).\r\n- Keep volumes small and pause between requests. CAPTCHAs and verification pages are never bypassed.\r\n\r\n### Disclaimer\r\n\r\n**Use at your own risk.** This project is not affiliated with or endorsed by Google. Automated access to Google Maps may conflict with the [Google Maps Terms of Service](https://www.google.com/help/terms_maps/). It is meant for personal and research use at low volumes. You are responsible for how you use this library and for complying with the applicable terms and laws. Photos, reviews and texts belong to their respective owners.\r\n\r\n### Development\r\n\r\n```bash\r\ngit clone https://github.com/alpersamur3/gmaps-place-reader.git\r\ncd gmaps-place-reader\r\nnpm install\r\nnpm test   # node --test, runs against local fixture pages; needs Chrome (MAPS_CHROME_PATH on Linux/macOS)\r\n```\r\n\r\nIssues and pull requests are welcome.\r\n\r\n### License\r\n\r\n[MIT](https://github.com/alpersamur3/gmaps-place-reader/blob/main/LICENSE) © Alper Samur\r\n\r\n</details>\r\n\r\n<details open>\r\n<summary><h2 id=\"turkce\">🇹🇷 Türkçe</h2></summary>\r\n\r\n### İçindekiler\r\n\r\n[Özellikler](#özellikler) · [Kurulum](#kurulum) · [Hızlı başlangıç](#hızlı-başlangıç) · [Dokümantasyon](#dokümantasyon) · [API](#api-1) · [Komut satırı](#komut-satırı) · [MCP sunucusu](#mcp-sunucusu) · [Yapılandırma](#yapılandırma) · [Tam görünüm ve oturum açma](#tam-görünüm-ve-oturum-açma) · [Sınırlar](#sınırlar) · [Sorumluluk reddi](#sorumluluk-reddi)\r\n\r\n### Özellikler\r\n\r\n- Google Maps'te anahtar kelime ve konumla **arama**; sorgu başına 60 işletmeye kadar (kaydırma ve tekilleştirme dahil).\r\n- **İşletme bilgileri:** ad, adres, telefon, web sitesi, puan, yorum sayısı, gün gün çalışma saatleri, işletme türü, fiyat seviyesi, koordinat, place id ve CID.\r\n- **Hakkında bilgileri:** Google veriyorsa işletme açıklaması; erişilebilirlik, hizmet, atmosfer ve ödeme gibi kategorilere ayrılmış özellikler.\r\n- **Menü albümünün tamamı.** Genel bakıştaki menü şeridi \"Fotoğraf 1/12\" yazsa da yalnız birkaç küçük resim gösterir; bu yüzden albüm tam ekran fotoğraf görüntüleyicisinden okunur. Her fotoğraf tam boy adresi, **orijinal boyutu** ve **çekildiği ay** (`taken_at`, ör. `2026-01`) ile gelir. Eski fotoğraflarda güncel olmayan fiyatlar varsa en yeni menüyü seçebilirsiniz.\r\n- Menü sekmesinden kategorileriyle **ürünler ve fiyatlar**.\r\n- **Tek oturum açmayla tam görünüm.** Ekim 2026 sonundan beri Google oturumsuz tarayıcılara yalnız sınırlı mekân sayfasını gösteriyor (Menü sekmesi yok, ürün yok, çoğu zaman menü albümü yok). `gmaps-login`, okuyucunun profilinde sıradan bir Chrome penceresinde bir kez oturum açmanızı sağlar; ekranı olmayan bir sunucuda da (SSH tüneli + `chrome://inspect`). Sonrasında headless okuyucu tam görünümü alır ve her sonuç hangi görünümü ve hesap durumunu aldığını söyler (`view`, `account`). Bkz. [Oturum açma](docs/tr/sign-in.md) ve [Tam görünüm](docs/tr/full-view.md).\r\n- **Ayrıntılı, tarihli yorumlar (isteğe bağlı):** yorumcu, yıldız (yalnız yıldız verilenler dahil), tam metin, işletme yanıtı, beğeni, yorum fotoğrafları, alt puanlar ve diğer detaylar (`Yiyecek: 5`, kişi başı fiyat …), düzenleme ve \"Google tarafından çevrildi\" işaretleri. Her yorumun **kesin yayın tarihi** (`date_iso`), Google'ın sayfaya gönderdiği veriden okunur ve ekrandaki \"2 ay önce\" etiketiyle doğrulanır; okunamazsa yaklaşık tarih (`date_estimate`) ve hassasiyeti verilir. İsteğe bağlı **en yeniden eskiye** sıralama (`reviewSort: 'newest'`); liste sonuna kadar sayfalandığı için bütün yorumlar okunabilir.\r\n- **Tek bağlantıyla sorgu:** Google Maps bağlantısını `readPlaceUrl` ya da `gmaps-place --url ...` komutuna verin — `maps.app.goo.gl` paylaşım bağlantıları, tüm Google ülke alan adları (`google.com.tr` …), `?cid=` bağlantıları ve Menü/Yorumlar sekmesi açıkken kopyalanan bağlantılar kabul edilir.\r\n- **Yapay zekâ ajanları için MCP sunucusu** (`gmaps-mcp`): Claude Code, Claude Desktop ve diğer MCP istemcileri mekân arayabilir; bilgileri, menüleri ve yorumları okuyabilir; fotoğraflara bakabilir, ör. menü sayfası okumak için. Bkz. [MCP sunucusu](docs/tr/mcp.md).\r\n- İşletme galerisinden **genel fotoğraflar**; menü fotoğrafları, profil resimleri ve aynı görselin farklı boyutları ayıklanır.\r\n- AB'deki **çerez onayı** sayfasında yalnız **\"Tümünü reddet\"** seçilir; hiçbir şey kabul edilmez.\r\n- **Dürüst sonuçlar:** okunamayan veri hiçbir zaman \"yok\" diye raporlanmaz. Durumlar ve uyarılar (`limited_view`, `consent_required`, `blocked`, `truncated`, …) neyin okunamadığını açıkça söyler.\r\n- [`puppeteer-core`](https://pptr.dev) ve kendi Chrome/Chromium'unuz üzerinde saf ESM. API anahtarı yok, tarayıcı indirmez.\r\n\r\n### Kurulum\r\n\r\n```bash\r\nnpm install gmaps-place-reader\r\n```\r\n\r\n**Node.js 20+** ve kurulu bir **Chrome ya da Chromium** gerekir. Paket `puppeteer-core` kullanır ve tarayıcı indirmez. Windows'ta varsayılan Chrome konumu kendiliğinden kullanılır; Linux ve macOS'ta `MAPS_CHROME_PATH` ayarlayın:\r\n\r\n```bash\r\nexport MAPS_CHROME_PATH=/usr/bin/google-chrome   # ya da /usr/bin/chromium\r\n```\r\n\r\n### Hızlı başlangıç\r\n\r\n```js\r\nimport { launchBrowser, newMapsPage, searchPlaces, readPlace } from 'gmaps-place-reader';\r\n\r\n// gmaps-login ile bir kez oturum açılmış kalıcı profil Google'ın tam görünümünü korur.\r\nconst browser = await launchBrowser({ userDataDir: '/mutlak/yol/gmaps-profile' });\r\ntry {\r\n  const page = await newMapsPage(browser);\r\n  const found = await searchPlaces(page, { location: 'Kadıköy, İstanbul', keyword: 'kafe', limit: 5 });\r\n\r\n  const place = await readPlace(page, found.places[0], { maxMenuImages: 20, maxImages: 12, includeReviews: true, maxReviews: 100 });\r\n  console.log(place.status, place.view, place.name, place.phone, place.rating, place.review_count);\r\n  console.log(place.reviews.reviews[0]?.date_iso, place.reviews.reviews[0]?.text);\r\n\r\n  // Önce en yeni menü fotoğrafları\r\n  const menu = [...place.menu.images].sort((a, b) => (b.taken_at || '').localeCompare(a.taken_at || ''));\r\n  for (const photo of menu) console.log(photo.taken_at, `${photo.width}x${photo.height}`, photo.url);\r\n} finally {\r\n  await browser.close();\r\n}\r\n```\r\n\r\n### Dokümantasyon\r\n\r\nAyrıntılı dokümantasyon [`docs/tr/`](docs/tr/README.md) altında: [tam görünüm için oturum açma](docs/tr/sign-in.md) · [tam görünüm](docs/tr/full-view.md) · [API başvurusu](docs/tr/api.md) · [veri başvurusu](docs/tr/data.md) (her alan) · [komut satırı](docs/tr/cli.md) · [MCP sunucusu](docs/tr/mcp.md) · [durumlar, uyarılar ve sorun giderme](docs/tr/troubleshooting.md).\r\n\r\n### API\r\n\r\n| Fonksiyon | Döndürdüğü |\r\n|---|---|\r\n| `launchBrowser(options?)` | Puppeteer tarayıcısı. Seçenekler: `executablePath`, `userDataDir` (kalıcı profil, önerilir), `headless` (varsayılan `true`). |\r\n| `newMapsPage(browser)` | Maps için hazırlanmış sayfa (masaüstü user agent, Türkçe arayüz). |\r\n| `searchPlaces(page, { location, keyword?, limit?, maxScrolls? })` | `{ status, places: [{ source_id, name, google_maps_url }], truncated }`. `limit` en fazla 60. |\r\n| `readPlace(page, place, { includeReviews?, maxReviews?, maxReviewScrolls?, reviewSort?, maxImages?, maxMenuImages?, maxScrolls?, includeMenu?, includePhotos?, recoverView?, onProgress? })` | İşletme ve Hakkında bilgileri ile `menu`, `photos`, isteğe bağlı `reviews`, `view`, `warnings` ve `data_quality`. Yorumlar varsayılan kapalıdır; sınır 100'dür ve 10.000'e kadar yükseltilebilir. `includeMenu` / `includePhotos` (varsayılan `true`) `false` olunca menüyü ya da galeriyi atlar. `recoverView` (varsayılan `true`) sınırlı görünümü onarır. |\r\n| `readPlaceUrl(browser, url, options?)` | Maps mekan bağlantısını açar, aynı bilgileri çeker ve sayfayı kapatır. Normal Maps ve `maps.app.goo.gl` bağlantıları kabul edilir. |\r\n| `readReviews(page, { reviewCount?, maxReviews?, maxScrolls?, sort?, onProgress? })` | Yorum sekmesini açar, tam metinleri genişletir ve listeyi kaydırır. Yorumları, kesilme ve tamlık durumuyla döndürür. `maxScrolls` varsayılan 25, üst sınır 1.000'dir. |\r\n| `readMenuPhotos(page, { overviewUrl, maxImages? })` | Yalnız menü albümü: `{ status: 'found' \\| 'empty' \\| 'unavailable', images: [{ url, width, height, taken_at, label }], truncated }`. |\r\n| `scan(browser, { location, keyword?, limit?, known?, maxImages?, maxMenuImages?, includeReviews?, maxReviews?, maxReviewScrolls? })` | Arama ve detay tek çağrıda; istenirse yorumları da çeker ve normalize kayıtlarla `{ status, items, skipped_known }` döner. `known` listesindeki işletmeler (`{ source: 'google_maps_browser', source_id }`) atlanır. |\r\n| `toObservation(place, detail)` | `readPlace` sonucunu `assets`, `menu_assets` ve istenirse yorumları içeren tek kayda (`schema_version: 'gmaps.place.v1'`) çevirir. |\r\n\r\nYardımcılar: `normalizePlaceUrl(url)` (tarayıcı açmadan bağlantıyı denetler), `fullImageUrl(url)` (Google fotoğraf adresinin büyük hali), `placeIdentity(url)`, `pageStatus(page)`, `passConsent(page)`, `parseRelativeAge(label)`, `estimateReviewDate(label)`, `checkView(browser, url?, { repair? })` (`{ view, renewed, account }`), `accountState(page)`; `gmaps-place-reader/login` altında `signIn(options)` (`gmaps-login` akışı).\r\nAlt yollar: `gmaps-place-reader/media`, `/details`, `/reviews`, `/login`, `/mcp`.\r\n\r\nYorum seçenekleri: `includeReviews` (varsayılan `false`), `maxReviews` (100, en fazla 10.000), `maxReviewScrolls` (25, en fazla 1.000 — her adım yaklaşık 10 yorum yükler), `reviewSort` (`relevant` · `newest` · `highest` · `lowest`). Yorum alanları: `review_id`, `author`, `author_summary`, `rating`, `text`, `date_label`, `date_iso`, `date_estimate`, `date_precision` (`exact`, `day`, `week`, `month`, `year` …), `edited`, `edited_estimate` (düzenlenmiş yorumun yaklaşık düzenlenme tarihi), `translated`, `photos`, `owner_response`, `likes`, `language`, `details` (yorumun altındaki yapılandırılmış satırlar: `{ name: 'Yiyecek', value: '5' }` gibi alt puanlar ve `{ name: 'Kişi başı fiyat', value: '₺400–600' }` gibi satırlar). `reviews` sonucu ayrıca `sort_label` ve `sort_applied` bildirir; istenen sıralama seçilemezse `warnings` içinde `REVIEW_SORT_NOT_APPLIED` olur.\r\n\r\nHer sonuçta `view` (`full` · `limited` · `unknown`) ve `account` (`signed_in` · `signed_out` · `unknown`) bulunur. Her fonksiyon, seçenek ve alan: [docs/tr/api.md](docs/tr/api.md), [docs/tr/data.md](docs/tr/data.md).\r\n\r\n**Durumlar:** `ok`, `incomplete` (bazı kısımlar okunamadı, `warnings`e bakın), `limited_view`, `auth_required`, `consent_required`, `blocked`, `unavailable`. Sık uyarılar: `MENU_PHOTOS_UNAVAILABLE` (menü ürünleri okundu ama menü fotoğraf albümü açılamadı), `REVIEWS_UNAVAILABLE`, `REVIEW_SORT_NOT_APPLIED`, `LIMITED_VIEW` ve sizin koyduğunuz sınır bir listeyi durdurduysa `…_LIMIT_OR_SCROLL_LIMIT`.\r\n\r\n### Komut satırı\r\n\r\nKomutlar stdout'a tek bir JSON yanıt yazar (hata durumunda çıkış kodu `2` ve `error_code`). `MAPS_PROFILE_DIR`'i kalıcı bir profile ayarlayın ve `gmaps-login` ile bir kez oturum açın; çerez dosyası kullanılmaz. Bütün bayraklar ve alanlar: [docs/tr/cli.md](docs/tr/cli.md).\r\n\r\n```bash\r\n# Bir kez: profilde oturum açın (pencere açılır; sunucuda --port 9222 ekleyip SSH tüneli kullanın, bkz. docs/tr/sign-in.md)\r\nMAPS_PROFILE_DIR=/mutlak/ozel/profil npx gmaps-login\r\n\r\n# Linkle tek mekân: detaylar, menü, fotoğraflar ve tarihleriyle en yeni 300 yorum\r\nMAPS_PROFILE_DIR=/mutlak/ozel/profil npx gmaps-place --url \"https://maps.app.goo.gl/mekan-linki\" --reviews --sort newest --max-reviews 300 --max-review-scrolls 40\r\n\r\n# Birden çok işletme için arama + detay (JSON istek stdin'den)\r\necho '{\"schema_version\":\"gmaps.scan.request.v1\",\"location\":\"Kadıköy, İstanbul\",\"keyword\":\"kafe\",\"limit\":5}' \\\r\n  | MAPS_PROFILE_DIR=/mutlak/ozel/profil npx gmaps-scan\r\n\r\n# Profili denetlemek (cron, saatte bir): çıkış kodu 0 = tam görünüm, 3 = sınırlı; görünümü ve hesabı bildirir\r\nMAPS_PROFILE_DIR=/mutlak/ozel/profil npx gmaps-view --no-repair\r\n```\r\n\r\n### MCP sunucusu\r\n\r\n`gmaps-mcp`, yapay zekâ ajanlarının (Claude Code, Claude Desktop ve diğer MCP istemcileri) okuyucuyu dört araçla kullanmasını sağlar: `search`, `place`, `reviews` (yorumcu adları olmadan) ve `photos` (Google fotoğraflarını görsel olarak döndürür, ör. menü sayfası okumak için). Kendi Chrome'unuzla yerelde çalışır; API anahtarı gerekmez. Tam görünüm için profilde `gmaps-login` ile bir kez oturum açın.\r\n\r\n```bash\r\n# Claude Code\r\nclaude mcp add gmaps -e MAPS_PROFILE_DIR=/mutlak/yol/gmaps-profile -- npx -y -p gmaps-place-reader gmaps-mcp\r\n```\r\n\r\nClaude Desktop ve diğer istemciler, araçların bütün argümanları ve sınırlar (`MAPS_MCP_MAX_READS`, `MAPS_MCP_MAX_PHOTOS`, `MAPS_MCP_PAUSE_MS`): [docs/tr/mcp.md](docs/tr/mcp.md).\r\n\r\n### Yapılandırma\r\n\r\n| Ortam değişkeni | Seçenek | Amaç |\r\n|---|---|---|\r\n| `MAPS_CHROME_PATH` | `executablePath` | Chrome ya da Chromium dosyası |\r\n| `MAPS_PROFILE_DIR` | `userDataDir` | Kalıcı, özel tarayıcı profili (mutlak yol). **Önerilir:** oturumu (`gmaps-login`) ve tam görünümü korur. |\r\n\r\nKomut satırı bayrakları ve JSON istek alanları ortam değişkenlerinden önce gelir. MCP sunucusunun kendi sınırları vardır ([MCP sunucusu](docs/tr/mcp.md)).\r\n\r\n### Tam görünüm ve oturum açma\r\n\r\nGoogle Maps bir mekân sayfasını ya **sınırlı görünüm** (Menü sekmesi yok, ürün ve fiyat yok, çoğu zaman menü albümü yok, daha az bilgi) ya da **tam görünüm** olarak gösterir. Ekim 2026'ya kadar bunu tarayıcının anonim kimlik çerezi belirliyordu (AB'de `__Secure-ENID`, başka yerlerde `NID`) ve yeni profillerin yaklaşık yarısı tam görünüm alıyordu; **Ekim 2026 sonundan beri her oturumsuz tarayıcı sınırlı görünüm alıyor**, Google hesabıyla oturum açmış tarayıcı ise tam görünümü almaya devam ediyor.\r\n\r\n- **Kalıcı bir profil kullanın** (`MAPS_PROFILE_DIR` / `userDataDir`). Oturum ve anonim kimlik orada saklanır.\r\n- **`gmaps-login` ile bir kez oturum açın.** Profilde sıradan bir Chrome penceresi açar; oturum açın, Maps açıldığında pencere kapanır. Ekranı olmayan sunucuda pencereyi sanal ekranda (`xvfb-run`) çalıştırır; siz onu bilgisayarınızdan SSH tüneli ve `chrome://inspect` ile yönetirsiniz. Oturumu okuyucunun çalıştığı makinede oluşturun: Chrome, Google oturumlarını cihaza bağlar; başka bilgisayardan kopyalanan oturumlar saatler içinde kapatılır. Okuyucuya ayrılmış bir hesap kullanın.\r\n- **`gmaps-view --no-repair`'i saatte bir çalıştırın** (cron). `\"view\"` ve `\"account\"` bildirir, oturumu canlı tutar ve yalnız tam görünümde `0` ile çıkar. `--no-repair` olmadan sınırlı *oturumsuz* görünümü de onarmayı dener (yeniden yükleme, sonra en çok altı geçici profilden tam görünümlü kimlik; Ekim 2026'dan beri bulamıyor).\r\n- **Çerez dosyası yok.** Okuyucu dışa aktarılmış çerez yüklemez; oturum yalnız profil klasöründe yaşar.\r\n\r\nSüreç, ölçümler ve ipuçları: [docs/tr/sign-in.md](docs/tr/sign-in.md) ve [docs/tr/full-view.md](docs/tr/full-view.md).\r\n\r\nHer durumda Chrome ya da Chromium gerekir. Okuma görünmez modda çalıştığı için masaüstü gerekmez; Linux'ta root olarak değil, normal bir kullanıcıyla çalıştırın. Profil klasörünü gizli tutun.\r\n\r\n### Sınırlar\r\n\r\n- **Türkçe** Google Maps arayüzünü okur: her Maps adresi `hl=tr` ile açılır, bu yüzden sunucunun ve tarayıcının dili önemli değildir. İngilizce etiketler de tanınır.\r\n- Google, Maps sayfa yapısını sık değiştirir; seçicilerin güncellenmesi gerekebilir. Böyle bir durumda yanlış veri yerine `unavailable` ya da `incomplete` alırsınız.\r\n- Arama yarıçapı kesin bir filtre değildir; \"yakın\" olanı Maps metin araması belirler.\r\n- Kesin yorum tarihleri Google'ın kendi sayfa verisinden gelir ve yalnız görünen etiketle uyuşursa kabul edilir; eşleşmezse `date_estimate` etiketten hesaplanır, `date_precision` ne kadar kaba olduğunu söyler. Düzenlenmiş yorumda etiket düzenleme yaşını gösterir, `date_iso` ise ilk yayın tarihidir. Sayfalama sınırları `truncated` ve `coverage_complete` alanlarında belirtilir. Binlerce yorum okumak dakikalar sürer (adım başına ~10 yorum).\r\n- Küçük partilerle çalışın ve istekler arasında bekleyin. CAPTCHA ve doğrulama sayfaları asla atlatılmaz.\r\n\r\n### Sorumluluk reddi\r\n\r\n**Kendi riskinizde kullanın.** Bu proje Google ile bağlantılı değildir ve Google tarafından onaylanmamıştır. Google Maps'e otomatik erişim [Google Haritalar Hizmet Şartları](https://www.google.com/help/terms_maps/) ile çelişebilir. Kişisel ve araştırma amaçlı, düşük hacimli kullanım içindir. Kütüphaneyi nasıl kullandığınızdan, ilgili şartlara ve yasalara uymaktan siz sorumlusunuz. Fotoğraf, yorum ve metinler sahiplerine aittir.\r\n\r\n### Geliştirme\r\n\r\n```bash\r\ngit clone https://github.com/alpersamur3/gmaps-place-reader.git\r\ncd gmaps-place-reader\r\nnpm install\r\nnpm test   # node --test, yerel sahte sayfalarla çalışır; Chrome gerekir (Linux/macOS'ta MAPS_CHROME_PATH)\r\n```\r\n\r\nHata bildirimleri ve pull request'ler memnuniyetle karşılanır.\r\n\r\n### Lisans\r\n\r\n[MIT](https://github.com/alpersamur3/gmaps-place-reader/blob/main/LICENSE) © Alper Samur\r\n\r\n</details>\r\n","readmeFilename":"README.md"}