Commerce and markets · SearchApi

trends.search

Returns Google Trends relative interest and related-query or topic data. Indices and breakout markers are not absolute search counts. Refresh changes the query, region or time window.

Operation: POST /v1/capabilities/trends.search/execute
operationId: executeTrendsSearch
Typical credits: 4
Search deadline: 40 s server-side
Paging: single result
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per provider dataset; cached details are free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/trends.search/execute, JSON, validated against the TrendsSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of trends.search
Field	Type	Required	Default	Constraints and description
query	string	yes		min length 1, max length 500 Up to five comma-separated search terms for time series or geography; one term for related queries/topics.
data_type	"TIMESERIES" \| "GEO_MAP" \| "RELATED_QUERIES" \| "RELATED_TOPICS"	no	"TIMESERIES"
geo	string	no		max length 30, pattern ^[A-Z0-9-]*$ Google Trends geography code; omit for worldwide.
region	"COUNTRY" \| "REGION" \| "DMA" \| "CITY"	no
category	integer	no		min 0
property	"web" \| "images" \| "news" \| "froogle" \| "youtube"	no	"web"
time_range	string	no	"today 12-m"	pattern ^(now (1-H\|4-H\|1-d\|7-d)\|today (1-m\|3-m\|12-m\|5-y)\|all\|[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{4}-[0-9]{2}-[0-9]{2})$
timezone_offset_minutes	integer	no	0	min -1439, max 1439 Provider timezone offset in minutes, used to bucket observations; default UTC.

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Time series and geography accept up to five comma-separated terms; related queries and topics accept one.
region requires data_type: "GEO_MAP"; region: "COUNTRY" requires worldwide geography (no geo).

Examples

Interest over time

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/trends.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"electric cars"}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the TrendsSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of trends.search
Key	Type	Presence
data_type	string	always
time_range	string	always
source	string	always
fetched_at	string	always

Caveats

Returns zero or one record.
Details are served from the record stored at search time without a provider call. When that stored detail is no longer available the call returns 410 session_expired ("the cached record detail is no longer available. Run the search again."); it is never re-fetched.

Follow-ups

Paging: Single result; more is refused with 400 invalid_request.
Update: Refresh or change the trend query and time window. Params accept any subset of the request fields (TrendsSearchUpdateParams). update is a billed refresh ($0.004): the dataset is fetched again with the merged parameters.
Record actions:
- details: Cached trend series or related record.
Detail behaviour: Stored at search time; details is free and never calls the provider. details returns the stored dataset at no charge.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/trends.search/execute", {
  body: {
    "query": "electric cars"
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);