Google Ads Transparency Center

Perform Search

Overview

Method	Endpoint	Version	Description
`POST`	`/api/v1/open/search`	v1	Google Search API endpoint for retrieving search results

Request Headers

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Must be set to `application/json`
`Accept`	`string`	No	Response format (defaults to `application/json`)

Authentication

API Key Authentication - Pass the API key as a request parameter: api_key=your_api_key - Example: "api_key": "your_api_key_here"

Request Example

curl -X POST "https://domain/api/v1/open/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    // ...
  }'

Response Format

All responses follow a standardized JSON structure:

{
  "code": 200,
  "msg": "Success",
  "reqId": "req_1234567890",
  "timestamp": "2025-01-08T10:30:00Z",
  "data": {
    // Response data object
  }
}

HTTP Status Codes

Code	Status	Description	Retry
200	OK	Request successful	No

Request Parameters

Parameter	Type	Required	Description	Default
`api_key`	`string`	Yes	API key for authentication
`engine`	`string`	Yes	Search engine type, currently engine value is `google_ads_transparency_center`	google
`advertiser_id`	`string`	Yes	Parameter defines the Google Advertiser ID. It can be found in the Ads Transparency Center advertiser URL. For example, the advertiser ID for the URL https://adstransparency.google.com/advertiser/AR17828074650563772417 is AR17828074650563772417(Tesla Inc). It accepts either a single ID or multiple IDs separated by commas (,). Example, Single ID: AR17828074650563772417 Multple IDs: AR17828074650563772417,AR03911981557522366465,... Alternatively, text can be used for free-text search.
`text`	`string`	No	Parameter defines the text you want to search, typically related to a domain search within the context of Google Ads. You can use anything that you would normally use in a standard Google Ads Transparency Center search. It can be used as an alternative to advertiser_id. The advertiser_id can be optional when text is present.
`platform`	`string`	No	Parameter defines the target platform where ads are displayed. When not set, it will return results from all platforms (default). Available options: PLAY - Google Play, MAPS - Google Maps, SEARCH - Google Search, SHOPPING - Google Shopping, YOUTUBE - YouTube.
`political_ads`	`string`	No	The parameter determine if the advertiser promotes political advertisement. Political advertisement is a different category than regular advetisements, and will not appear on the results unless this parameter is set to true. If this parameter is set to true, only political advertisements will appear on the results. By default it is false. This parameter can only be used alonside with the region parameter.	false
`region`	`string`	No	Parameter defines from where you want the search to originate. By default it search results from anywhere. Head to the Google Ads Transparency Center Regions for a full list of supported regions.
`start_date`	`string`	No	Parameter defines the start date of time period you want to limit the search to. This parameter can't be used with time parameters. start_date with blank end_date produces date range FROM start_date TO today. This parameter overrides cdr and cd_min components of tbs parameter.
`end_date`	`string`	No	Parameter defines the end date of time period you want to limit the search to. This parameter can't be used with time parameters. end_date with blank start_date produces date range BEFORE end_date. This parameter overrides cdr and cd_max components of tbs parameter.
`creative_format`	`string`	No	Parameter defines the format you want to filter by. Only search results with a similar format will be returned. Available options: text - Text, image - Image, video - Video
`num`	`number`	No	Parameter defines the maximum number of results to return. (e.g., 40 (default) returns 40 results and 100 returns 100 results).
`next_page_token`	`string`	No	Parameter defines the next page token. It is used for retrieving the next page results.
`html`	`string`	No	Whether to return HTML format, 1-yes, 0-no	0

Response Example

{
  "reqId": "1984168106343272448",
  "code": 200,
  "msg": "OK",
  "data": {
    "search_metadata": {
      "raw_html_file": "oss_html",
      "total_time_taken": 1.768001541,
      "id": "1984168106343272448",
      "json_endpoint": "oss_json",
      "created_at": "2025-10-31 15:58:35",
      "processed_at": "2025-10-31 15:58:39",
      "google_url": "https://adstransparency.google.com/advertiser/AR07223290584121737217",
      "status": "Success"
    },
    "search_information": {
      "time_taken_displayed": 0.076,
      "total_results": "",
    },
    "search_parameters": {
      "engine": "google_ads_transparency_center",
      "html": "0",
      "google_domain": "adstransparency.google.com",
      "q": "AR07223290584121737217",
      "advertiser_id": "AR07223290584121737217",
    },
    "ad_creatives": [
        {
            "advertiser_id": "AR07223290584121737217",
            "advertiser": "Bloomberg L.P",
            "ad_creative_id": "CR14106866074221805569",
            "format": "image",
            "image": "https://i.ytimg.com/vi/3YcKLd410tw/hqdefault.jpg",
            "width": "480",
            "height": "360",
            "details_link": "https://adstransparency.google.com/advertiser/AR07223290584121737217/creative/CR14106866074221805569?region=MY"
        }
    ]
  }
}

Complete Response Parameters Overview

search_metadata

object Contains metadata about the search execution

Parameter	Type	Description	Applicable Terminal
`id`	`string`	Unique identifier for the search request	desktop
`json_endpoint`	`string`	Provide an interface endpoint for searching related JSON data, through which JSON-formatted search data can be obtained	desktop
`created_at`	`string`	The timestamp when the search request was created, recording the time when the search was initiated	desktop
`processed_at`	`string`	The timestamp when the search results were processed and became available for return, recording the time point from processing to completion of the search	desktop
`google_url`	`string`	The Google search URL, which contains the search keyword "coffee" along with language parameters (hl=en for English), regional parameters (gl=us for the United States), and other search parameters, used to redirect to the corresponding Google search page	desktop
`status`	`string`	Status of the search execution (e.g., Success)	desktop
`raw_html_file`	`string`	Identifier for the original HTML file	desktop
`total_time_taken`	`number`	The total time spent on the entire search process (including request sending, result parsing, and other stages)	desktop

search_information

object Contains information about the search results

Parameter	Type	Description	Applicable Terminal
`time_taken_displayed`	`number`	TDisplay time (i.e., the time spent on displaying the search results)	desktop
`total_results`	`string`	Total results count (the total number of results returned by this search)	desktop

search_parameters

object Contains the parameters used for the search

Parameter	Type	Description	Applicable Terminal
`engine`	`string`	Search engine used for this query (e.g., google_web)	desktop
`google_domain`	`string`	Specifies the corresponding Google domain (e.g., google.com, etc., used to distinguish Google services in different regions/locales)	desktop
`device`	`string`	Device type used during search (e.g., desktop)	desktop
`html`	`string`	When HTML=0, returns JSON; when HTML=1, returns HTML; when HTML=2, returns both JSON and HTML	desktop
`advertiser_id`	`number`	Google Advertiser ID for this query (found in the advertiser URL within the Ad Transparency Center)	desktop
`q`	`string`	‌same as the `advertiser_id` parameter	desktop

ad_creatives

object[] Ads Transparency Center‌ (ad transparency and disclosure-related content)

Parameter	Type	Description	Applicable Terminal
`advertiser_id`	`string`	Advertiser Unique ID‌ (used to distinguish between different advertising entities in the ad system)	desktop
`advertiser`	`string`	Advertiser's name, i.e., the entity that places the advertisement	desktop
`ad_creative_id`	`string`	Unique identifier for a single ad creative, used for locating and managing specific ad creative content	desktop
`format`	`string`	Ad creative presentation format	desktop
`image`	`string`	Image format ad creative resource link	desktop
`width`	`string`	Image ad creative width	desktop
`height`	`string`	Image ad creative height	desktop
`details_link`	`string`	Ad creative transparency details link, which leads to more information about the advertisement	desktop