Google

Four Google surfaces behind one key: web search results, the Ads Transparency Center (who is advertising, with what creative, where), Google Business Profiles with their reviews, owner posts and customer questions, and Google Travel hotel listings with vendor pricing. Each is useful on its own; together they cover most of what a competitor or local-market research pipeline needs from Google.

Base URL: /v1/google/...

Getting started

Every endpoint is a GET with query parameters and an x-api-key header.

# Web search — 1 credit
curl "https://www.socialcrawl.dev/v1/google/search?query=social%20media%20api&region=US" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# Every ad a company is running — 5 credits
curl "https://www.socialcrawl.dev/v1/google/company/ads?domain=lululemon.com" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

Web search

GET /v1/google/search?query=… returns ranked organic results — title, page URL, snippet, and position — for 1 credit. region takes a two-letter country code and returns that country's results, and page walks the ranking. For Korean-language web pages /v1/naver/webkr/search indexes far more deeply, and for headlines /v1/google_news/search is the right surface.

Ads Transparency Center

Three endpoints, and the order matters because the Transparency Center indexes advertisers by an opaque id.

Start from a domain if you have one: company/ads?domain=lululemon.com returns that advertiser's ad history directly. When all you have is a brand name, resolve it first with adlibrary/advertisers/search?query=lululemon, which returns matching advertisers with their advertiser_id and region (it defaults to searching the US — pass region for another market).

# 1. Brand name to advertiser id
curl "https://www.socialcrawl.dev/v1/google/adlibrary/advertisers/search?query=lululemon&region=CA" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Their ads, filtered to YouTube video creatives this year
curl "https://www.socialcrawl.dev/v1/google/company/ads?advertiser_id=$ADVERTISER_ID&platform=youtube&format=video&start_date=2026-01-01" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

company/ads filters on platform (google_maps, google_play, google_search, google_shopping, youtube), format (text, image, video), a start_date/end_date window, and topic (all or political — political searches also need a region). It cursor-paginates.

The list rows carry a creative id, ad URL, advertiser name, thumbnail and first-shown date, but not the ad's own copy. For that, pass a row's creative URL to GET /v1/google/ad. That URL must contain both segments — …/advertiser/{AR…}/creative/{CR…} — because an advertiser-only URL does not identify an ad. No impression estimate is returned by either endpoint; Google does not publish one here.

Business Profiles

/v1/google/business/info resolves one local business and returns its name, category, star rating, address, phone, coordinates, opening hours, and whether the listing is claimed, for 1 credit. Identify it by keyword (business name plus address, e.g. Irving Farm New York 645 5th Ave), or exactly by cid or place_id when you already hold one. location_name takes a City,Region,Country string for geographic context and defaults to New York.

Three endpoints go deeper on the same place:

• /v1/google/business/extended-reviews (5cr) returns reviews from the Google listing and from third-party sites such as TripAdvisor and Yelp, each with its source, text, rating and owner reply. depth runs in steps of 20 up to 1000.
• /v1/google/business/questions (5cr) returns the public customer questions and their answers as one flat list, where each answer links to its question through parent_id.
• /v1/google/business/updates (1cr) returns the posts the owner published on the profile. Most businesses publish none, so an empty list here is a normal answer rather than a failure.

Hotels

hotels/search?keyword=hotels in Barcelona returns candidate hotels from Google Travel with star rating, review score, coordinates, images, nightly price and an opaque hotel_identifier, for 1 credit. check_in and check_out set the stay being priced; omitted, they default to tomorrow for one night. Pass an identifier to /v1/google/hotels/info (5cr) for the full record — description, address, phone, amenities, review sentiment topics, and prices from several booking vendors.

curl "https://www.socialcrawl.dev/v1/google/hotels/search?keyword=hotels%20in%20Barcelona&check_in=2026-09-12&check_out=2026-09-15" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

Endpoints

10 endpoints available.

Read this before you build

Every business endpoint needs one of a small identifier set, and the sets differ. business/info, business/extended-reviews and business/questions accept keyword, cid or place_id. business/updates accepts keyword or cid only — there is no place_id on that one. Sending none of them is a 400 before billing.

cid is the reliable identifier. A keyword match is a search, so an ambiguous business name resolves to whichever listing Google ranks first. Resolve once with business/info, store the cid, and use it everywhere after that.

The ad-list rows have no engagement and no duration. Ad Library records carry no views, likes, comments or shares, and video ads carry no duration at the list level, so those canonical fields come back null rather than zero. get_ad_details is the opt-in expansion for per-ad detail.

Image URLs on ads are frequently null. Text-format ads carry an archived creative thumbnail; image and video formats often do not, because Google does not archive video frames in the list response.

Notes

• All endpoints use GET with query parameters
• Authentication via the x-api-key header
• Responses follow the unified SocialCrawl schema
• language_name on the business and hotel endpoints selects the result language and defaults to English
• Several business and hotel endpoints run as upstream tasks, so allow a longer client timeout on business/updates, business/extended-reviews and hotels/info than on the inline ones