gphotos-scraper

A high-performance tool to extract public URLs and metadata from Google Photos shared albums.

🚀 Key Features

• Extreme Performance:
  • Parallel Processing: Fetches photo metadata in concurrent batches using a worker pool pattern.
  • Keep-Alive Connections: Reuses TCP connections via a custom https.Agent with compression (gzip/br).
  • O(1) Lookups: Uses highly optimized data structures for instant ID resolution.
• Zero Bloat:
  • No Cheerio: HTML parsing is done via optimized Regex, removing heavy DOM dependencies.
  • Lightweight: Minimal dependencies for maximum speed.
• Robust & Safe:
  • Defensive Parsing: Gracefully handles malformed responses from Google's RPC.
  • Anti-Hijacking: Automatically cleans Google's security prefixes.
  • Type Safe: Written in 100% TypeScript with strict typing.

📦 Installation

Global CLI

npm install -g gphotos-scraper

Local Module

npm install gphotos-scraper

💻 Usage

CLI

Extract an album to a JSON file:

gphotos-scraper extract <ALBUM_URL> <OUTPUT_FILE.json>

Example:

gphotos-scraper extract https://photos.app.goo.gl/ExampleAlbumID ./data/album.json

Module

Use it programmatically in your Node.js application:

import { extractAlbum } from "gphotos-scraper";

const run = async () => {
    try {
        const album = await extractAlbum('https://photos.app.goo.gl/ExampleAlbumID');
        console.log(`Title: ${album.title}`);
        console.log(`Total Photos: ${album.photos.length}`);
        console.log(album);
    } catch (error) {
        console.error("Failed to extract album:", error);
    }
};

run();

Output Format

{
  "id": "ALBUM_ID",
  "title": "Album Title",
  "url": "https://photos.app.goo.gl/...",
  "photos": [
    {
      "id": "PHOTO_ID",
      "description": "Photo caption",
      "filename": "image.jpg",
      "createdAt": 1654258374000,
      "size": 93425,
      "width": 800,
      "height": 500,
      "mimeType": "image/jpeg",
      "url": "https://lh3.googleusercontent.com/..."
    }
  ]
}

🛠️ Development

This project uses Biome for linting and formatting.

1. Install dependencies:

   nvm use
   npm install

2. Build:

   npm run build

3. Lint & Format:

   npm run lint:fix

📄 License

MIT