googlemaps-kit 0.4.0 → 0.6.0

package/dist/services/mobility.js

@@ -0,0 +1,307 @@
+import { SearchService } from './search.js';
+import { PlacesService } from './places.js';
+import { extractEvChargers, extractParkingAvailability, extractParkingPrice, requireBikeAvailability } from '../parsers/mobility.js';
+import { haversineMeters } from '../utils/geo.js';
+import { GMapsError } from '../types/common.js';
+import { pooledMap } from '../utils/async.js';
+/**
+ * Mobility POI services: EV charging, parking and bike-share availability.
+ */
+/**
+ * Maps has no dedicated parking RPC — parking lots are ordinary places, and the
+ * web client finds them with a categorical text search. These queries mirror the
+ * category chips the Maps UI uses.
+ */
+const TYPE_QUERIES = {
+    surface: 'surface parking lot',
+    garage: 'parking garage',
+    valet: 'valet parking',
+    street: 'street parking',
+    lot: 'parking lot',
+};
+/** Category label → ParkingType, matched loosely against Google's category strings. */
+function classify(result) {
+    const label = `${result.category ?? ''} ${result.categories?.join(' ') ?? ''} ${result.name}`.toLowerCase();
+    if (label.includes('valet'))
+        return 'valet';
+    if (label.includes('garage') || label.includes('multi-storey') || label.includes('multi storey')) {
+        return 'garage';
+    }
+    if (label.includes('street'))
+        return 'street';
+    if (label.includes('surface'))
+        return 'surface';
+    return 'lot';
+}
+export class ParkingService {
+    search_;
+    places;
+    constructor(http, config) {
+        this.search_ = new SearchService(http, config);
+        this.places = new PlacesService(http, config);
+    }
+    /**
+     * Parking near a point, from a categorical place search.
+     *
+     * `radiusMeters` filters the returned rows client-side — Maps biases search by
+     * viewport rather than accepting a hard radius.
+     */
+    async search(options) {
+        const queries = options.type?.length
+            ? options.type.map((t) => TYPE_QUERIES[t])
+            : ['parking'];
+        const batches = await Promise.all(queries.map((query) => this.search_.searchText({
+            query,
+            location: options.location,
+            limit: 20,
+            fieldMask: 'enterprise',
+        })));
+        const seen = new Set();
+        const parkings = [];
+        for (const batch of batches) {
+            for (const row of batch.places) {
+                const id = row.hexId ?? row.placeId;
+                const lat = row.lat ?? row.latitude;
+                const lng = row.lng ?? row.longitude;
+                if (!id || lat == null || lng == null || seen.has(id))
+                    continue;
+                seen.add(id);
+                const distanceMeters = haversineMeters(options.location.lat, options.location.lng, lat, lng);
+                if (options.radiusMeters != null && distanceMeters > options.radiusMeters)
+                    continue;
+                parkings.push({
+                    id,
+                    name: row.name,
+                    type: classify(row),
+                    lat,
+                    lng,
+                    distanceMeters,
+                    rating: row.rating,
+                    reviews: row.reviewCount,
+                });
+            }
+        }
+        if (options.sort === 'price') {
+            parkings.sort((a, b) => (a.hourlyRate ?? Infinity) - (b.hourlyRate ?? Infinity));
+        }
+        else if (options.sort === 'availability') {
+            parkings.sort((a, b) => (b.availableSpaces ?? -1) - (a.availableSpaces ?? -1));
+        }
+        else {
+            parkings.sort((a, b) => a.distanceMeters - b.distanceMeters);
+        }
+        return parkings;
+    }
+    /**
+     * Live space counts for one parking place, read from its place preview.
+     *
+     * Google only publishes occupancy for a small number of operator-integrated
+     * garages; throws {@link GMapsError} when the place carries no counts.
+     */
+    async getAvailability(parkingId) {
+        const { data } = await this.places.fetchPreview({ hexId: parkingId, mode: 'live' });
+        const availability = extractParkingAvailability(data, parkingId);
+        if (!availability) {
+            throw new GMapsError(`No live availability published for parking ${parkingId} — Google exposes space counts only for operator-integrated garages.`);
+        }
+        return availability;
+    }
+    /**
+     * Posted rates for one parking place, read from its place preview.
+     *
+     * Throws {@link GMapsError} when the place carries no pricing block.
+     */
+    async getPricing(parkingId) {
+        const { data } = await this.places.fetchPreview({ hexId: parkingId, mode: 'live' });
+        const price = extractParkingPrice(data, parkingId);
+        if (!price) {
+            throw new GMapsError(`No pricing published for parking ${parkingId}.`);
+        }
+        return price;
+    }
+}
+/**
+ * Maps has no dedicated EV RPC. Charging stations are ordinary places found via
+ * categorical text search; connector type, power, and plug count come from each
+ * station's place preview.
+ */
+const CONNECTOR_QUERIES = {
+    supercharger: 'tesla supercharger',
+    tesla: 'tesla charging station',
+    ccs: 'ccs ev charging station',
+    chademo: 'chademo ev charging station',
+    type2: 'type 2 ev charging station',
+    ac: 'ac ev charging station',
+};
+const ENRICH_CONCURRENCY = 5;
+export class EvChargingService {
+    search_;
+    places;
+    constructor(http, config) {
+        this.search_ = new SearchService(http, config);
+        this.places = new PlacesService(http, config);
+    }
+    /**
+     * Charging stations near a point, with their advertised connectors.
+     *
+     * Runs one place search, then a bounded set of place-preview calls to read the
+     * connector block for each hit. `radiusMeters` filters client-side — Maps
+     * biases search by viewport rather than accepting a hard radius.
+     */
+    async findCharging(options) {
+        const queries = options.connectorTypes?.length
+            ? options.connectorTypes.map((t) => CONNECTOR_QUERIES[t])
+            : ['ev charging station'];
+        const batches = await Promise.all(queries.map((query) => this.search_.searchText({
+            query,
+            location: options.location,
+            limit: 20,
+            fieldMask: 'enterprise',
+        })));
+        const seen = new Set();
+        const candidates = [];
+        for (const batch of batches) {
+            for (const row of batch.places) {
+                const id = row.hexId ?? row.placeId;
+                const lat = row.lat ?? row.latitude;
+                const lng = row.lng ?? row.longitude;
+                if (!id || lat == null || lng == null || seen.has(id))
+                    continue;
+                seen.add(id);
+                const distanceMeters = haversineMeters(options.location.lat, options.location.lng, lat, lng);
+                if (options.radiusMeters != null && distanceMeters > options.radiusMeters)
+                    continue;
+                candidates.push({
+                    id,
+                    name: row.name,
+                    operator: row.name,
+                    lat,
+                    lng,
+                    distanceMeters,
+                    chargers: [],
+                    address: row.address,
+                    phone: row.internationalPhone ?? row.phone,
+                    website: row.website,
+                });
+            }
+        }
+        const enriched = await pooledMap(candidates, ENRICH_CONCURRENCY, async (station) => {
+            try {
+                const preview = await this.places.fetchPreview({
+                    hexId: station.id,
+                    name: station.name,
+                    lat: station.lat,
+                    lng: station.lng,
+                    mode: 'live',
+                });
+                let chargers = extractEvChargers(preview.data, station.id);
+                if (chargers.length === 0) {
+                    const rich = await this.places.fetchPreview({
+                        hexId: station.id,
+                        name: station.name,
+                        lat: station.lat,
+                        lng: station.lng,
+                        mode: 'rich',
+                    });
+                    chargers = extractEvChargers(rich.data, station.id);
+                }
+                return { ...station, chargers };
+            }
+            catch {
+                // A preview failure costs connector detail, not the station itself.
+                return station;
+            }
+        });
+        const filtered = options.minPower == null
+            ? enriched
+            : enriched.filter((s) => s.chargers.some((c) => (c.power ?? 0) >= options.minPower));
+        if (options.sort === 'availability') {
+            filtered.sort((a, b) => totalPlugs(b) - totalPlugs(a));
+        }
+        else if (options.sort === 'price') {
+            // No pricing is published on any Maps surface — fall back to distance.
+            filtered.sort((a, b) => a.distanceMeters - b.distanceMeters);
+        }
+        else {
+            filtered.sort((a, b) => a.distanceMeters - b.distanceMeters);
+        }
+        return filtered;
+    }
+    /**
+     * Not available.
+     *
+     * Google publishes a per-plug status code in the place preview but documents
+     * no mapping to a charging state, and exposes no availability RPC. Use
+     * {@link findCharging} for connector type, power, and plug count.
+     *
+     * @throws {GMapsError} always
+     */
+    async getStatus(chargerId) {
+        throw new GMapsError(`Live charger availability is not exposed by any public Maps surface (charger ${chargerId}). ` +
+            'findCharging() returns connector type, power, and plug count.');
+    }
+    /**
+     * Not available.
+     *
+     * Charging tariffs are not carried in Maps place data or any batchexecute
+     * service the web client calls.
+     *
+     * @throws {GMapsError} always
+     */
+    async getPricing(stationId) {
+        throw new GMapsError(`Charging pricing is not exposed by any public Maps surface (station ${stationId}).`);
+    }
+}
+function totalPlugs(station) {
+    return station.chargers.reduce((sum, c) => sum + (c.totalCount ?? 0), 0);
+}
+/**
+ * Bike-share dock availability.
+ *
+ * Reads the live operator-feed block from the station's place preview
+ * (placeData[133][0], verified anonymously across preview modes and
+ * operators such as Citi Bike NYC and Santander Cycles London).
+ */
+export class BikeShareService {
+    places;
+    constructor(http, config = {}) {
+        this.places = new PlacesService(http, config);
+    }
+    /**
+     * Live dock availability for one bike-share station.
+     * Accepts a hexId (from search hits or `parseMapsUrl`) or name/coords/ftid hints.
+     */
+    async getAvailability(options) {
+        if (!options.hexId) {
+            throw new GMapsError('getAvailability requires a station hexId — resolve the station first via search or parseMapsUrl.');
+        }
+        const preview = await this.places.fetchPreview({
+            hexId: options.hexId,
+            name: options.name,
+            lat: options.lat,
+            lng: options.lng,
+            ftid: options.ftid,
+            mode: options.mode ?? 'live',
+        });
+        return requireBikeAvailability(preview.data);
+    }
+    /** Availability for several stations in parallel (bounded). */
+    async getAvailabilityMany(stations, concurrency = 5) {
+        const results = new Array(stations.length).fill(null);
+        let cursor = 0;
+        const runners = Array.from({ length: Math.min(concurrency, stations.length) }, async () => {
+            while (cursor < stations.length) {
+                const index = cursor++;
+                try {
+                    results[index] = await this.getAvailability(stations[index]);
+                }
+                catch {
+                    results[index] = null;
+                }
+            }
+        });
+        await Promise.all(runners);
+        return results;
+    }
+}
+//# sourceMappingURL=mobility.js.map

package/dist/services/mobility.js.map

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

package/dist/services/nearby-search.d.ts

@@ -0,0 +1,32 @@
+import type { GMapsConfig, LocationRef, SearchResult } from '../types/common.js';
+import { HttpClient } from '../client/http-client.js';
+export interface NearbySearchOptions {
+    /** Places API (New) includedTypes — at least one required. */
+    includedTypes: string[];
+    location: LocationRef;
+    /** Search radius in metres (client-side filter after search). */
+    radiusMeters?: number;
+    maxResultCount?: number;
+    hl?: string;
+    gl?: string;
+    rankPreference?: 'DISTANCE' | 'POPULARITY';
+}
+export interface NearbySearchResult {
+    places: SearchResult[];
+    /** Mirrors Places API (New) — offset token when more pages exist. */
+    nextPageToken?: string;
+}
+export declare class NearbySearchService {
+    private search;
+    private hl;
+    private gl;
+    constructor(http: HttpClient, config: GMapsConfig);
+    /**
+     * Nearby Search — categorical place search biased to a point.
+     *
+     * Consumer Maps has no type-only RPC; this mirrors the UI by running one
+     * text search per included type and merging/deduping by place id.
+     */
+    searchNearby(options: NearbySearchOptions): Promise<NearbySearchResult>;
+}
+//# sourceMappingURL=nearby-search.d.ts.map

package/dist/services/nearby-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearby-search.d.ts","sourceRoot":"","sources":["../../src/services/nearby-search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAgCtD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,WAAW,CAAC;IACtB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAsD9E"}

package/dist/services/nearby-search.js

@@ -0,0 +1,85 @@
+import { SearchService } from './search.js';
+import { haversineMeters } from '../utils/geo.js';
+/** Maps includedTypes values to categorical search queries the consumer uses. */
+const TYPE_QUERY_MAP = {
+    restaurant: 'restaurant',
+    cafe: 'cafe',
+    bar: 'bar',
+    bakery: 'bakery',
+    hotel: 'hotel',
+    gas_station: 'gas station',
+    parking: 'parking',
+    hospital: 'hospital',
+    pharmacy: 'pharmacy',
+    school: 'school',
+    university: 'university',
+    bank: 'bank',
+    atm: 'atm',
+    supermarket: 'supermarket',
+    grocery_store: 'grocery store',
+    shopping_mall: 'shopping mall',
+    ev_charging_station: 'EV charging station',
+    train_station: 'train station',
+    bus_station: 'bus station',
+    airport: 'airport',
+    museum: 'museum',
+    park: 'park',
+    gym: 'gym',
+    dentist: 'dentist',
+    doctor: 'doctor',
+};
+export class NearbySearchService {
+    search;
+    hl;
+    gl;
+    constructor(http, config) {
+        this.search = new SearchService(http, config);
+        this.hl = config.hl ?? 'en';
+        this.gl = config.gl ?? 'us';
+    }
+    /**
+     * Nearby Search — categorical place search biased to a point.
+     *
+     * Consumer Maps has no type-only RPC; this mirrors the UI by running one
+     * text search per included type and merging/deduping by place id.
+     */
+    async searchNearby(options) {
+        if (options.includedTypes.length === 0) {
+            return { places: [] };
+        }
+        const origin = await this.search.resolveBias(options.location);
+        const radius = options.radiusMeters ?? 5_000;
+        const limit = options.maxResultCount ?? 20;
+        const queries = options.includedTypes.map((type) => TYPE_QUERY_MAP[type] ?? type.replace(/_/g, ' '));
+        const batches = await Promise.all(queries.map((query) => this.search.searchText({
+            query,
+            location: origin,
+            limit,
+            fieldMask: 'enterprise',
+        })));
+        const seen = new Set();
+        const scored = [];
+        for (const batch of batches) {
+            for (const row of batch.places) {
+                const id = row.hexId ?? row.placeId;
+                const lat = row.lat ?? row.latitude;
+                const lng = row.lng ?? row.longitude;
+                if (!id || lat == null || lng == null || seen.has(id))
+                    continue;
+                const distance = haversineMeters(origin.lat, origin.lng, lat, lng);
+                if (distance > radius)
+                    continue;
+                seen.add(id);
+                scored.push({ place: row, distance });
+            }
+        }
+        if (options.rankPreference === 'POPULARITY') {
+            scored.sort((a, b) => (b.place.reviewCount ?? 0) - (a.place.reviewCount ?? 0));
+        }
+        else {
+            scored.sort((a, b) => a.distance - b.distance);
+        }
+        return { places: scored.slice(0, limit).map((entry) => entry.place) };
+    }
+}
+//# sourceMappingURL=nearby-search.js.map

package/dist/services/nearby-search.js.map

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

package/dist/services/panorama.d.ts

@@ -1,6 +1,6 @@
 import { HttpClient } from '../client/http-client.js';
 import type { GMapsConfig } from '../types/common.js';
-import type { PanoramaGetOptions, PanoramaImageOptions, PanoramaLocationOptions, PanoramaMetadata, PanoramaRef, PanoramaSearchOptions } from '../types/panorama.js';
+import type { PanoramaGetOptions, PanoramaImageOptions, PanoramaLocationOptions, PanoramaMetadata, PanoramaRef, PanoramaSearchOptions, PanoramaStaticImageLocationOptions, PanoramaStaticImageOptions, PanoramaStaticImageResult, PanoramaTileGrid } from '../types/panorama.js';
 export declare class PanoramaService {
     private http;
     private hl;
@@ -29,11 +29,29 @@ export declare class PanoramaService {
     private rankByDistance;
     /** Fetch full metadata for a panorama id; null when Google returns the stub response. */
     get(panoId: string, options?: PanoramaGetOptions): Promise<PanoramaMetadata | null>;
+    private getPhotometaAsBytes;
     /** Resolve the closest panorama near a point, then fetch its full metadata. */
     getByLocation(lat: number, lng: number, options?: PanoramaLocationOptions): Promise<PanoramaMetadata | null>;
+    /**
+     * Build the full equirectangular tile manifest for a panorama.
+     *
+     * Street View has no video stream — the web client renders by fetching these
+     * tiles, so this grid is the complete imagery contract. Geometry comes from
+     * photometa (`tileSizes` count, `maxTileDimensions`, `tileFaceSize`); pass
+     * previously fetched metadata to avoid a second request. Without it the
+     * observed default pyramid (4 levels, 8192×4096 top, 512px faces) is used.
+     */
+    getTileGrid(panoId: string, metadata?: PanoramaMetadata | null): Promise<PanoramaTileGrid>;
     /** Build a Street View thumbnail URL (no network I/O). */
     buildThumbnailUrl(options: PanoramaImageOptions): string;
     /** Build a Street View tile URL (no network I/O). */
     buildTileUrl(options: PanoramaImageOptions): string;
+    /**
+     * Fetch a static Street View JPEG (Maps Platform "Static Street View").
+     * Uses streetviewpixels /thumbnail — not /maps/api/streetview.
+     */
+    fetchStaticImage(options: PanoramaStaticImageOptions): Promise<PanoramaStaticImageResult>;
+    /** Resolve the nearest panorama, then fetch its static thumbnail JPEG. */
+    fetchStaticImageByLocation(lat: number, lng: number, options?: PanoramaStaticImageLocationOptions): Promise<PanoramaStaticImageResult | null>;
 }
 //# sourceMappingURL=panorama.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"panorama.d.ts","sourceRoot":"","sources":["../../src/services/panorama.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAatD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAkB9B,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAWxE,sFAAsF;YACxE,eAAe;IAgD7B,iEAAiE;YACnD,mBAAmB;IAgCjC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAoBtB,yFAAyF;IACnF,GAAG,CACP,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAenC,+EAA+E;IACzE,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAuBnC,0DAA0D;IAC1D,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;IAUxD,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;CAQpD"}
+{"version":3,"file":"panorama.d.ts","sourceRoot":"","sources":["../../src/services/panorama.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAatD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,kCAAkC,EAClC,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAyB9B,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAMjD;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAWxE,sFAAsF;YACxE,eAAe;IAgD7B,iEAAiE;YACnD,mBAAmB;IAgCjC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAoBtB,yFAAyF;IACnF,GAAG,CACP,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAqBrB,mBAAmB;IASjC,+EAA+E;IACzE,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAuBnC;;;;;;;;OAQG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2ChG,0DAA0D;IAC1D,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;IAUxD,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;IASnD;;;OAGG;IACG,gBAAgB,CACpB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC;IA2BrC,0EAA0E;IACpE,0BAA0B,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,kCAAkC,GAC3C,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;CAmB7C"}

package/dist/services/panorama.js

@@ -2,9 +2,15 @@ import { extractCoveragePanoramas, extractNearbyPanoramas, extractPanoramaMetada
 import { buildCoverageTileUrl, buildListEntityPhotosUrl, buildPhotometaUrl, buildThumbnailUrl, buildTileUrl, } from '../rpc/panorama-pb.js';
 import { GMapsNetworkError, GMapsPhotosBlockedError } from '../types/common.js';
 import { haversineMeters, webMercatorTile } from '../utils/geo.js';
+import { parseGoogleResponse } from '../utils/payload.js';
 const DEFAULT_RADIUS_METERS = 300;
 /** Coverage tiles only answer at zoom 17 — zoom 18 returns HTTP 400. */
 const COVERAGE_ZOOM = 17;
+/** Observed default equirectangular pyramid when photometa omits tile geometry. */
+const DEFAULT_PANO_LEVELS = 4;
+const DEFAULT_PANO_MAX_WIDTH = 8192;
+const DEFAULT_PANO_MAX_HEIGHT = 4096;
+const DEFAULT_PANO_FACE = 512;
 /** A z17 tile spans roughly this far, so wider searches need the neighbouring tiles. */
 const COVERAGE_TILE_SPAN_METERS = 305;
 /** Street View pano ids from listentityphotos — excludes session tokens and numeric photo ids. */
@@ -122,13 +128,27 @@ export class PanoramaService {
     async get(panoId, options) {
         const hl = options?.hl ?? this.hl;
         const gl = options?.gl ?? this.gl;
-        const url = buildPhotometaUrl({ panoId, hl, gl });
-        const data = await this.http.get(url, {
+        const includeDepth = options?.includeDepth ?? false;
+        const url = buildPhotometaUrl({ panoId, hl, gl, includeDepth });
+        // The depth raster rides inside the JSON as raw bytes, so that response has
+        // to be read as latin1; decoding it as UTF-8 replaces every byte above 0x7f
+        // and leaves an unreadable WebP.
+        const data = includeDepth
+            ? await this.getPhotometaAsBytes(url)
+            : await this.http.get(url, {
+                referer: 'https://www.google.com/maps/',
+                includeOrigin: true,
+                allowShortBody: true,
+            });
+        return extractPanoramaMetadata(data, { raw: options?.raw });
+    }
+    async getPhotometaAsBytes(url) {
+        const { bytes } = await this.http.getBytes(url, {
             referer: 'https://www.google.com/maps/',
             includeOrigin: true,
             allowShortBody: true,
         });
-        return extractPanoramaMetadata(data, { raw: options?.raw });
+        return parseGoogleResponse(Buffer.from(bytes).toString('latin1'));
     }
     /** Resolve the closest panorama near a point, then fetch its full metadata. */
     async getByLocation(lat, lng, options) {
@@ -152,6 +172,46 @@ export class PanoramaService {
         }
         return null;
     }
+    /**
+     * Build the full equirectangular tile manifest for a panorama.
+     *
+     * Street View has no video stream — the web client renders by fetching these
+     * tiles, so this grid is the complete imagery contract. Geometry comes from
+     * photometa (`tileSizes` count, `maxTileDimensions`, `tileFaceSize`); pass
+     * previously fetched metadata to avoid a second request. Without it the
+     * observed default pyramid (4 levels, 8192×4096 top, 512px faces) is used.
+     */
+    async getTileGrid(panoId, metadata) {
+        const levelCount = metadata?.tileSizes?.length ?? DEFAULT_PANO_LEVELS;
+        const [maxWidth, maxHeight] = metadata?.maxTileDimensions ?? [
+            DEFAULT_PANO_MAX_WIDTH,
+            DEFAULT_PANO_MAX_HEIGHT,
+        ];
+        const [faceWidth, faceHeight] = metadata?.tileFaceSize ?? [
+            DEFAULT_PANO_FACE,
+            DEFAULT_PANO_FACE,
+        ];
+        const levels = [];
+        const urls = [];
+        for (let zoom = 0; zoom < levelCount; zoom++) {
+            const divisor = 2 ** (levelCount - 1 - zoom);
+            const width = Math.min(maxWidth, Math.max(faceWidth, Math.ceil(maxWidth / divisor)));
+            const height = Math.min(maxHeight, Math.max(faceHeight, Math.ceil(maxHeight / divisor)));
+            const cols = Math.max(1, Math.ceil(width / faceWidth));
+            const rows = Math.max(1, Math.ceil(height / faceHeight));
+            levels.push({ zoom, cols, rows, width, height });
+            const gridRows = [];
+            for (let y = 0; y < rows; y++) {
+                const row = [];
+                for (let x = 0; x < cols; x++) {
+                    row.push(buildTileUrl({ panoId, x, y, zoom }));
+                }
+                gridRows.push(row);
+            }
+            urls.push(gridRows);
+        }
+        return { panoId, levels, urls };
+    }
     /** Build a Street View thumbnail URL (no network I/O). */
     buildThumbnailUrl(options) {
         return buildThumbnailUrl({
@@ -171,5 +231,53 @@ export class PanoramaService {
             zoom: options.zoom,
         });
     }
+    /**
+     * Fetch a static Street View JPEG (Maps Platform "Static Street View").
+     * Uses streetviewpixels /thumbnail — not /maps/api/streetview.
+     */
+    async fetchStaticImage(options) {
+        const width = options.width ?? 640;
+        const height = options.height ?? 480;
+        const url = buildThumbnailUrl({
+            panoId: options.panoId,
+            width,
+            height,
+            pitch: options.pitch,
+            yaw: options.yaw,
+        });
+        const { bytes, contentType } = await this.http.getBytes(url, {
+            referer: 'https://www.google.com/maps/',
+            includeOrigin: true,
+            minBytes: 100,
+        });
+        return {
+            bytes,
+            contentType,
+            width,
+            height,
+            panoId: options.panoId,
+            url,
+        };
+    }
+    /** Resolve the nearest panorama, then fetch its static thumbnail JPEG. */
+    async fetchStaticImageByLocation(lat, lng, options) {
+        const nearby = await this.findNearby({
+            lat,
+            lng,
+            radiusMeters: options?.radiusMeters,
+            hl: options?.hl,
+            gl: options?.gl,
+        });
+        const ref = nearby.find((entry) => isLikelyStreetViewPanoId(entry.panoId));
+        if (!ref)
+            return null;
+        return this.fetchStaticImage({
+            panoId: ref.panoId,
+            width: options?.width,
+            height: options?.height,
+            pitch: options?.pitch ?? ref.pitch,
+            yaw: options?.yaw ?? ref.heading,
+        });
+    }
 }
 //# sourceMappingURL=panorama.js.map