# Social Fetch API - Google endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

3 documented Google operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/google/ad-library/companies/ads
List Google company ads
Credit cost: 25 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/google/ad-library/companies/ads/get.mdx
SDK: client.google.listCompanyAds({ domain: "lululemon.com" })
Parameters:
- domain (optional, string) - Company domain when you do not have an advertiser id.
- advertiserId (optional, string) - Google Ad Transparency advertiser id when you have it instead of a domain.
- topic (optional, string, enum: all | political) - Optional topic filter. When `political`, `region` is required.
- region (optional, string) - Optional region filter as a two-letter country code.
- startDate (optional, string) - Optional start date filter in YYYY-MM-DD format.
- endDate (optional, string) - Optional end date filter in YYYY-MM-DD format.
- platform (optional, string, enum: google_maps | google_play | google_search | google_shopping | youtube) - Optional Google surface filter.
- format (optional, string, enum: text | image | video) - Optional creative format filter.
- cursor (optional, string) - Opaque pagination cursor from a previous response (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Disambiguation: Google Ad Transparency only includes public ads.
curl "https://api.socialfetch.dev/v1/google/ad-library/companies/ads?domain=lululemon.com" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/google/ad-library/ads
Get Google Ad Library ad
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/google/ad-library/ads/get.mdx
SDK: client.google.getAdLibraryAd({ url: "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR07443539616616939521" })
Parameters:
- url (required, string) - Public Google Ad Transparency URL for the creative.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/google/ad-library/ads?url=https://www.example.com/social/content/example123" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/google/ad-library/advertisers/search
Search Google Ad Library advertisers
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/google/ad-library/advertisers/search/get.mdx
SDK: client.google.searchAdLibraryAdvertisers({ query: "lululemon" })
Parameters:
- query (required, string) - Search query text for Google Ad Transparency advertisers.
- region (optional, string) - Optional two-letter country code to search in. Defaults to US when omitted.
curl "https://api.socialfetch.dev/v1/google/ad-library/advertisers/search?query=lululemon" \
  -H "x-api-key: YOUR_API_KEY"