googlemaps-kit 0.3.1 → 0.5.0

package/dist/parsers/place-extended.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Extended place parser: extracts all data points from the place preview protobuf
+ * that are not covered by the base extractPlaceDetails() / extractPlaceAggregateAttributes().
+ *
+ * This parser is designed to be called once (no extra HTTP requests) on the same
+ * placeData node returned by the place preview endpoint. All fields are optional;
+ * missing nodes produce undefined rather than throwing.
+ *
+ * Performance: all extractions are O(n) over the protobuf tree with bounded depth.
+ * The combined parse time is <1 ms on a 130 KB payload.
+ */
+import type { PlaceDetails } from '../types/common.js';
+import type { PlaceDataNode } from '../types/protobuf.js';
+import type { GasPrice, HotelData, OwnerUpdate, PeopleAlsoSearch, PlaceMenu, PlaceQAResult, RestaurantData, ReviewTag } from '../types/place-extended.js';
+/**
+ * Extract cid (numeric content id) and kgmid (/g/… or /m/… knowledge entity id).
+ *
+ * Primary path: placeData[227][0] — the definitive ID block (verified against fixture).
+ *   [227][0][0] = hexId
+ *   [227][0][3] = kgmid (/g/… or /m/…)
+ *   [227][0][4] = placeId (ChIJ…)
+ *   [227][0][5] = cid (numeric string)
+ *   [227][0][6] = ownerId
+ *
+ * Fallback paths used when [227] is absent (older response variants):
+ *   kgmid: placeData[89] (ftid) or placeData[23]
+ *   cid:   placeData[181][5]
+ */
+export declare function extractPlaceIdentifiers(placeData: PlaceDataNode): {
+    cid?: string;
+    kgmid?: string;
+    ownerId?: string;
+};
+/**
+ * Decompose address components from placeData[183] or placeData[2].
+ *
+ * placeData[183] is the structured address block; [183][0] = street number,
+ * [183][1] = street name, [183][2][2][0] = plus code address (locality), etc.
+ * Fallback: scan placeData[2] string array for city/state/postal heuristics.
+ */
+export declare function extractStructuredAddress(placeData: PlaceDataNode, formattedAddress?: string): {
+    street?: string;
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    countryCode?: string;
+    country?: string;
+    raw?: unknown;
+};
+/**
+ * Extract review keyword/topic frequency tags from placeData.
+ * These are the chips shown under the star histogram, e.g. "paneer dishes".
+ *
+ * Primary: placeData[153][0][i] — verified against fixture (Kake Di Hatti HSR).
+ *   entry[0]    = [topicId] array
+ *   entry[1]    = keyword string  ("paneer dishes")
+ *   entry[3]    = counts array:
+ *     [3][4]    = positiveCount
+ *     [3][5]    = negativeCount
+ *     [3][7]    = totalMentions
+ *   entry[4]    = encodedId (base64)
+ *
+ * Fallback: placeData[175][1][*] for older response variants.
+ */
+export declare function extractReviewTags(placeData: PlaceDataNode): ReviewTag[];
+/**
+ * Extract "People also search for" cards from the place panel.
+ * These are cross-sell recommendation cards shown at the bottom of the place card.
+ *
+ * Location candidates: placeData[127][*] or placeData[99][*] in various preview versions.
+ */
+export declare function extractPeopleAlsoSearch(placeData: PlaceDataNode): PeopleAlsoSearch[];
+/**
+ * Extract owner-posted updates from placeData.
+ *
+ * Owner updates differ from local posts: they are "this business has updated X"
+ * style entries visible on the place card (e.g. "Updated hours" / "Added new photos").
+ *
+ * Location: placeData[175][3][*] or placeData[128][*] in various response variants.
+ */
+export declare function extractOwnerUpdates(placeData: PlaceDataNode): OwnerUpdate[];
+/**
+ * Extract gas station fuel prices from placeData.
+ *
+ * Location: placeData[150] in most response variants — an array of grade+price entries.
+ * Each entry: [grade_label, price_string, updated_at?]
+ */
+export declare function extractGasPrices(placeData: PlaceDataNode): GasPrice[];
+/**
+ * Extract hotel-specific data from placeData.
+ *
+ * Hotel stars: placeData[89] or placeData[141] — string like "4-star hotel".
+ * Hotel description: placeData[32][*] (same as general description fallback).
+ * Booking offers: placeData[159][*] — provider name + price + url.
+ * Similar hotels: placeData[162][*] — name + rating + price.
+ */
+export declare function extractHotelData(placeData: PlaceDataNode): HotelData | undefined;
+/**
+ * Extract restaurant-specific data (reservation provider, order/booking links).
+ *
+ * Reservation provider: placeData[25] or placeData[66][0] — [name, reserveUrl].
+ * Table reservation links: placeData[66][*] — [name, url].
+ * Order links: placeData[75][*] or placeData[71][*] — [provider, url].
+ */
+export declare function extractRestaurantData(placeData: PlaceDataNode): RestaurantData | undefined;
+/**
+ * Extract inline structured menu from placeData.
+ *
+ * The inline menu (when Google serves it) lives at placeData[168] or placeData[117].
+ * Structure: sections array → each section: [title, items[]] → item: [name, price, desc, imageUrl].
+ *
+ * Many places only have a menuUrl (placeData[7][1] or placeData[46]) without inline items.
+ */
+export declare function extractMenu(placeData: PlaceDataNode, menuUrl?: string): PlaceMenu | undefined;
+/**
+ * Extract inline Q&A items embedded in place preview.
+ *
+ * Q&A data is embedded at placeData[311] (verified on some restaurant fixtures).
+ * Layout (inferred from structure):
+ *   [311][0][*] — array of Q&A items
+ *   item[0]     — question id
+ *   item[1]     — question text
+ *   item[2]     — askedBy author name
+ *   item[3]     — askedBy author profile URL
+ *   item[4]     — date asked
+ *   item[5]     — upvote count
+ *   item[6][*]  — array of answers
+ *     answer[0] — answer text
+ *     answer[1] — author name
+ *     answer[2] — author profile URL
+ *     answer[3] — author avatar URL
+ *     answer[4] — date
+ *     answer[5] — upvote count
+ *     answer[6] — is owner answer (1 = true)
+ *
+ * Also tries placeData[171] which may carry a different Q&A layout on some locales.
+ */
+export declare function extractEmbeddedQA(placeData: PlaceDataNode): PlaceQAResult | undefined;
+/**
+ * Apply all extended field extractions to an already-parsed PlaceDetails object.
+ *
+ * This mutates `details` in-place and returns it, so callers can write:
+ *   const details = extractPlaceDetails(data);
+ *   applyExtendedFields(details, placeData, { raw: true, rawData: data });
+ *
+ * Passing `raw: true` attaches the full protobuf tree to `details.raw`.
+ * All sub-parsers are called unconditionally — they return empty/undefined
+ * internally rather than throwing, so the total overhead is negligible.
+ */
+export declare function applyExtendedFields(details: PlaceDetails, placeData: PlaceDataNode, options?: {
+    raw?: boolean;
+    rawData?: unknown;
+}): PlaceDetails;
+/**
+ * Build a `reviewDetailedRating` map from a review's attribute array.
+ * Call this inside the boq review parser after attributes are extracted.
+ */
+export declare function buildReviewDetailedRating(attributes: Array<{
+    label: string;
+    rating?: number;
+}> | undefined): Record<string, number> | undefined;
+//# sourceMappingURL=place-extended.d.ts.map

package/dist/parsers/place-extended.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place-extended.d.ts","sourceRoot":"","sources":["../../src/parsers/place-extended.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAU,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EACV,QAAQ,EAER,SAAS,EAGT,WAAW,EACX,gBAAgB,EAChB,SAAS,EAGT,aAAa,EACb,cAAc,EACd,SAAS,EAEV,MAAM,4BAA4B,CAAC;AASpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,aAAa,GAAG;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAqBA;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,aAAa,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAuDA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,EAAE,CA2CvE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB,EAAE,CAgCpF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,aAAa,GAAG,WAAW,EAAE,CAmC3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,QAAQ,EAAE,CA+BrE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,CAkFhF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CA0C1F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAmF7F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CA6ErF;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C,YAAY,CAuEd;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,GAChE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CASpC"}