@xapp/stentor-service-google-places

Google Places Service

Service for integrating with Google Places API, built on Stentor's FetchService.

Installation

npm install @xapp/stentor-service-google-places

Usage

Basic Setup with API Key

import { GooglePlacesService } from "@xapp/stentor-service-google-places";

const service = new GooglePlacesService({
    apiKey: "your-google-places-api-key"
});

Setup with Authentication Function

import { GooglePlacesService } from "@xapp/stentor-service-google-places";

const service = new GooglePlacesService({
    authenticate: async () => {
        // Your authentication logic here
        return { apiKey: await getApiKeyFromSomewhere() };
    }
});

Get Place Details

// Get basic place details
const placeDetails = await service.getPlaceDetails("ChIJN1t_tDeuEmsRUsoyG83frY4");

// Get specific fields only
const placeDetails = await service.getPlaceDetails(
    "ChIJN1t_tDeuEmsRUsoyG83frY4",
    ["name", "formatted_address", "geometry", "photos"]
);

API Reference

GooglePlacesService

Constructor Options

• apiKey?: string - Google Places API key
• authenticate?: () => Promise<{ apiKey: string }> - Function that returns API key
• urlBase?: string - Custom API base URL (defaults to Google Places API)

Methods

getPlaceDetails(placeId: string, fields?: string[]): Promise<GooglePlaceDetails>

Retrieves detailed information about a place.

Parameters:

• placeId - The unique identifier for a place
• fields - Optional array of fields to return (reduces API cost)

Returns: Promise resolving to place details

Available Fields:

• Basic: place_id, name, formatted_address, geometry
• Contact: formatted_phone_number, international_phone_number, website
• Atmosphere: photos, rating, user_ratings_total, reviews, price_level
• Details: opening_hours, business_status, types, vicinity

Error Handling

The service throws descriptive errors for:

• Missing API key or authentication function
• HTTP errors (4xx/5xx status codes)
• Google Places API errors (INVALID_REQUEST, OVER_QUERY_LIMIT, etc.)

Types

All TypeScript interfaces are exported for use in your application:

import { 
    GooglePlaceDetails, 
    GooglePlaceDetailsResponse,
    GooglePlacesGeometry,
    GooglePlacesPhoto,
    GooglePlacesReview
} from "@xapp/stentor-service-google-places";