AgriciDaniel/claude-blog / skills/blog-google
blog-google
VerifiedCredentialed Google API calls for a blog: PageSpeed Insights, CrUX history, Search Console performance and URL Inspection, GA4 organic traffic, Cloud NLP entities, YouTube video search, Google Ads Keyword Planner, and the Indexing API (job and livestream pages only). Uses the user's Google credentials, quotas, and sometimes billing, and asks for consent before the first call. Runs only on an explicit request: /blog google, "run PageSpeed on this blog URL", "pull my Search Console data", "inspect this URL's index status", "set up Google API credentials". Shares config with claude-seo at ~/.config/claude-seo/google-api.json.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.2 KB |
| assets/templates/cwv-audit-report.md | markdown | 1.6 KB |
| assets/templates/gsc-performance-report.md | markdown | 1.2 KB |
| assets/templates/indexation-status-report.md | markdown | 1.1 KB |
| references/api-reference.md | markdown | 9.3 KB |
| references/auth-setup.md | markdown | 7.1 KB |
| references/rate-limits-quotas.md | markdown | 4.6 KB |
| references/search-currentness.md | markdown | 12.5 KB |
| scripts/__init__.py | script | 0 B |
| scripts/crux_history.py | script | 11.0 KB |
| scripts/ga4_report.py | script | 17.0 KB |
| scripts/google_auth.py | script | 42.0 KB |
| scripts/google_report.py | script | 37.4 KB |
| scripts/gsc_inspect.py | script | 19.3 KB |
| scripts/gsc_query.py | script | 15.6 KB |
| scripts/indexing_notify.py | script | 15.1 KB |
| scripts/keyword_planner.py | script | 12.0 KB |
| scripts/nlp_analyze.py | script | 19.3 KB |
| scripts/pagespeed_check.py | script | 23.0 KB |
| scripts/requirements.lock | other | 103.0 KB |
| scripts/requirements.txt | manifest | 909 B |
| scripts/run.py | script | 4.2 KB |
| scripts/runtime_paths.py | script | 2.6 KB |
| scripts/setup_environment.py | script | 7.0 KB |
| scripts/youtube_search.py | script | 14.6 KB |
references/api-reference.md
View on GitHub# Blog Google - API Reference
Consolidated reference for all Google APIs used by the blog-google skill.
---
## PageSpeed Insights v5
**Endpoint:** `GET https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed` (canonical)
Legacy hostname also works: `https://www.googleapis.com/pagespeedonline/v5/runPagespeed`
| Param | Type | Description |
|-------|------|-------------|
| `url` | string | Required. URL to analyze |
| `category` | string | `ACCESSIBILITY`, `BEST_PRACTICES`, `PERFORMANCE`, `SEO` (can specify multiple) |
| `strategy` | string | `DESKTOP` or `MOBILE` (default) |
| `key` | string | API key (optional but recommended) |
Response contains `loadingExperience` (URL-level CrUX), `originLoadingExperience` (origin CrUX), and `lighthouseResult` with category scores and audit details.
**Note:** Google has signaled intent to remove CrUX from PSI, but as of April 2026 CrUX field
data (`loadingExperience`, `originLoadingExperience`) is still returned in PSI responses. The
standalone CrUX API is the recommended long-term solution for field data; use PSI primarily
for Lighthouse lab scores.
---
## CrUX API (Daily)
**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryRecord?key={API_KEY}`
```json
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"]
}
```
- `origin` and `url` are mutually exclusive. Use `origin` for site-wide, `url` for a specific page.
- `formFactor`: `DESKTOP`, `PHONE`, `TABLET` (omit for all).
- Each metric returns `histogram` (density buckets), `percentiles.p75`, and `category`.
- **CLS p75 is a string** (e.g., `"0.05"` not `0.05`). Always parse as float.
- 404 = insufficient Chrome traffic (not an auth error).
- Updated daily on a best-effort basis with ~2-day lag. No guaranteed update time; timezone is PST.
---
## CrUX History API (Weekly)
**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key={API_KEY}`
Same request format as CrUX API. Returns up to **40 weekly collection periods** (~10 months)
as timeseries arrays (`p75s[]`, `densities[]`). Default is 25; configurable via
`collectionPeriodCount` parameter (range: 1-40). Use `crux_history.py --periods N`.
- Updated **Mondays** ~04:00 UTC.
- Each period = 28-day rolling average ending on a Sunday.
- Watch for `"NaN"` strings in densities and `null` in percentiles for ineligible periods.
---
## Core Web Vitals Thresholds
Current as of March 2026. INP replaced FID on March 12, 2024.
**Core Web Vitals (the 3 official CWV):**
| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| **LCP** | ≤ 2,500ms | 2,500-4,000ms | > 4,000ms |
| **INP** | ≤ 200ms | 200-500ms | > 500ms |
| **CLS** | ≤ 0.1 | 0.1-0.25 | > 0.25 |
**Diagnostic metrics (not CWV - informational only):**
| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| **FCP** | ≤ 1,800ms | 1,800-3,000ms | > 3,000ms |
| **TTFB** | ≤ 800ms | 800-1,800ms | > 1,800ms |
---
## GSC Search Analytics
**Endpoint:** `POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query`
### Request Body
| Field | Type | Description |
|-------|------|-------------|
| `startDate` | string | Required. YYYY-MM-DD |
| `endDate` | string | Required. YYYY-MM-DD |
| `dimensions` | string[] | `query`, `page`, `country`, `device`, `date`, `searchAppearance` |
| `type` | string | `web`, `image`, `video`, `news`, `discover`, `googleNews` |
| `dimensionFilterGroups` | object[] | Filter groups with `dimension`, `operator`, `expression` |
| `rowLimit` | int | 1-25000 (default: 1000) |
| `startRow` | int | Pagination offset (default: 0) |
| `dataState` | string | `final` (default), `all`, `hourly_all` (April 2025, requires `hour` dimension) |
### Filter Operators
`contains`, `equals`, `notContains`, `notEquals`, `includingRegex`, `excludingRegex`
### Response Fields
Each row: `keys[]`, `clicks`, `impressions`, `ctr`, `position`.
- Data lag by `dataState`: `final` = ~2-3 days; `all` = shorter lag; `hourly_all` = few hours (April 2025). Retention: ~16 months. Use `gsc_query.py --data-state hourly_all --dimensions date,hour,...`.
- Country codes are **ISO 3166-1 alpha-3** (e.g., `USA`, `GBR`).
- The dedicated generative-AI Search and Discover reports are Search Console
UI views. Google's August 31 update says they rolled out to all websites
worldwide. They are not an extra `type` or
`searchAppearance` value documented for this endpoint. Do not synthesize
clicks or queries for those reports or claim this API isolates AI Overviews
and AI Mode.
- Google's July 29 Search Central announcement says Instagram, TikTok, X, and
YouTube platform properties are globally available, while the current Help
Center still says gradual rollout. Verify availability in the account. Do not
promise that this endpoint supports their dedicated reports until Google
publishes API documentation.
---
## GSC URL Inspection
**Endpoint:** `POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect`
```json
{
"inspectionUrl": "https://example.com/blog/post",
"siteUrl": "sc-domain:example.com",
"languageCode": "en"
}
```
### Key Response Fields (`indexStatusResult`)
| Field | Values |
|-------|--------|
| `verdict` | `PASS`, `FAIL`, `NEUTRAL`, `PARTIAL` |
| `coverageState` | Human-readable coverage description |
| `robotsTxtState` | `ALLOWED`, `DISALLOWED` |
| `indexingState` | `INDEXING_ALLOWED`, `BLOCKED_BY_META_TAG`, `BLOCKED_BY_HTTP_HEADER` |
| `pageFetchState` | `SUCCESSFUL`, `SOFT_404`, `BLOCKED_ROBOTS_TXT`, `NOT_FOUND`, `SERVER_ERROR` |
| `lastCrawlTime` | ISO 8601 timestamp |
| `googleCanonical` | URL Google selected as canonical |
| `crawledAs` | `DESKTOP`, `MOBILE` |
---
## Google Analytics Data API v1
This integration uses the `google.analytics.data_v1beta` Python client
namespace and its beta endpoint. The product documentation is Data API v1.
**Base URL:** `https://analyticsdata.googleapis.com/v1beta`
### runReport Overview
Key fields: `property`, `dimensions[]`, `metrics[]`, `dateRanges[]`, `dimensionFilter`, `orderBys[]`, `limit`.
### Blog-Relevant Dimensions
`date`, `landingPage`, `pagePath`, `pageTitle`, `sessionDefaultChannelGroup`, `sessionSource`, `sessionMedium`, `country`, `deviceCategory`
### Blog-Relevant Metrics
`sessions`, `totalUsers`, `screenPageViews`, `bounceRate`, `averageSessionDuration`, `engagementRate`, `keyEvents`
### Organic Traffic Filter
```json
{
"filter": {
"fieldName": "sessionDefaultChannelGroup",
"stringFilter": { "matchType": "EXACT", "value": "Organic Search" }
}
}
```
Uses token-based quotas (200,000 Core Tokens/day per standard property; 2M for 360).
Set `returnPropertyQuota: true` to monitor consumption.
---
## Cloud Natural Language API
**Endpoint:** `POST https://language.googleapis.com/v2/documents:annotateText?key={API_KEY}`
| Feature | What It Does | Blog Use |
|---------|-------------|----------|
| `extractEntities` | People, orgs, places with salience scores | Topic coverage depth, entity optimization |
| `extractDocumentSentiment` | Document + sentence-level sentiment | Content tone assessment |
| `classifyText` | Map content to 700+ Google categories | Topic relevance verification |
| `moderateText` | Detect harmful/sensitive content categories | Content safety screening |
Each entity includes `name`, `type`, `salience` (0-1), `sentiment`, and `metadata` (Wikipedia URL, Knowledge Graph MID).
**Pricing:** 5,000 free units/month for entities and sentiment. Requires billing enabled.
---
## YouTube Data API v3
YouTube results can support relevant media research and cross-platform
distribution. Third-party visibility correlations are observational and do not
establish a Google ranking or citation requirement.
| Method | Quota Cost | Description |
|--------|-----------|-------------|
| `search.list` | 1 unit per call, own bucket (default 100 calls/day) | Search videos matching a query |
| `videos.list` | 1 unit | Video details, statistics, tags |
| `channels.list` | 1 unit | Channel info, subscriber count |
Default quota: `search.list` has its own bucket of **100 calls/day** (1 unit per call); other endpoints share **10,000 units/day** (free). Source: https://developers.google.com/youtube/v3/determine_quota_cost (read 2026-10-12). API key only, no OAuth needed.
---
## Keyword Planner (Google Ads API)
Gold-standard source for keyword search volume. Methods: **GenerateKeywordIdeas** (suggestions
from seeds), **GenerateKeywordHistoricalMetrics** (volume for specific keywords), and
**GenerateKeywordForecastMetrics** (future projections). Returns volume, competition, CPC bids.
**Current API version guidance:** Google Ads API release notes list v25.2 dated
2026-09-23. Check the release notes and support table together before changing
a client or versioned path. The repository's existing client constraint may
lag the current Python package, so validate Keyword Plan compatibility offline:
https://developers.google.com/google-ads/api/docs/release-notes
https://developers.google.com/google-ads/api/docs/sunset-dates
- Without active ad spend, volumes are **bucketed ranges** ("1K-10K") not exact numbers
- `competition` measures **advertiser competition**, not organic difficulty
- Requires: Google Ads Manager Account + Developer Token + OAuth credentials
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |