Google Trends

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'googletrends'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Google Trends:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'googletrends_get_operation',
     toolInput: { name: 'YOUR_NAME' },
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "googletrends"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Google Trends:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={"name":"YOUR_NAME"},
       tool_name="googletrends_get_operation",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Get operation — Get the current status and result of a Google Trends API (alpha) long-running operation by its name
• Fetch time series — Start an asynchronous search-interest time-series query in Google Trends for one or more terms, scoped to a country or region, date range, and interval

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

googletrends_fetch_time_series#Start an asynchronous search-interest time-series query in Google Trends for one or more terms, scoped to a country or region, date range, and interval. Returns a long-running Operation envelope immediately, e.g. {"name": "v1alpha.d3f3ded6-6fbe-4625-9bf1-d71d6312c9c9", "done": false} — not the time series data itself. Use this to start a query; call googletrends_get_operation next with the returned name to poll until done and retrieve the actual search-interest results. Requires a Google Cloud project accepted into the Google Trends API alpha program, with the Search Trends API enabled.7 params▾

Start an asynchronous search-interest time-series query in Google Trends for one or more terms, scoped to a country or region, date range, and interval. Returns a long-running Operation envelope immediately, e.g. {"name": "v1alpha.d3f3ded6-6fbe-4625-9bf1-d71d6312c9c9", "done": false} — not the time series data itself. Use this to start a query; call googletrends_get_operation next with the returned name to poll until done and retrieve the actual search-interest results. Requires a Google Cloud project accepted into the Google Trends API alpha program, with the Search Trends API enabled.

NameTypeRequiredDescription

end_time_secondsintegerrequiredEnd of the time range to query, as Unix epoch seconds (UTC).

geo_codestringrequiredISO country code identifying the country or region to fetch search interest for, e.g. "US" or "CH".

start_time_secondsintegerrequiredStart of the time range to query, as Unix epoch seconds (UTC). The API covers a rolling 5-year window; convert your desired start date to epoch seconds before calling this tool.

termsarrayrequiredArray of search terms to compare, each an object with a value (the search phrase) and a type. The only confirmed type value in this alpha is "BROAD"; no other type is documented. Example: [{"value": "gold", "type": "BROAD"}]. Multiple terms can be passed in one call to compare them on a consistent scale, unlike the Trends website's 8-term UI limit.

geo_typestringoptionalHow geo_code should be interpreted. The only confirmed value is "GEO_TYPE_COUNTRY_OR_REGION" (geo_code is treated as a country/region code); this is also the default, so most callers can leave it unset.

project_idstringoptionalOptional Google Cloud project ID to bill this call's quota against, sent as the x-goog-user-project header. If omitted, Google uses the project already tied to the connected OAuth credentials — confirmed by live testing (an omitted/empty value falls back to the OAuth grant's own project rather than being rejected). Only set this to point the call at a different project you have serviceusage.services.use permission on; that project must also have the Search Trends API enabled.

time_resolutionstringoptionalInterval at which the time series is aggregated. Confirmed values are DAY, WEEK, MONTH, and YEAR; HOUR is not yet supported in this alpha. Defaults to DAY.

googletrends_get_operation#Get the current status and result of a Google Trends API (alpha) long-running operation by its name. Returns an Operation object with name and a done boolean; once done, the response includes a time series with per-point searchInterest (raw) and scaledSearchInterest (0-100 scaled, matching the Trends website) — the exact envelope beyond these fields is not fully confirmed from available sources, so treat any other fields as undocumented. Use this to poll a job after starting it with fetch_time_series; call it repeatedly until done is true. Requires an operation name returned by fetch_time_series.2 params▾

Get the current status and result of a Google Trends API (alpha) long-running operation by its name. Returns an Operation object with name and a done boolean; once done, the response includes a time series with per-point searchInterest (raw) and scaledSearchInterest (0-100 scaled, matching the Trends website) — the exact envelope beyond these fields is not fully confirmed from available sources, so treat any other fields as undocumented. Use this to poll a job after starting it with fetch_time_series; call it repeatedly until done is true. Requires an operation name returned by fetch_time_series.

NameTypeRequiredDescription

namestringrequiredOperation name to poll, copied verbatim from the "name" field returned by the fetch_time_series call that started this job (e.g. "v1alpha.d3f3ded6-6fbe-4625-9bf1-d71d6312c9c9"). Use it exactly as returned — do not strip, add, or reconstruct any prefix.

project_idstringoptionalOptional Google Cloud project ID to bill this call's quota against, sent as the x-goog-user-project header. If omitted, Google uses the project already tied to the connected OAuth credentials (confirmed by live testing) — match whatever value, if any, was used for the fetch_time_series call that started this operation.