Agentic Platform
Documentation API reference Tools Skills

Tools

Google Trends

google_trends MCP Keywords

Get Google Trends data for one or more keywords.

Analyze search trend data to understand how interest in specific keywords has changed over time, compare keyword popularity, and discover seasonal trends. Data is worldwide unless a location is set; cities are widened to their region or country. Related topics and related queries are only returned when a single keyword is requested; with several keywords, only the interest-over-time graph is returned. When `save_to_tmp_storage` is enabled, the trend results are written to temporary project storage and a URL is returned instead of the inline payload.

Playground

POST
item
keywords required

List of keywords to analyze (up to 5)

config
location_id

Location ID (optional)

location_request

Location request (ex: Paris, FR), will translate to the closest Google Trends location (country or region). Leave empty or use "Worldwide" for worldwide data.

country_code

ISO3166 country code (ex: GB)

lang_code

BCP47 language code (ex: "en", "en-GB")

save_to_tmp_storage

Save the bulky result payload to Botify temporary storage and return the temporary URL instead of the payload. Use this to save output tokens.

Credits

Fixed cost per item requested, plus one search-trends request. That one request covers every keyword you pass, so asking about five terms costs the same as asking about one.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item, on top of any usage below.
Search trends 9 per request Interest-over-time data. One request covers every term you pass.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
keywords array required

List of keywords to analyze (up to 5)

max items 5

Example
{
  "keywords": [
    "string"
  ]
}

Configuration

object
Properties
location_id integer | null

Location ID (optional)

Default: null

location_request string | null

Location request (ex: Paris, FR), will translate to the closest Google Trends location (country or region). Leave empty or use "Worldwide" for worldwide data.

Default: null

country_code string | null

ISO3166 country code (ex: GB)

Default: null

lang_code string | null

BCP47 language code (ex: "en", "en-GB")

Default: null

save_to_tmp_storage boolean

Save the bulky result payload to Botify temporary storage and return the temporary URL instead of the payload. Use this to save output tokens.

Default: false

Example
{
  "location_id": null,
  "location_request": null,
  "country_code": null,
  "lang_code": null,
  "save_to_tmp_storage": false
}

Response

object
Properties
keywords array required

List of keywords analyzed

date_from string required

Start date of the trends data in YYYY-MM-DD format

date_to string required

End date of the trends data in YYYY-MM-DD format

location_id integer required

Location ID used for the Google Trends request (0 means worldwide). It can be a parent of the requested location because Google Trends does not support cities.

location_name string required

Name of the location used for the Google Trends request (ex: "Ile-de-France,France", or "Worldwide")

lang_code string required

Language code used for the Google Trends request

graph object | null

Default: null

topics object | null

Default: null

queries object | null

Default: null

results_tmp_storage_url string | null

Temporary storage URL of the trends payload (`graph`, `topics` and `queries`). Returned instead of those fields when `save_to_tmp_storage` is True.

Default: null

Example
{
  "keywords": [
    "string"
  ],
  "date_from": "string",
  "date_to": "string",
  "location_id": 0,
  "location_name": "string",
  "lang_code": "string",
  "graph": null,
  "topics": null,
  "queries": null,
  "results_tmp_storage_url": null
}

Endpoints

POST http://agents.botify.com/{organization}/{project}/google_trends/process
POST http://agents.botify.com/{organization}/{project}/google_trends/batch_process
POST http://agents.botify.com/{organization}/{project}/google_trends/async_process
POST http://agents.botify.com/{organization}/{project}/google_trends/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/google_trends/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "keywords": []
  }
}'

Over MCP

This tool is exposed as the MCP tool google_trends. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata