google-retail-api-client

Google Retail API Client

A TypeScript client for the Google Retail API, providing easy access to search, recommendations, and predictions.

Features

• 🔍 Full Retail Search API support
• 🎯 Product recommendations
• 🔮 Predictions
• 📦 TypeScript support
• 🔐 Service Account authentication
• 🚀 Promise-based API

Installation

npm install google-retail-api-client

Authentication

This library requires a Google Cloud Service Account with appropriate permissions for the Retail API.

Getting Service Account Credentials

1. Go to the Google Cloud Console
2. Navigate to "IAM & Admin" > "Service Accounts"
3. Click "Create Service Account"
4. Grant the service account the following roles:
   • roles/retail.admin or appropriate Retail API roles
5. Create and download the JSON key file
6. The JSON file will contain your credentials in this format:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id"
}

Usage

Initializing the Client

import { RetailClient } from "google-retail-api-client";
const client = new RetailClient({
  credentials: {
    // Your service account credentials
    type: "service_account",
    project_id: "your-project-id",
    private_key: "your-private-key",
    client_email: "your-client-email",
    // ... other credential fields
  },
  location: "global", // optional, defaults to "global"
  catalogId: "default_catalog", // optional, defaults to "default_catalog"
});

Searching Products

// Basic search
const results = await client.search({
  query: "blue jeans",
  pageSize: 10,
});
// Advanced search with filters
const filteredResults = await client.search({
  query: "t-shirt",
  filter: "price.value > 20 AND price.value < 50",
  pageSize: 20,
  offset: 0,
  orderBy: "price desc",
});

Getting Recommendations

// Get recommendations for a specific product
const recommendations = await client.getPredictions({
  productId: "product123",
  pageSize: 12,
  filter: "availability: IN_STOCK",
});
// Get general recommendations
const homePageRecommendations = await client.getPredictions({
  pageSize: 12,
  eventType: "home-page-view",
});

Error Handling

The client throws RetailApiError for any API or authentication errors:

try {
  const results = await client.search({ query: "shoes" });
} catch (error) {
  if (error instanceof RetailApiError) {
    console.error(error.message); // Error message
    console.error(error.code); // HTTP status code
    console.error(error.details); // Additional error details
  }
}

Security Considerations

⚠️ Important Security Notes:

1. Never commit service account credentials to version control
2. Store credentials securely using environment variables or secret management systems
3. Follow the principle of least privilege when assigning roles to the service account
4. Regularly rotate service account keys
5. Never expose service account credentials in client-side/browser code

API Reference

For detailed API documentation, please refer to the Google Retail API Documentation.

License

MIT