googlemaps-kit 0.1.0

package/dist/services/distance-matrix.js

@@ -0,0 +1,144 @@
+import { parseDistanceToMeters, parseDurationToSeconds } from '../utils/directions-metrics.js';
+import { haversineMeters } from '../utils/geo.js';
+import { pooled } from '../utils/pooled.js';
+/** Match HttpClient default concurrency; no per-pair sleep — scheduler paces. */
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_REQUEST_DELAY_MS = 0;
+const SAME_POINT_THRESHOLD_METERS = 1;
+function isCoordinates(value) {
+    return typeof value === 'object' && value != null && 'lat' in value && 'lng' in value;
+}
+function locationKey(value) {
+    if (isCoordinates(value)) {
+        return `${value.lat.toFixed(6)},${value.lng.toFixed(6)}`;
+    }
+    return `s:${value.trim().toLowerCase()}`;
+}
+function normalizeLocations(values) {
+    return values.map((origin) => ({ key: locationKey(origin), origin }));
+}
+function parseDirectionsCell(result) {
+    const distanceText = result.distance ?? result.legs[0]?.distance;
+    const durationText = result.duration ?? result.legs[0]?.duration;
+    const distanceMeters = parseDistanceToMeters(distanceText);
+    const durationSeconds = parseDurationToSeconds(durationText);
+    if (!distanceText && !durationText && result.legs.length === 0) {
+        return { status: 'ZERO_RESULTS' };
+    }
+    return {
+        status: 'OK',
+        distanceMeters,
+        durationSeconds,
+        distanceText,
+        durationText,
+    };
+}
+export class DistanceMatrixService {
+    directions;
+    constructor(directions, _config) {
+        this.directions = directions;
+    }
+    /**
+     * Compute an origins × destinations travel-time matrix.
+     *
+     * Consumer Maps has no native Distance Matrix RPC — this fans out over
+     * `/maps/preview/directions` with `metricsOnly` (no HTML scrape). Defaults:
+     * concurrency 8, no artificial per-pair delay. A 2×2 lands near one directions
+     * RTT (~700 ms); larger matrices scale as ceil(N×M / concurrency) × ~RTT.
+     */
+    async getMatrix(options) {
+        const origins = normalizeLocations(options.origins);
+        const destinations = normalizeLocations(options.destinations);
+        const mode = options.mode ?? 'driving';
+        const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+        const requestDelayMs = options.requestDelayMs ?? DEFAULT_REQUEST_DELAY_MS;
+        const start = performance.now();
+        if (origins.length === 0 || destinations.length === 0) {
+            return {
+                rows: [],
+                requestCount: 0,
+                implementation: 'directions-fan-out',
+                timingMs: 0,
+            };
+        }
+        const uniquePairs = new Map();
+        for (let oi = 0; oi < origins.length; oi++) {
+            for (let di = 0; di < destinations.length; di++) {
+                const origin = origins[oi];
+                const destination = destinations[di];
+                const pairKey = `${origin.key}:${destination.key}:${mode}`;
+                if (!uniquePairs.has(pairKey)) {
+                    uniquePairs.set(pairKey, {
+                        originIndex: oi,
+                        destinationIndex: di,
+                        origin: origin.origin,
+                        destination: destination.origin,
+                    });
+                }
+            }
+        }
+        const pairResults = new Map();
+        const pairList = [...uniquePairs.entries()];
+        await pooled(pairList, concurrency, async ([pairKey, pair], index) => {
+            if (requestDelayMs > 0 && index > 0) {
+                await new Promise((r) => setTimeout(r, requestDelayMs));
+            }
+            if (isCoordinates(pair.origin) &&
+                isCoordinates(pair.destination) &&
+                haversineMeters(pair.origin.lat, pair.origin.lng, pair.destination.lat, pair.destination.lng) <
+                    SAME_POINT_THRESHOLD_METERS) {
+                pairResults.set(pairKey, {
+                    originIndex: pair.originIndex,
+                    destinationIndex: pair.destinationIndex,
+                    status: 'OK',
+                    distanceMeters: 0,
+                    durationSeconds: 0,
+                    distanceText: '0 m',
+                    durationText: '0 min',
+                });
+                return;
+            }
+            try {
+                const directions = await this.directions.get({
+                    origin: pair.origin,
+                    destination: pair.destination,
+                    mode,
+                    metricsOnly: true,
+                });
+                pairResults.set(pairKey, {
+                    originIndex: pair.originIndex,
+                    destinationIndex: pair.destinationIndex,
+                    ...parseDirectionsCell(directions),
+                });
+            }
+            catch (error) {
+                pairResults.set(pairKey, {
+                    originIndex: pair.originIndex,
+                    destinationIndex: pair.destinationIndex,
+                    status: 'ERROR',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+        const rows = origins.map((origin, originIndex) => destinations.map((destination, destinationIndex) => {
+            const pairKey = `${origin.key}:${destination.key}:${mode}`;
+            const cached = pairResults.get(pairKey);
+            if (cached) {
+                return { ...cached, originIndex, destinationIndex };
+            }
+            return {
+                originIndex,
+                destinationIndex,
+                status: 'ERROR',
+                error: 'Missing cell result',
+            };
+        }));
+        return {
+            rows,
+            requestCount: pairList.length,
+            implementation: 'directions-fan-out',
+            timingMs: performance.now() - start,
+        };
+    }
+}
+//# sourceMappingURL=distance-matrix.js.map

package/dist/services/distance-matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distance-matrix.js","sourceRoot":"","sources":["../../src/services/distance-matrix.ts"],"names":[],"mappings":"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"}

package/dist/services/elevation.d.ts

@@ -0,0 +1,30 @@
+import { HttpClient } from '../client/http-client.js';
+import { DirectionsService } from './directions.js';
+import type { Coordinates, GMapsConfig } from '../types/common.js';
+import type { ElevationPathOptions, ElevationPathResult, ElevationPointOptions, ElevationPointResult } from '../types/elevation.js';
+export declare class ElevationService {
+    private http;
+    private directions;
+    private hl;
+    private gl;
+    constructor(http: HttpClient, directions: DirectionsService, config: GMapsConfig);
+    /**
+     * Point elevation via a short bicycling directions lookup.
+     * No dedicated elevation RPC on consumer Maps — Google embeds stats in bicycling
+     * directions at route `[0][16][2]`. One preview hit (no scrape / no retry sleeps).
+     */
+    getAtPoint(options: ElevationPointOptions): Promise<ElevationPointResult>;
+    /** Batch point elevations with bounded concurrency (default 8). */
+    getAtPoints(points: Coordinates[], options?: {
+        concurrency?: number;
+        hl?: string;
+        gl?: string;
+    }): Promise<ElevationPointResult[]>;
+    /**
+     * Elevation summary and distance/grade profile along a path.
+     * Uses `/maps/preview/directions` (bicycling by default — most reliable elevation block).
+     */
+    getAlongPath(options: ElevationPathOptions): Promise<ElevationPathResult>;
+    private fetchDirectionsRaw;
+}
+//# sourceMappingURL=elevation.d.ts.map

package/dist/services/elevation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevation.d.ts","sourceRoot":"","sources":["../../src/services/elevation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAM/B,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW;IAOhF;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiD/E,mEAAmE;IAC7D,WAAW,CACf,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3D,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAalC;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAmDjE,kBAAkB;CA8BjC"}

package/dist/services/elevation.js

@@ -0,0 +1,149 @@
+import { extractDirectionsElevation } from '../parsers/elevation-directions.js';
+import { buildDirectionsUrls } from '../rpc/pb-builders.js';
+import { pooled } from '../utils/pooled.js';
+const MICRO_ROUTE_OFFSET = 0.002;
+export class ElevationService {
+    http;
+    directions;
+    hl;
+    gl;
+    constructor(http, directions, config) {
+        this.http = http;
+        this.directions = directions;
+        this.hl = config.hl ?? 'en';
+        this.gl = config.gl ?? 'us';
+    }
+    /**
+     * Point elevation via a short bicycling directions lookup.
+     * No dedicated elevation RPC on consumer Maps — Google embeds stats in bicycling
+     * directions at route `[0][16][2]`. One preview hit (no scrape / no retry sleeps).
+     */
+    async getAtPoint(options) {
+        const hl = options.hl ?? this.hl;
+        const gl = options.gl ?? this.gl;
+        const start = performance.now();
+        try {
+            const dest = {
+                lat: options.lat + MICRO_ROUTE_OFFSET,
+                lng: options.lng + MICRO_ROUTE_OFFSET,
+            };
+            const raw = await this.fetchDirectionsRaw({ lat: options.lat, lng: options.lng }, dest, 'bicycling', hl, gl);
+            const parsed = extractDirectionsElevation(raw);
+            if (parsed.status !== 'OK' || parsed.startElevationMeters == null) {
+                return {
+                    lat: options.lat,
+                    lng: options.lng,
+                    status: 'UNAVAILABLE',
+                    error: 'Elevation block absent from bicycling directions response',
+                    timingMs: performance.now() - start,
+                };
+            }
+            return {
+                lat: options.lat,
+                lng: options.lng,
+                status: 'OK',
+                elevationMeters: parsed.startElevationMeters,
+                source: 'directions-bicycling-start',
+                timingMs: performance.now() - start,
+            };
+        }
+        catch (error) {
+            return {
+                lat: options.lat,
+                lng: options.lng,
+                status: 'ERROR',
+                error: error instanceof Error ? error.message : String(error),
+                timingMs: performance.now() - start,
+            };
+        }
+    }
+    /** Batch point elevations with bounded concurrency (default 8). */
+    async getAtPoints(points, options) {
+        const concurrency = options?.concurrency ?? 8;
+        const out = new Array(points.length);
+        await pooled(points, concurrency, async (point, index) => {
+            out[index] = await this.getAtPoint({
+                ...point,
+                hl: options?.hl,
+                gl: options?.gl,
+            });
+        });
+        return out;
+    }
+    /**
+     * Elevation summary and distance/grade profile along a path.
+     * Uses `/maps/preview/directions` (bicycling by default — most reliable elevation block).
+     */
+    async getAlongPath(options) {
+        const mode = options.mode ?? 'bicycling';
+        const hl = options.hl ?? this.hl;
+        const gl = options.gl ?? this.gl;
+        const start = performance.now();
+        if (options.points.length < 2) {
+            return {
+                status: 'ERROR',
+                mode,
+                error: 'At least two points are required',
+                timingMs: performance.now() - start,
+            };
+        }
+        const origin = options.points[0];
+        const destination = options.points[options.points.length - 1];
+        try {
+            const raw = await this.fetchDirectionsRaw(origin, destination, mode, hl, gl);
+            const parsed = extractDirectionsElevation(raw);
+            if (parsed.status !== 'OK') {
+                return {
+                    status: 'UNAVAILABLE',
+                    mode,
+                    error: 'No elevation block in directions response for this route/mode',
+                    raw: options.raw ? raw : undefined,
+                    timingMs: performance.now() - start,
+                };
+            }
+            return {
+                status: 'OK',
+                mode,
+                summary: parsed.summary,
+                profile: parsed.profile,
+                pathDistanceMeters: parsed.pathDistanceMeters,
+                raw: options.raw ? raw : undefined,
+                timingMs: performance.now() - start,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'ERROR',
+                mode,
+                error: error instanceof Error ? error.message : String(error),
+                timingMs: performance.now() - start,
+            };
+        }
+    }
+    async fetchDirectionsRaw(origin, destination, mode, hl, gl) {
+        const urls = buildDirectionsUrls({ origin, destination, mode, hl, gl });
+        const url = urls[0];
+        try {
+            const data = await this.http.get(url, {
+                referer: 'https://www.google.com/maps/',
+                includeOrigin: true,
+            });
+            const parsed = extractDirectionsElevation(data);
+            if (parsed.status === 'OK')
+                return data;
+        }
+        catch {
+            // fall through to metrics-only directions service
+        }
+        const fallback = await this.directions.get({
+            origin,
+            destination,
+            mode,
+            metricsOnly: true,
+        });
+        if (fallback.raw)
+            return fallback.raw;
+        throw new Error('Directions request returned no elevation-bearing payload');
+    }
+}
+//# sourceMappingURL=elevation.js.map

package/dist/services/elevation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevation.js","sourceRoot":"","sources":["../../src/services/elevation.ts"],"names":[],"mappings":"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"}

package/dist/services/geocode.d.ts

@@ -0,0 +1,20 @@
+import { HttpClient } from '../client/http-client.js';
+import type { GMapsConfig } from '../types/common.js';
+import type { GeocodeOptions, GeocodeResponse, ReverseGeocodeOptions } from '../types/geocode.js';
+export declare class GeocodeService {
+    private http;
+    private hl;
+    private gl;
+    constructor(http: HttpClient, config: GMapsConfig);
+    /** Forward geocode: address string → coordinates and place metadata. */
+    geocode(address: string, options?: GeocodeOptions): Promise<GeocodeResponse>;
+    /**
+     * Reverse geocode: coordinates → nearest place / Plus Code address.
+     *
+     * Query formulation: `q={lat},{lng}` with the search pb camera centred on the same
+     * coordinates (verified live against Paris, NYC and Bangalore probes).
+     */
+    reverseGeocode(lat: number, lng: number, options?: ReverseGeocodeOptions): Promise<GeocodeResponse>;
+    private fetch;
+}
+//# sourceMappingURL=geocode.d.ts.map

package/dist/services/geocode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geocode.d.ts","sourceRoot":"","sources":["../../src/services/geocode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAU7B,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD,wEAAwE;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAelF;;;;;OAKG;IACG,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC;YAQb,KAAK;CA4BpB"}

package/dist/services/geocode.js

@@ -0,0 +1,63 @@
+import { extractGeocodeResults, toGeocodeResponse } from '../parsers/geocode.js';
+import { buildSearchUrl } from '../rpc/pb-builders.js';
+const DEFAULT_RESULTS_COUNT = 5;
+const DEFAULT_MAX_RADIUS = 50_000;
+const DEFAULT_FORWARD_ZOOM = 15;
+const DEFAULT_REVERSE_ZOOM = 17;
+export class GeocodeService {
+    http;
+    hl;
+    gl;
+    constructor(http, config) {
+        this.http = http;
+        this.hl = config.hl ?? 'en';
+        this.gl = config.gl ?? 'us';
+    }
+    /** Forward geocode: address string → coordinates and place metadata. */
+    async geocode(address, options) {
+        const trimmed = address.trim();
+        if (!trimmed) {
+            return { result: null, alternatives: [] };
+        }
+        const lat = options?.lat ?? 0;
+        const lng = options?.lng ?? 0;
+        return this.fetch(trimmed, lat, lng, {
+            ...options,
+            zoom: options?.zoom ?? DEFAULT_FORWARD_ZOOM,
+        });
+    }
+    /**
+     * Reverse geocode: coordinates → nearest place / Plus Code address.
+     *
+     * Query formulation: `q={lat},{lng}` with the search pb camera centred on the same
+     * coordinates (verified live against Paris, NYC and Bangalore probes).
+     */
+    async reverseGeocode(lat, lng, options) {
+        const query = `${lat},${lng}`;
+        return this.fetch(query, lat, lng, {
+            ...options,
+            zoom: options?.zoom ?? DEFAULT_REVERSE_ZOOM,
+        });
+    }
+    async fetch(query, lat, lng, options) {
+        const hl = options?.hl ?? this.hl;
+        const gl = options?.gl ?? this.gl;
+        const url = buildSearchUrl({
+            query,
+            lat,
+            lng,
+            resultsCount: options?.resultsCount ?? DEFAULT_RESULTS_COUNT,
+            maxRadius: options?.maxRadius ?? DEFAULT_MAX_RADIUS,
+            viewportDist: options?.viewportDist,
+            offset: 0,
+            hl,
+            gl,
+            zoom: options?.zoom,
+        });
+        const data = await this.http.get(url);
+        const results = extractGeocodeResults(data);
+        const response = toGeocodeResponse(results, options?.raw ? data : undefined);
+        return response;
+    }
+}
+//# sourceMappingURL=geocode.js.map

package/dist/services/geocode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geocode.js","sourceRoot":"","sources":["../../src/services/geocode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AASvD,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAChC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAIhC,MAAM,OAAO,cAAc;IACjB,IAAI,CAAa;IACjB,EAAE,CAAS;IACX,EAAE,CAAS;IAEnB,YAAY,IAAgB,EAAE,MAAmB;QAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC;IAC9B,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,OAAwB;QACrD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;QAC5C,CAAC;QAED,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QAE9B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE;YACnC,GAAG,OAAO;YACV,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,oBAAoB;SAC5C,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAClB,GAAW,EACX,GAAW,EACX,OAA+B;QAE/B,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE;YACjC,GAAG,OAAO;YACV,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,oBAAoB;SAC5C,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,KAAK,CACjB,KAAa,EACb,GAAW,EACX,GAAW,EACX,OAAsB;QAEtB,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAElC,MAAM,GAAG,GAAG,cAAc,CAAC;YACzB,KAAK;YACL,GAAG;YACH,GAAG;YACH,YAAY,EAAE,OAAO,EAAE,YAAY,IAAI,qBAAqB;YAC5D,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,kBAAkB;YACnD,YAAY,EAAE,OAAO,EAAE,YAAY;YACnC,MAAM,EAAE,CAAC;YACT,EAAE;YACF,EAAE;YACF,IAAI,EAAE,OAAO,EAAE,IAAI;SACpB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAE7E,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/services/knowledge.d.ts

@@ -0,0 +1,25 @@
+import { HttpClient } from '../client/http-client.js';
+import type { GMapsConfig, KnowledgeEntity, PlaceDetails } from '../types/common.js';
+export interface GetKnowledgeOptions {
+    hexId: string;
+    ftid?: string;
+    placeId?: string;
+    /** Use place preview fields when the RPC surface is unavailable. */
+    fallbackDetails?: PlaceDetails;
+    /** Try getknowledgeentity RPC even when fallbackDetails is set (default false). */
+    tryRpc?: boolean;
+}
+export declare class KnowledgeService {
+    private http;
+    private hl;
+    private gl;
+    constructor(http: HttpClient, config: GMapsConfig);
+    /**
+     * Fetch knowledge entity data for a place.
+     * By default uses place-preview fallback — getknowledgeentity returns HTTP 400 for every
+     * pb variant and the path is absent from captured JS (no client-side pb builder to imitate).
+     */
+    get(options: GetKnowledgeOptions): Promise<KnowledgeEntity | null>;
+    private fromPlaceDetails;
+}
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/services/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/services/knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAMtD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGrF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD;;;;OAIG;IACG,GAAG,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoCxE,OAAO,CAAC,gBAAgB;CAOzB"}

package/dist/services/knowledge.js

@@ -0,0 +1,58 @@
+import { extractKnowledgeEntity, extractKnowledgeFromPlaceDetails, } from '../parsers/knowledge.js';
+import { buildKnowledgeUrl } from '../rpc/pb-builders.js';
+export class KnowledgeService {
+    http;
+    hl;
+    gl;
+    constructor(http, config) {
+        this.http = http;
+        this.hl = config.hl ?? 'en';
+        this.gl = config.gl ?? 'us';
+    }
+    /**
+     * Fetch knowledge entity data for a place.
+     * By default uses place-preview fallback — getknowledgeentity returns HTTP 400 for every
+     * pb variant and the path is absent from captured JS (no client-side pb builder to imitate).
+     */
+    async get(options) {
+        if (options.fallbackDetails && options.tryRpc !== true) {
+            return this.fromPlaceDetails(options.fallbackDetails);
+        }
+        const variants = buildKnowledgeUrl({
+            hexId: options.hexId,
+            ftid: options.ftid,
+            placeId: options.placeId,
+            hl: this.hl,
+            gl: this.gl,
+        }).slice(0, 1);
+        for (const url of variants) {
+            try {
+                const data = await this.http.get(url, {
+                    referer: 'https://www.google.com/maps/',
+                    includeOrigin: true,
+                    allowShortBody: true,
+                    noRetry: true,
+                });
+                const entity = extractKnowledgeEntity(data);
+                if (entity.name || entity.description || entity.facts?.length) {
+                    return entity;
+                }
+            }
+            catch {
+                // RPC unavailable — use fallback below
+            }
+        }
+        if (options.fallbackDetails) {
+            return this.fromPlaceDetails(options.fallbackDetails);
+        }
+        return null;
+    }
+    fromPlaceDetails(details) {
+        const entity = extractKnowledgeFromPlaceDetails(details);
+        if (entity.name || entity.description || entity.facts?.length) {
+            return entity;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/services/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/services/knowledge.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,GACjC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAc1D,MAAM,OAAO,gBAAgB;IACnB,IAAI,CAAa;IACjB,EAAE,CAAS;IACX,EAAE,CAAS;IAEnB,YAAY,IAAgB,EAAE,MAAmB;QAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,OAA4B;QACpC,IAAI,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,QAAQ,GAAG,iBAAiB,CAAC;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,EAAE,EAAE,IAAI,CAAC,EAAE;SACZ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEf,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE;oBACpC,OAAO,EAAE,8BAA8B;oBACvC,aAAa,EAAE,IAAI;oBACnB,cAAc,EAAE,IAAI;oBACpB,OAAO,EAAE,IAAI;iBACd,CAAW,CAAC;gBACb,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;gBAC5C,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;oBAC9D,OAAO,MAAM,CAAC;gBAChB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,uCAAuC;YACzC,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,gBAAgB,CAAC,OAAqB;QAC5C,MAAM,MAAM,GAAG,gCAAgC,CAAC,OAAO,CAAC,CAAC;QACzD,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YAC9D,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/services/links.d.ts

@@ -0,0 +1,22 @@
+import { HttpClient } from '../client/http-client.js';
+import { type GMapsConfig } from '../types/common.js';
+import type { ParsedMapsUrl } from '../types/links.js';
+/**
+ * Resolve short links and parse Maps URLs into structured identifiers.
+ *
+ * Short-link expansion uses browser document headers and `?_imcp=1` because
+ * maps.app.goo.gl otherwise serves an interstitial instead of redirecting.
+ */
+export declare class LinksService {
+    private http;
+    private hl;
+    private gl;
+    constructor(http: HttpClient, config: GMapsConfig);
+    /**
+     * Follow redirect chains (and HTML canonical URLs) until a full google.com/maps URL is reached.
+     */
+    expand(shortUrl: string): Promise<string>;
+    /** Expand short links when needed, then parse into a {@link ParsedMapsUrl}. */
+    resolve(url: string): Promise<ParsedMapsUrl>;
+}
+//# sourceMappingURL=links.d.ts.map

package/dist/services/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/services/links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAOtD,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKvD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA+C/C,+EAA+E;IACzE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAQnD"}