Google Ads

Query Google Ads

Queries the dedicated Google Ads library. Networks, audience countries, and Google category ids map to verified google-ads-search fields.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

search?array<string>

Optional Google advertiser/domain search terms.

status?string

Default"all"

Value in"active" | "inactive" | "all"

networks?array<>

Google delivery networks. Values are normalized to the casing used by the Google Ads search index.

categoryIds?array<number>

Google category ids returned by GET /v1/google-ads/facets/categories. These correspond to the app legacy niches parameter.

audienceCountries?

Audience-country filter. This is intentionally distinct from advertiser/shop creation country.

publishedAfter?string

Formatdate-time

publishedBefore?string

Formatdate-time

minDaysRunning?number

Range0 <= value

maxDaysRunning?number

Range0 <= value

minReach?number

Range0 <= value

maxReach?number

Range0 <= value

sortBy?string

Default"newest"

Value in"newest" | "reach" | "longestRunning"

order?string

Default"desc"

Value in"asc" | "desc"

page?object

Default1

Range1 <= value

limit?object

Default25

Range1 <= value <= 50

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/google-ads/query" \  -H "Content-Type: application/json" \  -d '{    "status": "active",    "networks": [      "shopping"    ],    "categoryIds": [      24    ],    "audienceCountries": {      "include": [        "US"      ]    },    "sortBy": "newest",    "order": "desc",    "page": 1,    "limit": 25  }'

{
  "requestId": "string",
  "data": [
    {
      "id": "google_123",
      "googleAdId": "string",
      "status": "active",
      "network": "search",
      "firstSeenAt": "2019-08-24T14:15:22Z",
      "lastSeenAt": "2019-08-24T14:15:22Z",
      "daysRunning": 0,
      "media": {
        "type": "image",
        "url": "string",
        "format": "string"
      },
      "advertiser": {
        "id": "string",
        "name": "string",
        "shopName": "string",
        "domain": "string",
        "websiteId": "string",
        "logoUrl": "string",
        "liveAds": {
          "google": 0,
          "all": 0
        }
      },
      "reach": {
        "value": 0,
        "lowerBound": 0,
        "upperBound": 0
      },
      "audience": {
        "mainCountry": "string",
        "countries": [
          {
            "code": "US",
            "percentage": 80,
            "reach": 0
          }
        ],
        "remarketing": true,
        "interest": true
      }
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "totalPages": 0
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Returns the normalized Google delivery networks accepted by POST /v1/google-ads/query.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/google-ads/facets/networks"

{
  "requestId": "string",
  "data": [
    {
      "value": "shopping",
      "label": "Shopping",
      "adsCount": 0
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Returns audience country codes observed in the Google Ads search index.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

search?string

Lengthlength <= 200

limit?object

Default100

Range1 <= value <= 500

offset?object

Default0

Range0 <= value

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/google-ads/facets/countries"

{
  "requestId": "string",
  "data": [
    {
      "value": "shopping",
      "label": "Shopping",
      "adsCount": 0
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Returns the Google category ids accepted by categoryIds on POST /v1/google-ads/query.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

search?string

Lengthlength <= 200

limit?object

Default100

Range1 <= value <= 500

offset?object

Default0

Range0 <= value

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/google-ads/facets/categories"

{
  "requestId": "string",
  "data": [
    {
      "id": 24,
      "name": "Women's Clothing",
      "path": "string",
      "parentId": 0,
      "advertiserUsageCount": 0
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Query Google Ads

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

List Google Ads network facets

Authorization

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

List Google Ads audience-country facets

Authorization

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

List Google Ads category facets

Authorization

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Google Ads

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`