googlemaps-kit 0.5.0 → 0.7.0

package/docs/trends-research.md

@@ -0,0 +1,82 @@
+# Google Trends investigation
+
+Investigation date: 2026-10-29. Target: Google's public Trends consumer surfaces,
+with no credentials, API alpha enrollment, CAPTCHA solving, or proxy rotation.
+The questions were which anonymous routes return usable data, how query inputs
+and payloads are encoded, which data can be preserved, and where access prevents
+verification.
+
+## Finding ledger
+
+| ID | Evidence | Conclusion | Boundary |
+| --- | --- | --- | --- |
+| TR-01 | Direct HTTP 200, `/trends/api/autocomplete/coffee?hl=en-US`; complete fixture `tests/fixtures/trends/suggestions-coffee.txt` | JSON has an XSSI prefix and `default.topics`, each with `mid`, `title`, `type`. | Observed for one query/locale; extra data is retained. |
+| TR-02 | Direct HTTP 200, `/trending/rss?geo=US`; trimmed fixture `tests/fixtures/trends/trending-us.xml` | RSS has channel metadata, item traffic buckets, dates, pictures and nested `ht:news_item` records. | Observed US feed; geographic availability and item count vary. |
+| TR-03 | First direct Explore page and `/trends/api/explore` attempts returned 429; ordinary fresh Chromium navigation independently displayed 429 | Explore data access is restricted from this network. | This is an observed restriction, not evidence that the protocol never works elsewhere. No retry/rotation flow was added. |
+| TR-04 | Live-served Google embed loader, SHA-256 `5f67429c1b957c1c3472b6e973700f07284a86782ead3791f8f404e1e925fd7e`; REA evidence `ev_152414288f62adb3212d2e73723e68eb6e72ef51fefba57e93cf5aad05e84494` | Source constructs `/trends/embed/explore/{type}` with encoded JSON `req` and minutes-west-of-UTC `tz`. Its compatibility code constructs `comparisonItem`, `category`, and `property`. | Static construction evidence; iframe runtime and data availability remain unverified. |
+| TR-05 | Current landing page and `boq-trends.TrendsUi.en_US.5dr7P7p863E.2018.O` home/exploreview JavaScript, frontend build `boq_trends-boq-servers-frontend_20261028.03_p0` | Current code contains a new Explore sign-in screen and classic Explore retirement notice. Navigation construction uses `/trends/explore`, `q`, `date`, `geo`, and optional `legacy`. | Static UI and navigation evidence; no signed-in session was inspected. |
+| TR-06 | [Official API documentation](https://developers.google.com/search/apis/trends) | The documented API is a limited alpha, distinct from consumer website requests. | No alpha credentials or API service calls were available. |
+
+The [Google-hosted embed loader](https://ssl.gstatic.com/trends_nrtr/2965_RC03/embed_loader.js)
+was located using an asset directory referenced by the current shipped home
+bundle. REA analyzed that isolated 12,352-byte artifact as inert JavaScript. Its
+parse coverage was complete, with three graph nodes; dynamic property resolution
+and runtime invocation remain unknown. An initial analysis of the entire scratch
+capture timed out after five minutes, so no conclusions depend on that analysis.
+The focused analysis did not execute Google's code.
+
+The current Explore bundle also maps the property keys `images`, `news`,
+`froogle`, and `youtube` to its image, news, Shopping, and YouTube labels.
+Those mappings support the typed link options; successful filtered Explore
+data responses were not observed.
+
+The current Explore bundle contains these UI strings: “Sign in to try the new
+Explore” and “Classic Explore is expiring soon, but you can still use it for a
+little longer.” These are static observations, rather than proof that every
+account receives the same rollout or that classic Explore has been retired.
+
+## Encoding and parsing
+
+Suggestions use `encodeURIComponent(keyword)` as one path component and `hl` as
+an ordinary query parameter. The observed XSSI prefix is removed before JSON
+parsing. Topic records and the full response remain available without dropping
+unknown properties.
+
+RSS parsing supports the observed XML namespace names, standard XML named and
+numeric entities, CDATA, self-closing empty text fields, and nested news items.
+It does not resolve DTDs or external entities. Dates are normalized to ISO while
+the original XML remains available. Approximate traffic is preserved verbatim;
+no exact-volume estimate is inferred from it.
+
+The source's embed compatibility constructor uses items shaped as
+`{ keyword, geo, time }`, plus `category` and `property`. Its iframe constructor
+JSON-serializes `req`, serializes `tz`, and strips nonletters from the optional
+locale. The SDK reproduces that URL construction. Defaults of worldwide,
+`today 12-m`, category 0, UTC, and web search are SDK choices. They are explicit
+and tested; they are not a claim about all website defaults.
+
+Website links are deliberately limited to shared geo/time and comma-free
+keywords. Independent per-item settings are represented by the embed request
+object, because no successful modern Explore response was available to verify
+more complex link semantics.
+
+## Coverage and remaining questions
+
+| Question | Status |
+| --- | --- |
+| Topic suggestion lookup and topic IDs | Answered by a successful capture and live test. |
+| Current trending RSS, article and image metadata | Answered by a successful capture and live test. |
+| Chart iframe request construction | Answered statically; rendering is unverified. |
+| Explore initialization and widget tokens | Unresolved: HTTP 429. |
+| `widgetdata/multiline`, `comparedgeo`, `relatedqueries`, `relatedsearches` | Not implemented: no successful response or corresponding shipped implementation was captured. |
+| Current signed-in new Explore data RPCs | Unresolved: outside the anonymous session inspected. |
+| Restricted official API alpha | Not implemented: enrollment and credentials required. |
+| Current Trending now website filters beyond the RSS export | Unresolved in this pass; RSS does not claim those fields. |
+
+[Google's Trending now help](https://support.google.com/trends/answer/3076011?hl=en)
+describes the RSS export, bucketed traffic and refresh behavior. The
+[related-search documentation](https://support.google.com/trends/answer/4355000?hl=en)
+explains top/rising results and Breakout labels; those concepts are not fabricated
+from the RSS feed. [The data FAQ](https://support.google.com/trends/answer/4365533?hl=en)
+explains sampling and normalization. The website's indexed interest values are
+not the consistently scaled values described for the restricted API.

package/docs/trends.md

@@ -0,0 +1,75 @@
+# Google Trends
+
+The Trends client reads topic suggestions and the public Trending now RSS feed.
+It also builds Explore and chart embed links from Google's shipped request
+format. These methods use the consumer website; Google's separately documented
+[Trends API](https://developers.google.com/search/apis/trends) requires alpha
+access.
+
+```ts
+import { trends } from 'googlemaps-kit/trends';
+
+const client = trends({ locale: 'en-US', timeoutMs: 30_000 });
+const suggestions = await client.suggestions('coffee');
+const coffee = suggestions.topics[0];
+console.log(coffee?.mid, coffee?.title, coffee?.type);
+
+const feed = await client.trending({ geo: 'US' });
+for (const item of feed.items) {
+  console.log(item.title, item.approximateTraffic, item.publishedAt);
+  console.log(item.articles);
+}
+```
+
+Suggestions return topic IDs such as `/m/02vqfm`, display titles and topic
+types. Both the complete JSON response and every topic object remain available
+as `raw`.
+
+RSS items include the exact approximate traffic label, publication time as ISO,
+picture information, and nested news articles. Feed, item and article `raw`
+values retain their XML text, including fields unknown to the client. Traffic
+labels are bucketed display values, rather than precise search counts. The feed
+does not provide arbitrary historical Explore time series or the website's full
+set of Trending now filters.
+
+```ts
+const request = {
+  comparisonItem: [{ keyword: '/m/02vqfm', geo: 'US', time: 'today 12-m' }],
+};
+const explore = client.exploreUrl(request);
+const embed = client.embedUrl('TIMESERIES', request);
+```
+
+Embed types are `TIMESERIES`, `GEO_MAP`, `RELATED_TOPICS`, and `RELATED_QUERIES`.
+Keywords may be ordinary terms or topic IDs. Each comparison item accepts a
+location and a website range expression; omitted values select worldwide and
+`today 12-m`. `category` defaults to 0 and `property` to web search (`''`).
+Optional property values are `images`, `news`, `froogle`, and `youtube`.
+
+Explore links require a shared location and range, and keywords without commas,
+so the link preserves the intended comparison. Embed requests retain independent
+item settings and literal commas. Link generation performs no request and does
+not establish that a chart can be loaded. The standalone
+`buildTrendsExploreUrl(request, { legacy: true })` follows the current website's
+classic Explore navigation option.
+
+Configuration accepts an injected `fetch`, `locale`, `timezone`, and `timeoutMs`.
+`timezone` is minutes west of UTC, matching `Date.getTimezoneOffset()`, and
+applies to embed URLs. Both network methods accept an `AbortSignal`. The timeout
+covers the response body as well as the initial HTTP request.
+
+`TrendsError.kind` distinguishes `rate-limit`, `blocked`, `http`, `network`,
+`timeout`, and `parse`. HTTP errors expose `status`; applicable responses expose
+`retryAfterMs`. Caller cancellation retains the caller's abort reason. Requests
+are issued once, so callers can decide their own scheduling after rate limits.
+
+The investigation successfully retrieved suggestions and RSS. Explore's page,
+legacy API, and embed page returned HTTP 429 on this network, including an
+ordinary browser visit. The library therefore does not expose unverified widget
+token or widget-data methods. The current shipped Explore frontend also contains
+a sign-in gate for the new Explore and a classic Explore retirement notice.
+See [the research ledger](trends-research.md) for the evidence boundary.
+
+Run offline verification with `npx vitest run tests/unit/trends`. Run live
+verification explicitly with
+`GMAPS_LIVE=1 npx vitest run tests/live/trends.test.ts`.

package/docs/youtube.md

@@ -0,0 +1,72 @@
+# YouTube
+
+The anonymous YouTube client reads watch-page metadata, public search results,
+search continuations, and oEmbed metadata. It uses the consumer website without
+an API key.
+
+```ts
+import { youtube } from 'googlemaps-kit/youtube';
+
+const client = youtube({ locale: 'en', region: 'US' });
+const video = await client.video('bC8fvcpocBU');
+console.log(video.title, video.author, video.lengthSeconds);
+console.log(video.playability.status, video.playability.reason);
+console.log(video.captions.map(track => [track.languageCode, track.name]));
+
+const first = await client.search('Google for Developers');
+console.log(first.items);
+if (first.continuation) {
+  const next = await client.continueSearch(first.continuation);
+  console.log(next.items);
+}
+
+const embedMetadata = await client.oembed('bC8fvcpocBU');
+console.log(embedMetadata.title, embedMetadata.thumbnail_url);
+```
+
+`video()` accepts an 11-character video ID or a YouTube watch, short, embed,
+live, or youtu.be URL. It returns title, channel/author, description, length,
+view-count text, thumbnails, keywords and available caption-track metadata.
+The original player payload and initial watch data remain available through
+`raw` and `initialData`. An unavailable video can have a playability status and
+reason while metadata is absent. `LOGIN_REQUIRED`, age restrictions, bot gates,
+and other player states are retained rather than interpreted as successful
+playback.
+
+Search items distinguish video, channel and playlist records. The parser handles
+the observed classic video/channel renderers and current playlist lockup view
+models, including nested result shelves. Unknown renderer structures remain in
+`raw`; the client does not claim to normalize every YouTube presentation.
+Duration, views and publication time from search remain localized display text.
+Duplicate result IDs are deduplicated, and explicit ad containers are excluded
+from the normalized items.
+
+The opaque continuation includes its minimal anonymous client context. Pass it
+unchanged to `continueSearch()`. The client uses the version and visitor context
+supplied by the current page; it does not embed a fixed internal API key. These
+cursors are session-specific and may expire.
+
+`oembed()` returns the complete provider object, including the iframe HTML. Treat
+that HTML as external content when presenting it. The client returns metadata
+and never fetches audio/video streams or deciphers media signatures.
+
+Caption tracks are metadata only. In the captured session, timed-text requests
+returned HTTP 200 with an empty body, both through the website and direct HTTP.
+That response does not prove that a video has no captions. No transcript-content
+method is exposed without a verified content response.
+
+Configuration accepts `fetch`, `locale`, `region`, and `timeoutMs` (30 seconds by
+default). Each method accepts `{ signal }`; the deadline includes response-body
+reads. `YouTubeError.kind` identifies `http`, `blocked`, `auth-required`,
+`rate-limit`, `parse`, `network`, and `timeout`. A playability restriction inside
+a successful watch response stays on `video.playability`. Failed requests are
+not retried.
+
+The investigation successfully exercised metadata, oEmbed, search, and anonymous
+continuation with the SDK. The suggested Rick Astley test ID was unavailable in
+the observed session; the public Google for Developers introduction supplied a
+successful alternative. See [the media research ledger](google-media-research.md)
+for the capture scope.
+
+Run offline tests with `npx vitest run tests/unit/youtube` and opt-in live checks
+with `GMAPS_LIVE=1 npx vitest run tests/live/google-media.test.ts`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "googlemaps-kit",
-  "version": "0.5.0",
-  "description": "TypeScript SDK + Bubble Tea TUI for Google Maps consumer surfaces",
+  "version": "0.7.0",
+  "description": "TypeScript SDK + Bubble Tea TUI for Google Maps and public Google consumer services",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,78 @@
         "default": "./dist/index.js"
       }
     },
+    "./pagespeed": {
+      "import": {
+        "types": "./dist/pagespeed.d.ts",
+        "default": "./dist/pagespeed.js"
+      }
+    },
+    "./translate": {
+      "import": {
+        "types": "./dist/translate.d.ts",
+        "default": "./dist/translate.js"
+      }
+    },
+    "./news": {
+      "import": {
+        "types": "./dist/news.d.ts",
+        "default": "./dist/news.js"
+      }
+    },
+    "./google-search": {
+      "import": {
+        "types": "./dist/google-search.d.ts",
+        "default": "./dist/google-search.js"
+      }
+    },
+    "./trends": {
+      "import": {
+        "types": "./dist/trends.d.ts",
+        "default": "./dist/trends.js"
+      }
+    },
+    "./finance": {
+      "import": {
+        "types": "./dist/finance.d.ts",
+        "default": "./dist/finance.js"
+      }
+    },
+    "./flights": {
+      "import": {
+        "types": "./dist/flights.d.ts",
+        "default": "./dist/flights.js"
+      }
+    },
+    "./hotels": {
+      "import": {
+        "types": "./dist/hotels.d.ts",
+        "default": "./dist/hotels.js"
+      }
+    },
+    "./youtube": {
+      "import": {
+        "types": "./dist/youtube.d.ts",
+        "default": "./dist/youtube.js"
+      }
+    },
+    "./lens": {
+      "import": {
+        "types": "./dist/lens.d.ts",
+        "default": "./dist/lens.js"
+      }
+    },
+    "./books": {
+      "import": {
+        "types": "./dist/books.d.ts",
+        "default": "./dist/books.js"
+      }
+    },
+    "./gemini-web": {
+      "import": {
+        "types": "./dist/gemini-web.d.ts",
+        "default": "./dist/gemini-web.js"
+      }
+    },
     "./advanced": {
       "import": {
         "types": "./dist/advanced.d.ts",
@@ -24,6 +96,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "LICENSE",
     "README.md",
     ".github/assets/banner.png"
@@ -41,6 +114,8 @@
     "test": "vitest run tests/unit",
     "test:watch": "vitest",
     "test:live": "GMAPS_LIVE=1 vitest run tests/live",
+    "test:pagespeed:live": "GMAPS_LIVE=1 PAGESPEED_LIVE=1 vitest run tests/live/pagespeed.test.ts",
+    "test:google-public:live": "GMAPS_LIVE=1 FINANCE_LIVE=1 GOOGLE_TRAVEL_LIVE=1 vitest run tests/live/google-translate.test.ts tests/live/google-news.test.ts tests/live/trends.test.ts tests/live/google-search.test.ts tests/live/finance.test.ts tests/live/google-travel.test.ts tests/live/google-media.test.ts tests/live/google-ai-books.test.ts",
     "preexample": "npm run build",
     "example:quick-start": "tsx examples/quick-start.ts",
     "example:search": "tsx examples/search-text.ts",