diff --git a/Specialized/serp-ads/SKILL.md b/Specialized/serp-ads/SKILL.md new file mode 100644 index 0000000..99a7daa --- /dev/null +++ b/Specialized/serp-ads/SKILL.md @@ -0,0 +1,384 @@ +--- +name: serp-ads +description: > + Specialized skill for Google Ads intelligence workflows via SerpApi β€” competitor ad research, + advertiser discovery, ad creative analysis, ad format tracking, political ad monitoring, + platform-specific ad filtering, and ad timeline analysis. Use when: (1) researching a + competitor's Google Ads campaigns or ad history, (2) finding all ads run by a specific + advertiser or domain, (3) analyzing ad creatives (text, image, video) for messaging and + strategy, (4) tracking when and where ads were shown (dates, regions, platforms), + (5) monitoring political advertising by region, (6) comparing ad strategies across + competitors, (7) finding ads on specific platforms (YouTube, Search, Shopping, Maps, Play), + (8) investigating ad creative formats and messaging patterns, (9) any task involving + the Google Ads Transparency Center. This skill builds on the foundational serpapi skill + for all API details. +metadata: {"openclaw": {"emoji": "πŸ“’", "requires": {"env": ["SERPAPI_KEY"]}, "primaryEnv": "SERPAPI_KEY"}} +--- + +# Google Ads Intelligence Workflows + +Competitor ad research, creative analysis, timeline tracking, and political ad monitoring via SerpApi's Google Ads Transparency Center engines. This skill covers workflow logic β€” load the **serpapi** foundational skill for API details, parameters, and wrapper script usage. + +## Dependencies + +This skill builds on: +- **serpapi** β€” SerpApi wrapper script and full API reference (engines: `google_ads_transparency_center`, `google_ads_transparency_center_ad_details`) + +## Core Concepts + +### Engines + +| Engine | Purpose | Key Inputs | +|--------|---------|------------| +| `google_ads_transparency_center` | List ads by advertiser or domain | `advertiser_id` or `text` (domain/name) | +| `google_ads_transparency_center_ad_details` | Detailed info for a specific ad creative | `advertiser_id` + `creative_id` | + +### Finding Advertisers + +Advertisers are identified by: +- **Advertiser ID** β€” format `AR` + digits (e.g., `AR17828074650563772417` for Tesla Inc.) +- **Domain search** β€” pass the domain as the `text` parameter (e.g., `text=apple.com`) + +The `text` parameter is the easiest way to discover an advertiser β€” use whatever you'd type into the Google Ads Transparency Center search bar (domain, brand name, etc.). + +### Ad Creative Results + +Each ad creative in the listing response includes: +- `advertiser_id` / `advertiser` β€” Advertiser info +- `ad_creative_id` β€” Unique ID (format `CR` + digits), used for fetching details +- `format` β€” `text`, `image`, or `video` +- `image` β€” Screenshot/preview of the ad +- `width` / `height` β€” Creative dimensions +- `first_shown` / `last_shown` β€” Unix timestamps for when the ad was active +- `details_link` β€” Google's transparency page for this ad +- `serpapi_details_link` β€” Direct SerpApi link to fetch details + +### Ad Detail Results + +The details endpoint returns richer data per creative: + +**For text ads:** +- `title`, `headline`, `long_headline` β€” Ad copy elements +- `snippet` β€” Ad description text +- `visible_link` / `link` β€” Display URL and destination URL +- `sitelink_texts` / `sitelink_descriptions` β€” Sitelink extensions +- `advertiser_logo` / `advertiser_logo_alt` β€” Branding + +**For image ads:** +- `image` β€” Full creative image URL +- `call_to_action` β€” CTA button text +- `snippet` β€” Ad text overlay +- `link` β€” Destination URL +- `carousel_data[]` β€” If carousel format: images, headlines, button links +- `images[]` β€” Multiple image variants with tags + +**For video ads:** +- `video_link` β€” Video URL (often YouTube-hosted) +- `raw_video_link` β€” Direct video file link (when available) +- `video_duration` β€” Duration string +- `headline`, `call_to_action`, `snippet` β€” Ad copy +- `channel_name` / `channel_icon` β€” YouTube channel info + +**Common detail fields:** +- `rating` / `reviews` / `reviews_link` β€” If product-related +- `address` β€” For local/store ads +- `is_verified` β€” Advertiser verification status +- `extensions[]` β€” Additional ad extensions + +**Search information (from details):** +- `format` β€” Creative type +- `last_shown` β€” Most recent display timestamp +- `region_name` β€” Target region +- `ad_funded_by` β€” Funding entity (especially for political ads) +- `regions[]` β€” Full list of regions where ad ran, with `first_shown`, `last_shown`, and `times_shown` + +### Pagination + +The listing endpoint returns up to `num` results (default 40). Paginate with `next_page_token` from the response. Each page costs one search credit. + +### Filters + +| Filter | Parameter | Values | +|--------|-----------|--------| +| Platform | `platform` | `SEARCH`, `YOUTUBE`, `SHOPPING`, `MAPS`, `PLAY` | +| Format | `creative_format` | `text`, `image`, `video` | +| Region | `region` | Region code (see Google Ads Transparency regions) | +| Date range | `start_date` / `end_date` | `YYYYMMDD` format | +| Political | `political_ads` | `true` (requires `region`) | + +## Workflows + +### 1. Competitor Ad Research + +Discover what ads a competitor is running and how they position themselves. + +**Step 1: Find the advertiser.** +Use the **serpapi** skill with `google_ads_transparency_center` engine and `text` set to the competitor's domain (e.g., `text=competitor.com`). + +**Step 2: Browse their ad catalog.** +Results return `ad_creatives[]` β€” scan `format`, `first_shown`/`last_shown` timestamps, and the ad preview `image`. Note which creatives are currently active (recent `last_shown`). + +**Step 3: Analyze key creatives.** +For interesting ads, use `google_ads_transparency_center_ad_details` with the `advertiser_id` + `creative_id` to get full creative details β€” headlines, descriptions, CTAs, sitelinks, and destination URLs. + +**What to extract:** +- **Messaging themes** β€” What value propositions do they lead with? +- **CTAs** β€” What actions do they push? (Shop now, Learn more, Get started) +- **Landing pages** β€” Where do ads link? (Product pages, landing pages, blog posts) +- **Sitelink strategy** β€” What additional links do they promote? +- **Format mix** β€” Ratio of text vs image vs video ads +- **Active period** β€” How long do they run ads? Seasonal patterns? + +**Presentation:** + +``` +πŸ“’ Ad Intelligence: [Competitor] +Advertiser: [name] (ID: [advertiser_id]) +Total ads found: [count] + +πŸ”€ Text Ads ([count]): +β€’ "[headline]" β€” [snippet excerpt] + CTA: [call_to_action] | πŸ”— [visible_link] + Active: [first_shown] β†’ [last_shown] + +πŸ–ΌοΈ Image Ads ([count]): +β€’ [call_to_action] β€” [snippet excerpt] + πŸ“ [width]Γ—[height] | πŸ”— [link] + +🎬 Video Ads ([count]): +β€’ "[headline]" β€” [video_duration] + CTA: [call_to_action] | πŸ”— [link] + +πŸ’‘ Key Insights: +- [Messaging patterns observed] +- [CTA preferences] +- [Landing page strategy] +``` + +### 2. Ad Creative Deep Dive + +When the user wants detailed analysis of specific ad creatives. + +**Step 1: Get the creative listing** (if not already done). +Search by advertiser ID or domain using `google_ads_transparency_center`. + +**Step 2: Fetch details for target creatives.** +Use `google_ads_transparency_center_ad_details` with `advertiser_id` + `creative_id`. + +**Step 3: Analyze the creative.** + +For **text ads**, focus on: +- Headline progression (title β†’ headline β†’ long_headline) +- Description/snippet copywriting +- Sitelink strategy and what pages they promote +- URL structure (vanity URLs, UTM patterns) + +For **image ads**, focus on: +- Visual style and branding consistency +- CTA placement and text +- If carousel: how many cards, what progression/story +- Image dimensions and aspect ratios (indicates platform targeting) + +For **video ads**, focus on: +- Video duration (6s bumper, 15s, 30s, long-form) +- Channel association (branded YouTube channel?) +- CTA overlay text +- Whether it's a repurposed organic video or ad-specific + +### 3. Platform-Specific Analysis + +Understand how an advertiser targets different Google platforms. + +**Strategy:** Run the listing search multiple times with different `platform` filters: +- `SEARCH` β€” Google Search text ads +- `YOUTUBE` β€” Video ads and display on YouTube +- `SHOPPING` β€” Product listing ads +- `MAPS` β€” Local/map ads +- `PLAY` β€” App install ads + +**What to compare:** +- Which platforms they invest in most (ad count per platform) +- How messaging differs across platforms +- Format preferences per platform (text on Search, video on YouTube) +- Whether they use platform-specific features (Shopping product feeds, Maps local info) + +**Presentation:** + +``` +πŸ“Š Platform Breakdown: [Advertiser] + +πŸ” Google Search: [count] ads + Formats: [text: X, image: Y] + Top themes: [themes] + +▢️ YouTube: [count] ads + Formats: [video: X, image: Y] + Avg duration: [duration] + +πŸ›’ Shopping: [count] ads +πŸ—ΊοΈ Maps: [count] ads +πŸ“± Play: [count] ads + +πŸ’‘ Platform strategy: [summary] +``` + +### 4. Ad Timeline Analysis + +Track how an advertiser's ad strategy evolves over time. + +**Step 1: Get the full ad listing** for the advertiser. + +**Step 2: Analyze timestamps.** +Each creative has `first_shown` and `last_shown` (Unix timestamps). Convert to dates and map out: +- Currently active ads (recent `last_shown`) +- Campaign duration patterns (how long each ad runs) +- Launch clusters (multiple ads starting around the same date = new campaign) +- Seasonal patterns (holiday campaigns, product launches) + +**Step 3: For deeper timeline data**, fetch details on key creatives. +The detail response includes `regions[]` with per-region `first_shown`/`last_shown`/`times_shown` β€” showing geographic rollout patterns. + +**Step 4: Use date-range filters** to focus on specific periods. +Pass `start_date` and `end_date` (YYYYMMDD) to narrow results to a time window. For today's ads only, set `end_date` = `start_date` + 1 day. + +**What to look for:** +- Campaign cycles β€” How often do they refresh creatives? +- Geographic expansion β€” Did they start in one region and expand? +- Seasonal spikes β€” More ads during holidays, events, or product launches? +- Format evolution β€” Shifting from text to video over time? + +### 5. Competitor Comparison + +Compare ad strategies across multiple competitors. + +**Step 1: List competitors** (2-5 domains or advertiser IDs). + +**Step 2: For each competitor**, run a listing search and collect: +- Total ad count +- Format breakdown (text/image/video) +- Active vs historical ads +- Platform distribution +- Key messaging themes (from headlines/snippets of top creatives) + +**Step 3: Compare across dimensions:** + +``` +πŸ“Š Competitive Ad Comparison + +| Metric | [Brand A] | [Brand B] | [Brand C] | +|--------|-----------|-----------|-----------| +| Total ads | X | Y | Z | +| Text ads | X | Y | Z | +| Image ads | X | Y | Z | +| Video ads | X | Y | Z | +| Active (last 30d) | X | Y | Z | +| Primary platform | Search | YouTube | Shopping | +| Top CTA | "Shop Now" | "Learn More" | "Get Started" | + +Key Differences: +- [Brand A] focuses heavily on text ads with aggressive CTAs +- [Brand B] invests in video content on YouTube +- [Brand C] leads with Shopping/product ads +``` + +### 6. Political Ad Monitoring + +Track political advertising in a specific region. + +**Important:** Political ads require `political_ads=true` AND a `region` parameter. Without both, political ads won't appear. + +**Step 1: Search for political ads.** +Use `google_ads_transparency_center` with `political_ads=true` and `region` set to the target region code. Optionally add `text` to search for a specific candidate, party, or PAC. + +**Step 2: Analyze the results.** +Political ad details include `ad_funded_by` β€” the entity paying for the ad. + +**What to track:** +- Which entities are advertising +- Volume of ads per entity +- Regional targeting patterns +- Format preferences (text vs video for different messages) +- Funding sources (`ad_funded_by`) +- Time patterns around elections/events + +### 7. Ad Format Analysis + +Research creative format trends for an industry or advertiser. + +**Step 1: Get ad listings** with `creative_format` filter to isolate a specific format. + +**Step 2: For each format, analyze patterns:** + +**Text ads:** +- Average headline length +- Common power words and phrases +- CTA language patterns +- Sitelink topics and count +- Use of extensions + +**Image ads:** +- Common dimensions (indicates platform targeting) +- Carousel vs single image ratio +- Visual style patterns (photography vs illustration vs design) +- CTA overlay patterns + +**Video ads:** +- Duration distribution +- YouTube vs non-YouTube hosting +- Whether ads are repurposed content or ad-specific + +### 8. Regional Ad Research + +Understand how an advertiser targets different geographic markets. + +**Step 1: Run listing search** for the advertiser. + +**Step 2: Fetch details on key creatives** β€” the `regions[]` array in details shows every region where that ad ran, with timing data. + +**Step 3: Map regional strategy:** +- Which regions get the most ads? +- Do they localize creatives or use the same ads globally? +- Regional launch timing β€” staggered rollout or simultaneous? +- Which regions see the ad most (`times_shown`)? + +**Use `region` filter** on the listing search to see only ads shown in a specific region. + +## Common Patterns + +### "What ads is [company] running?" +1. Search with `text=[company domain]` +2. Present total count, format breakdown, and top 5-10 most recent creatives +3. Offer to drill into specific ads or filter by format/platform + +### "Compare [brand A] vs [brand B] ads" +1. Search each brand separately +2. Build comparison table (counts, formats, platforms, themes) +3. Fetch details on 2-3 top creatives per brand for messaging comparison + +### "Show me their YouTube ads" +1. Search with `text=[domain]` and `platform=YOUTUBE` +2. Fetch details on video creatives for duration, headline, CTA +3. Present with video durations and messaging summaries + +### "What political ads are running in [region]?" +1. Search with `political_ads=true`, `region=[code]` +2. Group by `advertiser` / `ad_funded_by` +3. Present volume per entity with date ranges + +### "How has [company]'s advertising changed over the past year?" +1. Search with `text=[domain]`, `start_date` = 1 year ago, `end_date` = today +2. Analyze `first_shown`/`last_shown` patterns +3. Break into quarterly or monthly clusters +4. Note format shifts, messaging changes, new campaigns + +## Tips + +- **Domain search is easiest** β€” use `text=domain.com` to find any advertiser. No need to know the advertiser ID upfront. +- **Multiple advertiser IDs** β€” `advertiser_id` accepts comma-separated IDs to search multiple advertisers at once. +- **Active vs historical** β€” Compare `last_shown` timestamps against today to determine which ads are currently active vs archived. +- **Date filtering for campaigns** β€” Use `start_date`/`end_date` to isolate specific campaign periods (product launches, holidays, events). +- **Political ads are separate** β€” They never appear in regular results. Always set `political_ads=true` to find them. +- **`num` for batch size** β€” Default is 40 results. Set `num=100` for larger batches (one credit per page regardless of size). +- **Creative screenshots** β€” The `image` field in listing results is a rendered screenshot of the ad. Useful for visual analysis even without fetching full details. +- **Timestamp conversion** β€” `first_shown` and `last_shown` are Unix timestamps. Convert with standard date functions for human-readable dates. +- **Region codes** β€” These are numeric codes used by Google's Ads Transparency Center. Common ones: `2840` (US), `2826` (UK), `2276` (Germany), `2250` (France). When unsure, omit region to search globally. diff --git a/Specialized/serp-google-images/SKILL.md b/Specialized/serp-google-images/SKILL.md new file mode 100644 index 0000000..b1cde92 --- /dev/null +++ b/Specialized/serp-google-images/SKILL.md @@ -0,0 +1,378 @@ +--- +name: serp-google-images +description: > + Specialized skill for Google Images search workflows via SerpApi β€” find images by topic, + filter by size/color/type/license, reverse image search, explore related content, and + curate visual collections. Use when: (1) searching for images on a topic or keyword, + (2) finding high-resolution or specific-size images, (3) filtering images by color, + type (photo, clipart, line art, animated), or license (Creative Commons, commercial), + (4) performing reverse image search to find where an image appears online, + (5) finding visually similar or related images, (6) curating a collection of images + for a project, presentation, or mood board, (7) sourcing stock-style or reference images + with specific dimensions or aspect ratios, (8) time-filtered image search for recent + images only, (9) any image discovery or visual research task via Google Images. + This skill builds on the foundational serpapi skill for all API details. +metadata: {"openclaw": {"emoji": "πŸ–ΌοΈ", "requires": {"env": ["SERPAPI_KEY"]}, "primaryEnv": "SERPAPI_KEY"}} +--- + +# Google Images Search Workflows + +Image search, filtering, reverse lookup, related content discovery, and visual curation via SerpApi's Google Images engines. This skill covers workflow logic β€” load the **serpapi** foundational skill for API details, parameters, and wrapper script usage. + +## Dependencies + +This skill builds on: +- **serpapi** β€” SerpApi wrapper script and full API reference (engines: `google_images`, `google_images_light`, `google_images_related_content`, `google_reverse_image`) + +## Engine Selection + +| Engine | Purpose | Speed | Best For | +|--------|---------|-------|----------| +| `google_images` | Full image search | Normal | Detailed results with shopping, suggested searches | +| `google_images_light` | Lightweight image search | Faster | Quick searches, bulk queries, when you don't need shopping/suggestions | +| `google_images_related_content` | Related images for a specific result | Normal | "More like this" exploration | +| `google_reverse_image` | Reverse image search by URL | Normal | Finding image sources, visual matches, identification | + +**Default to `google_images`** for most workflows. Use `google_images_light` when speed matters or you're doing many searches in sequence. + +## Response Structure + +### Image Results + +Each item in `images_results[]` includes: +- `position` β€” Result index +- `title` β€” Image description/caption +- `original` β€” Full-resolution image URL +- `original_width` / `original_height` β€” Image dimensions in pixels +- `thumbnail` β€” Smaller preview URL +- `source` β€” Domain hosting the image +- `link` β€” Page URL where the image appears +- `is_product` β€” Whether the image links to a product page +- `in_stock` β€” Product availability (when `is_product` is true) +- `related_content_id` β€” ID for fetching related/similar images +- `tag` β€” Optional label (e.g., "Recipe", "Product") + +### Additional Response Sections + +- `suggested_searches[]` β€” Refinement suggestions with `name`, `chips`, `thumbnail` +- `shopping_results[]` β€” Product results with `title`, `price`, `source`, `link`, `thumbnail` +- `related_searches[]` β€” Related query suggestions with `query`, `thumbnail` + +### Pagination + +Images return in batches of ~100. Paginate with the `ijn` parameter: +- `ijn=0` β€” First page (default) +- `ijn=1` β€” Second page (results 101-200) +- `ijn=2` β€” Third page (results 201-300) + +For `google_images_light`, use the `start` parameter instead (offset-based, 0-999). + +## Workflows + +### 1. Basic Image Search + +Search for images on any topic using the `google_images` engine. + +**Required:** `q` (search query) +**Recommended:** Size and type filters when the user has specific needs + +**What to present:** 5-10 results with title, source, dimensions, and original URL. Include thumbnails descriptions when helpful. + +**Query tips:** +- Be specific: "golden retriever puppy outdoors" beats "dog" +- Use quotes for exact phrases: `"modern kitchen design"` +- Add context: "logo transparent background" or "infographic template" + +### 2. Filtered Image Search + +Apply filters to narrow results. All filters go through the `google_images` or `google_images_light` engine as parameters. + +#### Size Filters + +| Need | Parameter Value | Notes | +|------|----------------|-------| +| Large images | `imgsz=l` | Good default for high-quality results | +| Medium images | `imgsz=m` | Balanced size/speed | +| Icons/thumbnails | `imgsz=i` | Small images only | +| Minimum resolution | `imgsz=2mp`, `4mp`, `8mp`, etc. | Specific megapixel minimum (up to 70mp) | +| Specific minimum | `imgsz=qsvga` (400Γ—300), `vga` (640Γ—480), `svga` (800Γ—600), `xga` (1024Γ—768) | Named size thresholds | + +#### Aspect Ratio Filters + +| Ratio | Parameter Value | +|-------|----------------| +| Square | `imgar=s` | +| Tall (portrait) | `imgar=t` | +| Wide (landscape) | `imgar=w` | +| Panoramic (ultra-wide) | `imgar=xw` | + +#### Color Filters + +| Need | Parameter Value | +|------|----------------| +| Black and white | `image_color=bw` | +| Transparent background | `image_color=trans` | +| Specific color dominant | `image_color=red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `gray`, `black`, `brown` | + +#### Type Filters + +| Type | Parameter Value | +|------|----------------| +| Photos only | `image_type=photo` (or `imgtype=photo`) | +| Clip art | `image_type=clipart` | +| Line drawings | `image_type=lineart` | +| Animated/GIF | `image_type=animated` | +| Face-focused | `image_type=face` | + +#### License Filters + +| License | Parameter Value | Use Case | +|---------|----------------|----------| +| Creative Commons | `licenses=cl` | Free to use with attribution | +| Commercial use | `licenses=ol` | Safe for business use | +| Free to share | `licenses=f` | Personal sharing OK | +| Free commercial share | `licenses=fc` | Commercial sharing OK | +| Free to modify | `licenses=fm` | Can edit/remix | +| Free commercial modify | `licenses=fmc` | Can edit/remix commercially | + +**Combining filters:** Pass multiple filter parameters in the same request. They stack β€” e.g., large + transparent + photo narrows results to large transparent photos. + +### 3. Time-Filtered Search + +Find images from a specific time period. + +**Option A β€” Relative time:** +- `period_unit` + `period_value` β€” e.g., `period_unit=d`, `period_value=7` for past week +- Units: `s` (second), `n` (minute), `h` (hour), `d` (day), `w` (week), `m` (month), `y` (year) + +**Option B β€” Date range:** +- `start_date` + `end_date` in `YYYYMMDD` format +- `start_date` alone = from that date to today +- `end_date` alone = before that date + +**Use cases:** +- Recent product photos: `period_unit=m`, `period_value=3` +- Event coverage: date range around the event dates +- Trending visuals: `period_unit=w`, `period_value=1` + +### 4. Reverse Image Search + +Find where an image appears online, identify objects, or find similar images using the `google_reverse_image` engine. + +**Required:** `image_url` β€” a publicly accessible URL of the image to search + +**Optional:** `q` β€” add a text query alongside the image for more targeted results + +**What you get:** +- `image_results[]` β€” Pages containing the same or similar image +- `inline_images[]` β€” Visually similar images +- `knowledge_graph` β€” Identified subject (if recognizable) + +**Use cases:** +- **Source finding:** "Where did this image originate?" β€” Check the oldest/most authoritative results +- **Fact checking:** Verify if an image is being used in context or is misleading +- **Identification:** "What is this object/landmark/plant?" β€” Check knowledge graph +- **Higher resolution:** Find the same image at better quality from different sources +- **Copyright check:** See where an image is used across the web + +**Presentation pattern:** +1. If knowledge graph identifies the subject, lead with that +2. List top sources where the image appears (domain, page title) +3. Show visually similar images if the user wants alternatives + +### 5. Related Content Exploration + +When a user likes a specific image and wants more like it, use the `google_images_related_content` engine. + +**Required:** `related_content_id` β€” from an image result's `related_content_id` field + +**Workflow:** +1. Perform initial image search +2. User identifies an image they like (by position or description) +3. Use that image's `related_content_id` to fetch related content +4. Present the visually similar results + +This is Google's "more like this" feature β€” it finds images with similar visual characteristics, subject matter, and style. + +### 6. Visual Curation / Mood Board + +When a user wants to collect images for a project, presentation, or creative brief: + +**Step 1: Broad search** β€” Start with a general query to understand what's available. + +**Step 2: Refine with filters** β€” Apply size, color, type, and aspect ratio filters based on the user's project needs. + +**Step 3: Explore related content** β€” For images the user likes, use related content to find similar ones. + +**Step 4: Compile results** β€” Present a curated selection organized by theme or style. + +**Presentation format:** + +``` +πŸ–ΌοΈ Image Collection: [Theme] + +1. "[Title]" β€” [Source] + πŸ“ [Width]Γ—[Height] | πŸ”— [original URL] + +2. "[Title]" β€” [Source] + πŸ“ [Width]Γ—[Height] | πŸ”— [original URL] + +... + +πŸ’‘ Suggested refinements: [from suggested_searches] +``` + +**Tips:** +- Use `imgsz=l` or specific megapixel minimums for print/high-quality projects +- Use `image_color=trans` for images that need to overlay other content +- Use `imgar=w` for banner/header images, `imgar=s` for social media posts +- Filter by license when images will be used commercially + +### 7. Product Image Search + +When looking for product images, shopping results are especially useful: + +**Strategy:** +1. Search with product-specific query (brand + product name) +2. Check `shopping_results[]` for product images with prices and availability +3. Check `images_results[]` where `is_product=true` for additional product images +4. Filter `in_stock=true` results if linking to purchasable items matters + +**Presentation pattern:** + +``` +πŸ›’ Product Images: [Product] + +Shopping Results: +β€’ [Title] β€” $[Price] from [Source] + πŸ”— [link] + +Image Results (product pages): +β€’ "[Title]" β€” [Source] | πŸ“ [dimensions] + πŸ”— [original URL] +``` + +### 8. Reference Image Search + +When searching for images as reference material (design, art, architecture, etc.): + +**Strategy:** +1. Use descriptive, style-specific queries: "brutalist architecture exterior", "watercolor landscape tutorial", "80s retro neon aesthetic" +2. Filter to large images (`imgsz=l` or `imgsz=4mp`+) for detail +3. Use color filters to match a palette: `image_color=teal` for cool tones +4. Use type filters: `image_type=photo` for realism, `image_type=lineart` for technical references +5. Explore suggested searches for related style terms +6. Use related content to branch out from strong matches + +### 9. Iterative Refinement + +When initial results don't match what the user needs: + +**Refine the query:** +- Add adjectives: "minimalist", "vintage", "high-contrast", "aerial view" +- Add context: "for website", "on white background", "editorial style" +- Exclude terms with `-`: `"modern kitchen -IKEA"` + +**Add filters:** +- Too many small images β†’ add `imgsz=l` +- Wrong style β†’ add `image_type=photo` or `image_type=clipart` +- Wrong colors β†’ add `image_color` filter +- Wrong proportions β†’ add `imgar` filter + +**Explore branches:** +- Use `suggested_searches[]` from results β€” these are Google's refinement suggestions +- Use `related_searches[]` for tangential topics +- Use related content for visual similarity exploration + +**Paginate:** +- With `google_images`: increment `ijn` (0, 1, 2...) +- With `google_images_light`: increment `start` (0, 100, 200...) + +## Presenting Results + +### Standard Image Search Results + +``` +πŸ–ΌοΈ Google Images: "[query]" + +1. "[Title]" β€” [Source] + πŸ“ [Width]Γ—[Height] | [tag if present] + πŸ”— [original URL] + +2. "[Title]" β€” [Source] + πŸ“ [Width]Γ—[Height] + πŸ”— [original URL] + +... + +πŸ’‘ Try also: [2-3 suggested searches from results] +``` + +### Reverse Image Search Results + +``` +πŸ” Reverse Image Search + +🧠 Identified: [knowledge graph result, if present] + +πŸ“ Found on: +1. [Page title] β€” [domain] + πŸ”— [link] +2. [Page title] β€” [domain] + πŸ”— [link] + +πŸ–ΌοΈ Visually Similar: +β€’ "[Title]" β€” [Source] | πŸ“ [dimensions] +β€’ "[Title]" β€” [Source] | πŸ“ [dimensions] +``` + +## Common Patterns + +### "Find images of [topic]" +1. Search with `google_images`, `q=[topic]` +2. Present top 5-8 results with titles, sources, and dimensions +3. Offer to filter by size, color, or type + +### "Find large/HD images of [topic]" +1. Search with `imgsz=l` or specific megapixel minimum +2. Sort presentation by dimensions (largest first) +3. Note which images have the best resolution + +### "Find images with transparent background" +1. Search with `image_color=trans` +2. Note: results are typically PNG format +3. Verify by checking file extensions in original URLs when possible + +### "Find free-to-use images of [topic]" +1. Search with `licenses=cl` (Creative Commons) or `licenses=ol` (commercial) +2. Always note the license type β€” "free to use" doesn't mean "no attribution" +3. Recommend the user verify the license on the source page + +### "Where is this image from?" / "What is this?" +1. Use `google_reverse_image` with `image_url` +2. Check knowledge graph for identification +3. List the top sources by authority/date +4. Show visually similar images if the user wants alternatives + +### "Find images similar to this one" +1. First search to locate the reference image in results (or use reverse search) +2. Get the `related_content_id` from the matching result +3. Use `google_images_related_content` to fetch similar images +4. Present the related results + +### "Find [topic] images from the last [time period]" +1. Search with `period_unit` and `period_value` matching the requested timeframe +2. Or use `start_date`/`end_date` for specific date ranges +3. Useful for news events, recent product launches, seasonal content + +## Tips + +- **Default to large images** unless the user asks otherwise β€” `imgsz=l` gives better quality results with minimal downside. +- **`google_images_light` for speed** β€” when doing multiple searches in sequence (e.g., comparing results across queries), use the light engine to save time and API credits. +- **Combine filters freely** β€” size + color + type + license all work together. More filters = fewer but more relevant results. +- **Suggested searches are gold** β€” the `suggested_searches[]` array contains Google's own refinement ideas. Use them to help users who aren't sure exactly what they want. +- **Product detection** β€” `is_product` and `in_stock` fields help distinguish commercial images from editorial/informational ones. +- **`tbs` for advanced users** β€” the `tbs` parameter accepts raw Google filter strings. If the user knows the exact filter string from a Google Images URL, pass it directly. +- **Aspect ratio for specific uses** β€” `imgar=w` for banners/headers, `imgar=t` for phone wallpapers/Pinterest, `imgar=s` for avatars/profile pictures, `imgar=xw` for panoramic/landscape. +- **Localization matters** β€” use `gl` and `hl` to get region-appropriate image results (e.g., food images vary significantly by region). +- **License disclaimer** β€” always remind users that license filters are based on metadata and should be verified on the source page before commercial use. diff --git a/serp-google-images.skill b/serp-google-images.skill new file mode 100644 index 0000000..b3158d0 Binary files /dev/null and b/serp-google-images.skill differ