Google Ads

Search Google Ads creatives with the same filters as the in-app Google Ads tab. Use GET /api/v1/google-ads with your API key (dashboard /api/google-ads is session-oriented).

OBTENIR/api/v1/google-ads

Search Google Ads creatives from the WinningHunter index.

Send Clé X-API on every request.

Query parameters

rechercherstring
Free-text search. Alias: keyword.
searchkeywordstring
Search scope (All, landingurl, adtext, …).
Default: Tous
pageinteger
1-based page index.
Default: 1
limiteinteger
Page size; max 48.
Default: 24
trierstring
e.g. lastseen, firstseen, reach, adspend, days_running.
Default: lastseen
sort_dirstring
Default: descValues: asc desc
statusstring
active | inactive. Alias: is_active=1/0.
country_incstring
country_excstring
formatstring
image | video | text | …
platformstring
date_de_débutstring
Last shown from (Y-m-d).
date_tostring
first_seen_fromstring
first_seen_tostring
days_minstring
days_maxstring
reach_minstring
reach_maxstring
adspend_minstring
adspend_maxstring
adspend_cpmstring
CPM used for spend estimates.
Default: 11
domainstring
visits_minstring
visits_maxstring

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/google-ads?search=skincare%20serum&searchkeyword=All&page=1&limit=24&sort=lastseen&sort_dir=desc&status=string&country_inc=US&country_exc=string&format=string&platform=string&date_from=string&date_to=string&first_seen_from=string&first_seen_to=string&days_min=string&days_max=string&reach_min=string&reach_max=string&adspend_min=string&adspend_max=string&adspend_cpm=11&domain=string&visits_min=string&visits_max=string"

const res = await fetch(`${ORIGIN}/api/v1/google-ads?search=skincare%20serum&searchkeyword=All&page=1&limit=24&sort=lastseen&sort_dir=desc&status=string&country_inc=US&country_exc=string&format=string&platform=string&date_from=string&date_to=string&first_seen_from=string&first_seen_to=string&days_min=string&days_max=string&reach_min=string&reach_max=string&adspend_min=string&adspend_max=string&adspend_cpm=11&domain=string&visits_min=string&visits_max=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/google-ads?search=skincare%20serum&searchkeyword=All&page=1&limit=24&sort=lastseen&sort_dir=desc&status=string&country_inc=US&country_exc=string&format=string&platform=string&date_from=string&date_to=string&first_seen_from=string&first_seen_to=string&days_min=string&days_max=string&reach_min=string&reach_max=string&adspend_min=string&adspend_max=string&adspend_cpm=11&domain=string&visits_min=string&visits_max=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": [
        {
            "productid": "gads_8471028374650192",
            "doc_id": "gads_8471028374650192",
            "creative_id": "CR8471028374650192",
            "platform": "google",
            "pageName": "Glow Beauty Co.",
            "advertiser_name": "Glow Beauty Co.",
            "advertiser_id": "AR1234567890",
            "page_id": "AR1234567890",
            "caption": "Vitamin C Serum — Brighter Skin in 2 Weeks",
            "headline": "Vitamin C Serum — Brighter Skin in 2 Weeks",
            "copy": "Dermatologist-tested. Free shipping over $35.",
            "description": "Dermatologist-tested. Free shipping over $35.",
            "urlStore": "https://glowbeautyco.com",
            "domain": "glowbeautyco.com",
            "target_domain": "glowbeautyco.com",
            "format": "video",
            "google_platform": "youtube",
            "media_type": "video",
            "is_video": true,
            "is_active": true,
            "daysrunning": 128,
            "first_shown_at": "2024-11-08T00:00:00Z",
            "last_shown_at": "2026-03-14T00:00:00Z",
            "lastSeen": "2026-03-14T00:00:00Z",
            "total_views": 150000,
            "total_adspend": 1650,
            "ad_reach_lower": 120000,
            "ad_reach_upper": 150000,
            "countries": [
                "US",
                "CA"
            ],
            "regions": [
                {
                    "country_code": "US"
                }
            ],
            "store_traffic": {
                "monthly_visits": 185000,
                "domain": "glowbeautyco.com"
            },
            "transparency_ad_url": "https://adtransparency.google.com/…",
            "adspend_cpm": 11,
            "saved": false,
            "hidden": false
        }
    ],
    "total": 842,
    "total_relation": "eq",
    "pagination": {
        "page": 1,
        "limit": 24,
        "total": 842,
        "pages": 36,
        "total_relation": "eq"
    },
    "adspend_cpm": 11
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "WinningHunter Basic plan or higher required"
}

{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
    "credits": {
        "used": 20000,
        "limit": 20000,
        "remaining": 0,
        "addon_remaining": 0,
        "total_remaining": 0
    },
    "purchase": {
        "url": "https://…/checkout-api-credits?credits=…"
    }
}

{
    "success": false,
    "error": "lookup_failed"
}

Pagination: 1-based page + limite (max 48). Global browse returns share-card objects in data[] (dashboard card shape: pageName, daysrunning, urlStore, …) — not the raw list-item shape. regions[] always includes country_code when present; impressions_lower / impressions_upper appear only when indexed on the creative.

Store-scoped Google Ads

Browse Google Ads for a tracked Shopify store (same data as the store detail Google Ads tab). Requires storeid (WinningHunter store id). Each route costs 1 crédit API.

Method	Chemin	Objectif
OBTENIR	`/api/v1/store/google-ads`	Paginated creatives (`page`, `limite`, filters)
OBTENIR	`/api/v1/store/google-ads/count`	Total count for store domains
OBTENIR	`/api/v1/store/google-ads/detail`	Single creative (`doc_id`)
OBTENIR	`/api/v1/store/google-ads/overview`	Store-level KPI rollup
OBTENIR	`/api/v1/store/google-ads/advertiser`	Advertiser rollup (`advertiser_id`)
OBTENIR	`/api/v1/store/google-ads/creative`	Creative metrics history (`creative_id`)

OBTENIR/api/v1/store/google-ads

Google Ads creatives linked to a tracked store domain.

Send Clé X-API on every request.

Query parameters

storeidstringrequired
WinningHunter tracked store id.
pageinteger
Default: 1
limiteinteger
Max 100.
Default: 24
rechercherstring
formatstring
is_activeboolean
trierstring
Default: lastseen
sort_dirstring
Default: descValues: asc desc

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads?storeid=string&page=1&limit=24&search=string&format=string&is_active=true&sort=lastseen&sort_dir=desc"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads?storeid=string&page=1&limit=24&search=string&format=string&is_active=true&sort=lastseen&sort_dir=desc`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads?storeid=string&page=1&limit=24&search=string&format=string&is_active=true&sort=lastseen&sort_dir=desc",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "domain": "glowbeautyco.com",
    "domains": [
        "glowbeautyco.com",
        "www.glowbeautyco.com"
    ],
    "items": [
        {
            "doc_id": "gads_8471028374650192",
            "creative_id": "CR8471028374650192",
            "advertiser_id": "AR1234567890",
            "advertiser_name": "Glow Beauty Co.",
            "domain": "glowbeautyco.com",
            "format": "video",
            "platform": "youtube",
            "is_active": true,
            "headline": "Vitamin C Serum — Brighter Skin in 2 Weeks",
            "description": "Dermatologist-tested. Free shipping over $35.",
            "days_running": 128,
            "first_shown_at": "2024-11-08T00:00:00Z",
            "last_shown_at": "2026-03-14T00:00:00Z",
            "ad_reach_lower": 120000,
            "ad_reach_upper": 150000,
            "saved": false
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 24,
        "total": 842,
        "pages": 36
    }
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset."
}

OBTENIR/api/v1/store/google-ads/count

Total Google Ads count for a tracked store's domains.

Send Clé X-API on every request.

Query parameters

storeidstringrequired

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads/count?storeid=string"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads/count?storeid=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads/count?storeid=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "count": 842,
    "domain": "glowbeautyco.com",
    "domains": [
        "glowbeautyco.com"
    ]
}

OBTENIR/api/v1/store/google-ads/detail

Single creative by doc id.

Send Clé X-API on every request.

Query parameters

doc_idstringrequired

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads/detail?doc_id=string"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads/detail?doc_id=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads/detail?doc_id=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "item": {
        "doc_id": "AR15309357617457922049_CR09795573152263176193",
        "creative_id": "CR09795573152263176193",
        "advertiser_id": "AR15309357617457922049",
        "advertiser_name": "Comfrt LLC",
        "advertiser_ads_count": 1776,
        "domain": "comfrt.com",
        "target_domain": "comfrt.com",
        "format": "image",
        "platform": "display",
        "is_active": true,
        "headline": "Comfrt Airplane Mode Travel Hoodie | Navy | Oversized | S | Small",
        "description": "Comfrt · [Original currency]",
        "image_url": "https://pub-ad0474935e8d45af9db270f106d272ec.r2.dev/google-ads-previews/AR15309357617457922049_CR09795573152263176193.png",
        "media_url": "https://pub-ad0474935e8d45af9db270f106d272ec.r2.dev/google-ads-previews/AR15309357617457922049_CR09795573152263176193.png",
        "is_video": false,
        "country_codes": [
            "PL",
            "BE",
            "ES",
            "FR",
            "DE"
        ],
        "regions": [
            {
                "country_code": "PL"
            },
            {
                "country_code": "BE"
            }
        ],
        "region_count": 15,
        "days_running": 113,
        "first_shown_at": "2026-05-02T14:50:11.825186Z",
        "last_shown_at": "2026-08-24T10:11:53.837228Z",
        "store_traffic": {
            "monthly_visits": 14334941,
            "storeid": "b7963cd2df6f01b2656a02c06f5d9d58",
            "domain": "comfrt.com"
        },
        "transparency_ad_url": "https://adstransparency.google.com/advertiser/AR15309357617457922049/creative/CR09795573152263176193?region=anywhere",
        "saved": false
    }
}

{
    "success": false,
    "error": "doc_id_required"
}

{
    "success": false,
    "error": "not_found"
}

OBTENIR/api/v1/store/google-ads/overview

Store-level Google Ads KPI rollup.

Send Clé X-API on every request.

Query parameters

storeidstringrequired

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads/overview?storeid=string"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads/overview?storeid=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads/overview?storeid=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "overview": {
        "domain": "comfrt.com",
        "domains": [
            "comfrt.com",
            "comfrtclothing.myshopify.com"
        ],
        "global_ads": 1995,
        "total_ads": 2015,
        "reach": 10139000,
        "reach_eu_uk": 9747000,
        "reach_eu_uk_pct": 96.1,
        "growth_pct": 11.1,
        "platform_mix": [
            {
                "key": "display",
                "label": "Display",
                "count": 1323,
                "pct": 66.3
            },
            {
                "key": "youtube",
                "label": "YouTube",
                "count": 480,
                "pct": 24.1
            },
            {
                "key": "search",
                "label": "Search",
                "count": 162,
                "pct": 8.1
            }
        ],
        "countries": [
            {
                "country_code": "US",
                "count": 1009,
                "pct": 50.6
            },
            {
                "country_code": "CA",
                "count": 256,
                "pct": 12.8
            }
        ],
        "history": {
            "page_reach_upper": {
                "2026-08-17": 2763000,
                "2026-08-24": 10139000
            },
            "active_ads_count": {
                "2026-08-17": 1795,
                "2026-08-24": 1995
            },
            "ads_launched_count": {
                "2026-08-17": 1,
                "2026-08-24": 82
            }
        }
    }
}

OBTENIR/api/v1/store/google-ads/advertiser

Advertiser rollup plus trends/history.

Send Clé X-API on every request.

Query parameters

advertiser_idstringrequired

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads/advertiser?advertiser_id=string"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads/advertiser?advertiser_id=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads/advertiser?advertiser_id=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "advertiser": {
        "advertiser_id": "AR15309357617457922049",
        "advertiser_name": "Comfrt LLC",
        "domain": "comfrt.com",
        "total_ads_count": 1796,
        "active_ads_count": 1995,
        "ad_count_lower": 3000,
        "ad_count_upper": 4000,
        "page_reach_upper": 10118000,
        "logo_url": "https://www.google.com/s2/favicons?domain=comfrt.com&sz=64",
        "top_countries_by_ads": [
            {
                "country_code": "DE",
                "count": 983
            },
            {
                "country_code": "CA",
                "count": 240
            }
        ],
        "top_countries_by_impressions": [
            {
                "country_code": "DE",
                "impressions_upper": 315000
            },
            {
                "country_code": "IE",
                "impressions_upper": 574000
            }
        ],
        "updated_at": "2026-08-24T10:55:33.660563+00:00"
    },
    "trends": {
        "active_ads_pct": 11.1,
        "page_reach_pct": 267
    },
    "history": {
        "page_reach_upper": {
            "2026-08-17": 2763000,
            "2026-08-24": 10139000
        },
        "active_ads_count": {
            "2026-08-17": 1795,
            "2026-08-24": 1995
        },
        "ads_launched_count": {
            "2026-08-17": 1,
            "2026-08-24": 82
        }
    }
}

{
    "success": false,
    "error": "advertiser_id_required"
}

{
    "success": false,
    "error": "not_found"
}

OBTENIR/api/v1/store/google-ads/creative

Weekly impression/reach history for one creative.

Send Clé X-API on every request.

Query parameters

creative_idstringrequired

Demande

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/store/google-ads/creative?creative_id=string"

const res = await fetch(`${ORIGIN}/api/v1/store/google-ads/creative?creative_id=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/store/google-ads/creative?creative_id=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "creative_id": "CR09795573152263176193",
    "history": {
        "page_reach_upper": {
            "2026-08-17": 0,
            "2026-08-24": 12000
        }
    }
}

{
    "success": false,
    "error": "creative_id_required"
}

Shape notes: histoire is an object of metric series (not an array). Each series maps YYYY-MM-DD → number. Creative history is often sparse (one or a few weeks). Overview/advertiser history may also include platform_mix week buckets.

Shape split:

Route	Creatives array key	Item shape
`GET /api/v1/google-ads`	`data`	Share card (`daysrunning`, `pageName`, …)
`GET /api/v1/store/google-ads`	`items`	List item (`days_running`, `headline`, …)

Session equivalents remain at /api/store/google-ads/* for browser use.

Google Ads

Query parameters

Store-scoped Google Ads#

Query parameters

Query parameters

Query parameters

Query parameters

Query parameters

Query parameters

Store-scoped Google Ads