Retrieve advertising search term performance

curl --request GET \
  --url https://mm-api.merchantspring.io/advertising/searchTerms \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://mm-api.merchantspring.io/advertising/searchTerms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mm-api.merchantspring.io/advertising/searchTerms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mm-api.merchantspring.io/advertising/searchTerms"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mm-api.merchantspring.io/advertising/searchTerms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "channel_id": "<string>",
      "ad_type": "<string>",
      "search_term": "<string>",
      "impressions": 123,
      "clicks": 123,
      "cost": 123,
      "attributed_sales": 123,
      "attributed_sales_same_sku": 123,
      "attributed_conversions": 123,
      "attributed_conversions_same_sku": 123,
      "attributed_units_ordered": 123,
      "attributed_units_ordered_same_sku": 123,
      "acos": 123,
      "click_through_rate": 123,
      "cost_per_click": 123,
      "conversion_rate": 123,
      "cost_per_acquisition": 123,
      "roas": 123
    }
  ],
  "pagination": {
    "pageIndex": 123,
    "pageSize": 123,
    "count": 123
  },
  "meta": {
    "currency": "<string>"
  }
}

Advertising

Retrieve advertising search term performance

Returns paginated advertising search term performance for a single channel for the selected date range, optionally filtered to specific campaigns, ad groups, keywords, match types or a search term. Metrics are aggregated across every keyword sharing the same search term (within the same ad type), so campaignId/adGroupId/keywordId/matchType act only as filters - the response does not include keyword/campaign-level fields. Values are currency-adjusted based on the store’s country and the requested currency. Supports sorting by any response column and zero-based page indexing.

GET

advertising

searchTerms

curl --request GET \
  --url https://mm-api.merchantspring.io/advertising/searchTerms \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://mm-api.merchantspring.io/advertising/searchTerms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mm-api.merchantspring.io/advertising/searchTerms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mm-api.merchantspring.io/advertising/searchTerms"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mm-api.merchantspring.io/advertising/searchTerms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "channel_id": "<string>",
      "ad_type": "<string>",
      "search_term": "<string>",
      "impressions": 123,
      "clicks": 123,
      "cost": 123,
      "attributed_sales": 123,
      "attributed_sales_same_sku": 123,
      "attributed_conversions": 123,
      "attributed_conversions_same_sku": 123,
      "attributed_units_ordered": 123,
      "attributed_units_ordered_same_sku": 123,
      "acos": 123,
      "click_through_rate": 123,
      "cost_per_click": 123,
      "conversion_rate": 123,
      "cost_per_acquisition": 123,
      "roas": 123
    }
  ],
  "pagination": {
    "pageIndex": 123,
    "pageSize": 123,
    "count": 123
  },
  "meta": {
    "currency": "<string>"
  }
}

Authorizations

x-api-key

string

header

required

Query Parameters

channelId

string

required

Channel ID. Only a single channel is supported for this endpoint.

campaignId

string[]

Filter to search terms belonging to the given campaign(s). Repeatable (max 10), numeric.

adGroupId

string[]

Filter to search terms belonging to the given ad group(s). Repeatable (max 10), numeric.

keywordId

string[]

Filter to search terms belonging to the given keyword(s). Repeatable (max 10), numeric.

matchType

enum<string>[]

Filter to search terms matched via the given keyword match type(s). Repeatable, case-insensitive.

Available options:

BROAD,

EXACT,

PHRASE,

TARGETING_EXPRESSION,

TARGETING_EXPRESSION_PREDEFINED

searchTerm

string

Case-insensitive substring filter on the customer search term.

fromDate

integer

Start of date range as unix epoch seconds. Defaults to 30 days ago.

toDate

integer

End of date range as unix epoch seconds. Defaults to now. The range must not exceed 6 months.

currency

string

3-letter ISO currency code (default USD).

sortKey

enum<string>

default:cost

Response column to sort by (default cost). Note: attributed_sales_same_sku, attributed_conversions_same_sku and attributed_units_ordered_same_sku are always 0 for ad_type SB, so sorting by one of them won't distinguish between SB rows.

Available options:

ad_type,

search_term,

impressions,

clicks,

cost,

attributed_sales,

attributed_sales_same_sku,

attributed_conversions,

attributed_conversions_same_sku,

attributed_units_ordered,

attributed_units_ordered_same_sku,

acos,

click_through_rate,

cost_per_click,

conversion_rate,

cost_per_acquisition,

roas

sortOrder

enum<string>

Sort direction (default desc).

Available options:

asc,

desc

pageIndex

integer

default:0

Zero-based page index (default 0).

Required range: x >= 0

pageSize

integer

default:10

Number of (aggregated) search term rows per page, max 100 (default 10).

Required range: 1 <= x <= 100

Response

Successful operation

data

object[]

Show child attributes

pagination

object

Show child attributes