# SocialCrawl API — google endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/google

## GET /v1/google/search
Google web search
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase
- region (optional, string) — 2 letter country code, ie US, UK, CA, etc This will show results from that country
- date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted
- page (optional, integer) — Page number to retrieve
curl "https://www.socialcrawl.dev/v1/google/search?query=best restaurants in London" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/ad
Get Google ad details
Credit cost: 5 (advanced)
Parameters:
- url (required) — Ads Transparency Center CREATIVE URL — must include both the advertiser and creative segments (`…/advertiser/{AR…}/creative/{CR…}`). Get one from `/v1/google/company/ads`.
curl "https://www.socialcrawl.dev/v1/google/ad?url=https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/adlibrary/advertisers/search
Search Google Ad Library advertisers
Credit cost: 5 (advanced)
Parameters:
- query (required) — Search keyword or phrase to find advertisers in the Google Ads Transparency Center.
- region (optional, string) — 2-letter country code to search in. Defaults to US.
curl "https://www.socialcrawl.dev/v1/google/adlibrary/advertisers/search?query=lululemon" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/company/ads
List Google ads by company
Credit cost: 5 (advanced)
Parameters:
- domain (optional, string) — Company domain name to look up ads for
- advertiser_id (optional, string) — The advertiser id of the company
- topic (optional, enum: all | political) — The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU'
- region (optional, string) — The region to search for. Defaults to anywhere
- start_date (optional, string) — Start date to search for. Format: YYYY-MM-DD
- end_date (optional, string) — End date to search for. Format: YYYY-MM-DD
- platform (optional, enum: google_maps | google_play | google_search | google_shopping | youtube) — Google surface to filter ads by (e.g. youtube, google_search)
- format (optional, enum: text | image | video) — Ad format to filter by: text, image, or video
- get_ad_details (optional, string) — Set to true to get the ad details. Will cost 25 credits.
- cursor (optional, string) — Cursor to paginate through results
- Constraint: one of domain, advertiser_id (at least one required)
curl "https://www.socialcrawl.dev/v1/google/company/ads" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/business/info
Get a Google Business Profile
Credit cost: 1 (standard)
Parameters:
- keyword (optional, string) — Business name + address (e.g. 'Irving Farm New York 645 5th Ave'). Use cid/place_id when known for an exact match.
- cid (optional, string) — Google customer id (cid) of the place — the most reliable identifier.
- place_id (optional, string) — Google place_id of the place.
- location_name (optional, string) — Geographic context as 'City,Region,Country' (default 'New York,New York,United States').
- language_name (optional, string) — Result language (default 'English').
- Constraint: one of keyword, cid, place_id (at least one required)
curl "https://www.socialcrawl.dev/v1/google/business/info" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/business/extended-reviews
Get Google extended (multi-source) reviews
Credit cost: 5 (advanced)
Parameters:
- keyword (optional, string) — Business name + address. Use cid/place_id for an exact match.
- cid (optional, string) — Google customer id (cid) of the place.
- place_id (optional, string) — Google place_id of the place.
- location_name (optional, string) — Geographic context as 'City,Region,Country'.
- language_name (optional, string) — Result language (default 'English').
- depth (optional, integer) — Number of reviews to return (default 20, step 20, max 1000).
- Constraint: one of keyword, cid, place_id (at least one required)
curl "https://www.socialcrawl.dev/v1/google/business/extended-reviews" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/business/updates
Get Google Business Profile posts (updates)
Credit cost: 1 (standard)
Parameters:
- keyword (optional, string) — Business name + location (e.g. 'Toyota of Manhattan New York').
- cid (optional, string) — Google customer id (cid) of the business.
- location_name (optional, string) — Geographic context as 'City,Region,Country'.
- language_name (optional, string) — Result language (default 'English').
- Constraint: one of keyword, cid (at least one required)
curl "https://www.socialcrawl.dev/v1/google/business/updates" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/business/questions
Get Google Business Profile questions & answers
Credit cost: 5 (advanced)
Parameters:
- keyword (optional, string) — Business name + location (e.g. 'Starbucks Reserve Roastery New York').
- cid (optional, string) — Google customer id (cid) of the business.
- place_id (optional, string) — Google place_id of the business.
- location_name (optional, string) — Geographic context as 'City,Region,Country'.
- language_name (optional, string) — Result language (default 'English').
- depth (optional, integer) — Number of questions to return (default 20).
- Constraint: one of keyword, cid, place_id (at least one required)
curl "https://www.socialcrawl.dev/v1/google/business/questions" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/hotels/search
Search Google hotels
Credit cost: 1 (standard)
Parameters:
- keyword (required) — Hotel search query (e.g. 'hotels in New York').
- location_name (optional, string) — Geographic context as 'City,Region,Country'.
- language_name (optional, string) — Result language (default 'English').
- check_in (optional, string) — Check-in date (YYYY-MM-DD). Defaults to the next day.
- check_out (optional, string) — Check-out date (YYYY-MM-DD). Defaults to one night.
curl "https://www.socialcrawl.dev/v1/google/hotels/search?keyword=hotels in New York" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/google/hotels/info
Get Google hotel detail
Credit cost: 5 (advanced)
Parameters:
- hotel_identifier (required) — Opaque hotel id returned by GET /v1/google/hotels/search.
- location_name (optional, string) — Geographic context as 'City,Region,Country'.
- language_name (optional, string) — Result language (default 'English').
curl "https://www.socialcrawl.dev/v1/google/hotels/info?hotel_identifier=ChkIoYjXwK-S_okHGg0vZy8xMW1fd3MzY243EAE" \
  -H "x-api-key: sc_your_api_key_here"