Zernio
APIFor you
Zernio
APIFor you
API Reference

Insights

List lead conversationsGETGoogle Local Services Ads leadsGETSubmit async insights reportPOSTGet ad analyticsGETPoll an async insights report runGETGoogle Ads search terms reportGETGet campaign analyticsGETPer-creative performance inside TikTok Smart+ adsGETGet historical keyword metricsPOSTGenerate keyword ideasPOSTFlexible live insights queryGET
Dashboard
OverviewPlatformsAPI ReferenceResources
Insights

Get historical keyword metrics

Gets historical search volume, competition and bid ranges for up to 1,000 keywords from Google Keyword Planner.

Google Ads only. Runs Keyword Planner's generateKeywordHistoricalMetrics for up to 1,000 exact keywords: historical search volume, competition and top-of-page bid ranges, plus averageCpcMicros when includeAverageCpc is set. Rows come back verbatim; counters are int64s encoded as strings, bid/CPC values are micros of the account currency.


PlatformsGoogle
POST
/v1/ads/keywords/historical-metrics

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.adinsights.generateKeywordHistoricalMetrics({  body: {    accountId: 'account_abc123',    keywords: [      'string',    ],  },});console.log(data);
{  "customerId": "string",  "data": [    {}  ],  "aggregateMetricResults": {}}
Was this page helpful?

Per-creative performance inside TikTok Smart+ ads

Breaks a Smart+ ad (or ad group) down by creative material, one row per Spark post, video or image, from TikTok's Smart+ material report. For a Spark post `tiktokItemId` is the TikTok post id. Conversion metrics are TikTok web (pixel) events. `purchases`, `purchaseValue` and `roas` come from Complete Payment, or from Place an Order (legacy ON_WEB_ORDER pixels) when that reports more; the two are never summed. TikTok allows two dimensions per report, so rows are keyed by the Smart+ ad (`level=ad`) or by the ad group (`level=adGroup`), not both. A row is identified by `smartPlusAdId` + `materialId` at `level=ad` and by `adGroupId` + `materialId` at `level=adGroup`; each appears once across all pages. Rows are sorted by `spend` descending, then the Smart+ ad or ad group id, then `materialId`, and the full result is cached for 10 minutes per account, advertiser and query, so pages read within that window are consistent and `totalRows` counts distinct rows. When the result spans more than one TikTok page it is read per Smart+ ad (or ad group) listed on the advertiser, every status included, and those reads can return more rows than TikTok's unfiltered report declares, so `totalRows` can be larger than that count; when the unfiltered report fits one page (100 rows or fewer) it is served as is. Each TikTok read is checked against the row count it declares itself, and a short read is retried once. A shortfall of at most 2 rows (or 1% of the rows, whichever is more) is served with `missingRows` set to that number; a larger one answers 502 instead of a short result. Metrics TikTok returns empty come back as null.

Generate keyword ideas

Suggests new keywords from seed keywords or a website using Google Keyword Planner, with search volume, competition and bid estimates. Google Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL, or both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex, top-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid values are micros of the account currency. Omitting `countries` targets worldwide.

accountId*string

Zernio googleads SocialAccount id.

adAccountId?string

Platform ad account ID (Google customer ID, digits only).

customerId?string
Deprecated

Alias of adAccountId, kept for existing callers

keywords*array<>
Items1 <= items <= 1000
countries?array<>

ISO 3166-1 alpha-2 country codes. Omitted = worldwide.

Items1 <= items <= 10
languageConstantId?string

Google languageConstant id (1000 = English).

Default"1000"
network?string
Default"GOOGLE_SEARCH"

Value in

  • "GOOGLE_SEARCH"
  • "GOOGLE_SEARCH_AND_PARTNERS"
includeAdultKeywords?boolean
includeAverageCpc?boolean

Adds averageCpcMicros to each row's keywordMetrics.