# nikhilsearch/serp-scraper-gsheet architecture

> Architecture diagram of the GitHub repository nikhilsearch/serp-scraper-gsheet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhilsearch/serp-scraper-gsheet
- Repository: https://github.com/nikhilsearch/serp-scraper-gsheet

## Overview

##### Project type and purpose
- This is a single-file Google Apps Script project (`scraping.js`) that runs inside Google Sheets.
- Its purpose is to let users call a custom function (`IMPORTFROMGOOGLE`) in a sheet to fetch Google Search results via the Custom Search API and write them back into the sheet for SEO analysis.

##### File structure
- Top-level:
- LICENSE – open-source license
- README.md – explains purpose, usage, config
- scraping.js – the only code file, containing the Apps Script logic
- No separate frontend/backend directories; the “frontend” is the Google Sheets UI, the “backend” is the Apps Script runtime and the external API.

##### README for additional insights
- It describes:
- Setup steps in Google Sheets → Extensions → Apps Script
- Where to insert API Key and CSE ID
- How to call the custom function from a cell, passing query and date range

a. Main components
- Google Sheets (UI layer, where user enters formula and sees output)
- Google Apps Script runtime (managed by Google, executes `scraping.js`)
- Google Custom Search API (external service)
- Configuration (API Key & Custom Search Engine ID)
b. Relationships and data flow
1. User types `=IMPORTFROMGOOGLE(query, dateRange)` into a cell.
2. Google Sheets invokes the Apps Script function in `scraping.js`.
3. The script reads the user’s parameters and embedded credentials.
4. The script makes an HTTP GET request to the Custom Search API endpoint.
5. The API returns JSON search results.
6. The script parses the JSON and writes a range of cells back into the sheet.
c. Architectural patterns & principles
- Serverless/function-as-a-service: Apps Script code runs on demand.
- Single responsibility: one function fetches and writes search data.
- External API integration: clear boundary between script and Google’s API.
d. Key technologies/libraries
- Google Apps Script (JavaScript on Google’s servers)
- Google Sheets custom functions
- Google Custom Search JSON API
- Standard UrlFetchApp service for HTTP requests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interface"
        Sheets["Google Sheets UI / Data Sink & Trigger"]:::ui
    end

    %% Runtime Layer
    subgraph "Apps Script Runtime"
        Script["Apps Script Runtime\n(scraping.js)"]:::runtime
        Config["API Key + CSE ID"]:::config
    end

    %% External Service
    External["Custom Search API"]:::external

    %% Documentation
    subgraph "Project Documentation"
        README["README.md"]:::doc
        LICENSE["LICENSE"]:::doc
    end

    %% Data Flow
    Sheets -->|"IMPORTFROMGOOGLE(query, dateRange)"| Script
    Config -.->|"Provides Credentials"| Script
    Script -->|"HTTP GET / JSON response"| External
    External -->|"JSON search results"| Script
    Script -->|"Write results to cells"| Sheets

    %% Click Events
    click Script "https://github.com/nikhilsearch/serp-scraper-gsheet/blob/main/scraping.js"
    click README "https://github.com/nikhilsearch/serp-scraper-gsheet/blob/main/README.md"
    click LICENSE "https://github.com/nikhilsearch/serp-scraper-gsheet/tree/main/LICENSE"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef doc fill:#FFE4E1,stroke:#333,stroke-width:1px
```
