# Google (/docs/google)

Google web search, the Ads Transparency Center, Google Business Profiles with reviews and Q&A, and Google Travel hotel data

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. Together they cover most of what a competitor or local-market research pipeline needs from Google.

Base URL: `/v1/google/...`

  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.

## Quickstart

### 1. Run a web search

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

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google/search?query=social%20media%20api&region=US" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Pull every ad a company is running

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google/company/ads?domain=lululemon.com" \
  -H "x-api-key: YOUR_API_KEY"
```

## Web search

| Endpoint                | Credits | What it returns                                            | Key parameters                           |
| ----------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------- |
| `GET /v1/google/search` | 1       | Ranked organic results: title, page URL, snippet, position | `query`, `region`, `date_posted`, `page` |

`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

The order matters, because the Transparency Center indexes advertisers by an opaque id.

| Endpoint                                      | Credits | What it returns                                                                                | Key parameters                                                                                 |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET /v1/google/adlibrary/advertisers/search` | 5       | Matching advertisers with their `advertiser_id` and region                                     | `query`, `region`                                                                              |
| `GET /v1/google/company/ads`                  | 5       | One advertiser's ad history: creative id, ad URL, advertiser name, thumbnail, first-shown date | `domain` or `advertiser_id`, `platform`, `format`, `start_date`, `end_date`, `topic`, `cursor` |
| `GET /v1/google/ad`                           | 5       | One ad's own copy and creative detail                                                          | `url` (the creative URL from a list row)                                                       |

Start from a domain if you have one. When all you have is a brand name, resolve it first with `adlibrary/advertisers/search`, which defaults to searching the US. Pass `region` for another market.

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

# 2. Their ads, filtered to YouTube video creatives this year
curl "https://www.socialcrawl.dev/v1/google/company/ads?advertiser_id=AR01234567890123456789&platform=youtube&format=video&start_date=2026-01-01" \
  -H "x-api-key: YOUR_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`, and political searches also need a `region`). It cursor-paginates.

The `url` passed to `GET /v1/google/ad` must contain both segments (`…/advertiser/{AR…}/creative/{CR…}`), because an advertiser-only URL does not identify an ad.

## Business Profiles

| Endpoint                                   | Credits | What it returns                                                                                                                      | Key parameters                                                            |
| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `GET /v1/google/business/info`             | 1       | Name, category, star rating, address, phone, coordinates, opening hours, whether the listing is claimed                              | `keyword`, `cid` or `place_id`, plus `location_name`, `language_name`     |
| `GET /v1/google/business/extended-reviews` | 5       | Reviews from the Google listing and from third-party sites such as TripAdvisor and Yelp, each with source, text, rating, owner reply | `keyword`, `cid` or `place_id`, plus `depth`, `label`, `judgments` |
| `GET /v1/google/business/questions`        | 5       | Public customer questions and their answers as one flat list, each answer linked to its question by `parent_id`                      | `keyword`, `cid` or `place_id`, plus `depth`                              |
| `GET /v1/google/business/updates`          | 1       | The posts the owner published on the profile                                                                                         | `keyword` or `cid` (no `place_id`), plus `location_name`, `language_name` |

Identify a business by `keyword` (business name plus address, for example `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. On `extended-reviews` and `questions`, `depth` runs in steps of 20 up to 1000.

Most businesses publish no owner updates, so an empty list from `business/updates` is a normal answer rather than a failure.

## Hotels

| Endpoint                       | Credits | What it returns                                                                                                       | Key parameters                                                       |
| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `GET /v1/google/hotels/search` | 1       | Candidate hotels with star rating, review score, coordinates, images, nightly price, and an opaque `hotel_identifier` | `keyword`, `check_in`, `check_out`, `location_name`, `language_name` |
| `GET /v1/google/hotels/info`   | 5       | The full record: description, address, phone, amenities, review sentiment topics, prices from several booking vendors | `hotel_identifier`, `location_name`, `language_name`                 |

`check_in` and `check_out` set the stay being priced. Omitted, they default to tomorrow for one night.

```bash title="cURL"
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: YOUR_API_KEY"
```

## All endpoints

## Platform notes

- **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.
- **No impression estimate is returned** by `company/ads` or `ad`. Google does not publish one here.
- `language_name` on the business and hotel endpoints selects the result language and defaults to English.
- `business/updates`, `business/extended-reviews` and `hotels/info` run as upstream tasks, so allow a longer client timeout on them than on the inline endpoints.

## Labels

`/v1/google/business/extended-reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Google News](/docs/google_news.md): Headlines with country, language, outlet, and date-window filters.
- [Naver](/docs/naver.md): The deeper index for Korean-language web, blog, and community results.
- [Place schema](/docs/schema/place.md): The unified shape a business listing comes back in.