# Google (/docs/google)



Google [#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/...`

<Callout>
  The Business Profile endpoints each require 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. Sending none is a 

  `400`

   before billing.
</Callout>

Getting started [#getting-started]

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

```bash
# 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 [#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`](/docs/naver.md) indexes far more deeply, and for headlines
[`/v1/google_news/search`](/docs/google_news.md) is the right surface.

Ads Transparency Center [#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).

```bash
# 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 [#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]

`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.

```bash
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 [#endpoints]

<PlatformEndpoints platform="google" />

Read this before you build [#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 [#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