Name: Google Trends API: Interest Over Time, Regions and Queries
Brand: martindata
SKU: api-martindata-google-trends-api
Availability: InStock
Author: API Market

# Google Trends API

## Overview

The Google Trends API returns Google Trends data for one or more keywords in a single call: interest over time, interest by region, top and rising related queries and topics, the average and peak interest, and the trend direction. Keywords can be compared on one scale, and you can choose the countries, the time range, the search type (web, images, news, YouTube or shopping), the category and the region resolution.

It is built for SEO and content teams, marketers, market researchers, product managers and AI agents that need trend data as clean JSON without handling Google Trends pages or rate blocks themselves.

## Features

*   **1 endpoint**: one POST call that explores one or more keywords.
*   **Interest over time**: weekly or daily points for the chosen time range, with average, peak and change percent.
*   **Interest by region**: country, region, city or metro level.
*   **Related queries and topics**: top and rising queries and topics for each keyword.
*   **Comparison**: compare several keywords on one scale with `compareKeywords`.
*   **Search types**: web, images, news, YouTube and shopping searches.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **SEO and content planning**: find rising queries and seasonal peaks for topics you write about.
*   **Market research**: compare demand for brands, products or categories across countries.
*   **Product teams**: track interest in a feature, competitor or technology over time.
*   **AI agents**: answer "is interest in X growing?" with real trend data.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/martindata/google-trends-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Explore keyword trends

Returns one item per keyword and country with interest over time, interest by region, related queries and topics, and trend direction. The response is `{"count": N, "items": [...]}` with one object per result.

**Method:** `POST`

**Endpoint:** `/m/google-trends-explorer`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `keywords` | body | Search terms to analyze, one per line. Any number of keywords; they can also be compared on one common scale. | array of strings | No | - | - |
| `geos` | body | Country or region codes such as US, GB, DE or US-CA. Leave empty for worldwide. Each keyword is analyzed for every location. | array of strings | No | - | - |
| `timeframe` | body | Period to analyze. | string | No | - | - |
| `customTimeframe` | body | Overrides the time range. Format: YYYY-MM-DD YYYY-MM-DD, e.g. 2024-01-01 2024-12-31. | string | No | - | - |
| `searchType` | body | Which Google search to analyze. | string | No | - | - |
| `category` | body | Google Trends category ID, 0 = all categories. | integer | No | - | - |
| `includeRegions` | body | Add interest by country, region or city. | boolean | No | - | - |
| `regionResolution` | body | Detail of the regional breakdown. Auto uses countries for worldwide and regions for a country. | string | No | - | - |
| `includeRelated` | body | Add top and rising related queries and topics. | boolean | No | - | - |
| `maxRelatedItems` | body | How many related queries and topics to keep in each list. | integer | No | - | - |
| `compareKeywords` | body | Adds comparedInterest (0-100) so all keywords are comparable, even more than Google's limit of 5. | boolean | No | - | - |
| `language` | body | Interface language for names of regions and topics, e.g. en-US, de, es. | string | No | - | - |
| `maxItems` | body | Hard limit on rows saved (and paid for). | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/google-trends-api/m/google-trends-explorer' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "keywords": [
    "chatgpt",
    "claude ai"
  ],
  "geos": [
    "US"
  ],
  "timeframe": "past_12_months",
  "searchType": "web",
  "category": 0,
  "includeRegions": true,
  "regionResolution": "auto",
  "includeRelated": true,
  "maxRelatedItems": 5,
  "compareKeywords": true,
  "language": "en-US",
  "maxItems": 3
}'
```

**Example Response (200 OK):**

```json
{
  "count": 2,
  "items": [
    {
      "averageInterest": 77.1,
      "category": 0,
      "changePercent": -5.8,
      "comparedInterest": 100,
      "geo": "US",
      "interestByRegion": [
        {
          "geoCode": "US-CA",
          "geoName": "California",
          "value": 100
        },
        {
          "geoCode": "US-NJ",
          "geoName": "New Jersey",
          "value": 92
        }
      ],
      "interestOverTime": [
        {
          "date": "2025-10-26T00:00:00Z",
          "formattedTime": "Oct 26 - Nov 1, 2025",
          "isPartial": false,
          "value": 94
        },
        {
          "date": "2025-11-02T00:00:00Z",
          "formattedTime": "Nov 2 - 8, 2025",
          "isPartial": false,
          "value": 100
        }
      ],
      "keyword": "chatgpt",
      "peakDate": "2025-11-02T00:00:00Z",
      "peakInterest": 100,
      "risingQueries": [
        {
          "formattedValue": "+3,350%",
          "query": "chatgpt caricature",
          "value": 3350
        },
        {
          "formattedValue": "+2,000%",
          "query": "how to use chatgpt effectively",
          "value": 2000
        }
      ],
      "risingTopics": [],
      "scrapedAt": "2026-11-01T20:52:59Z",
      "searchType": "web",
      "timeframe": "today 12-m",
      "topQueries": [
        {
          "formattedValue": "100",
          "query": "what is chatgpt",
          "value": 100
        },
        {
          "formattedValue": "94",
          "query": "ai chatgpt",
          "value": 94
        }
      ],
      "topTopics": [],
      "trendDirection": "flat",
      "url": "https://trends.google.com/trends/explore?q=chatgpt&geo=US&date=today+12-m"
    },
    {
      "averageInterest": 50.8,
      "category": 0,
      "changePercent": 152.9,
      "comparedInterest": 5.7,
      "geo": "US",
      "interestByRegion": [
        {
          "geoCode": "US-DC",
          "geoName": "District of Columbia",
          "value": 100
        },
        {
          "geoCode": "US-WY",
          "geoName": "Wyoming",
          "value": 97
        }
      ],
      "interestOverTime": [
        {
          "date": "2025-10-26T00:00:00Z",
          "formattedTime": "Oct 26 - Nov 1, 2025",
          "isPartial": false,
          "value": 19
        },
        {
          "date": "2025-11-02T00:00:00Z",
          "formattedTime": "Nov 2 - 8, 2025",
          "isPartial": false,
          "value": 20
        }
      ],
      "keyword": "claude ai",
      "peakDate": "2026-03-01T00:00:00Z",
      "peakInterest": 100,
      "risingQueries": [
        {
          "formattedValue": "Breakout",
          "query": "claude cowork",
          "value": 89750
        },
        {
          "formattedValue": "Breakout",
          "query": "claude mythos",
          "value": 40950
        }
      ],
      "risingTopics": [],
      "scrapedAt": "2026-11-01T20:53:01Z",
      "searchType": "web",
      "timeframe": "today 12-m",
      "topQueries": [
        {
          "formattedValue": "100",
          "query": "best ai",
          "value": 100
        },
        {
          "formattedValue": "98",
          "query": "claude code",
          "value": 98
        }
      ],
      "topTopics": [],
      "trendDirection": "rising",
      "url": "https://trends.google.com/trends/explore?q=claude+ai&geo=US&date=today+12-m"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | The body is not valid JSON, `keywords` is missing, or an option has an invalid value. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but has no active subscription to this API, or your plan quota is used up. |
| 404 | Not Found | The path does not exist. Check the endpoint path against this page. |
| 429 | Too Many Requests | You sent more than your plan's per-second limit (10 requests per second). Wait and retry, honouring the `Retry-After` header when present. |
| 500 | Internal Server Error | An unexpected error on the provider side. Retry after a short wait. |
| 503 | Service Unavailable | Google Trends could not be reached. Retry later. |

## Rate Limits

Each plan has a per-second limit (10 requests per second on every plan) and a monthly call quota shown on the pricing page. Requests over the per-second limit get a 429 response. Throttle your client, back off when you get a 429, and honour the `Retry-After` header when it is present. Each call collects live data, so it can take from a few seconds to about 30 seconds; set your client timeout to at least 60 seconds.

## FAQ

*   **Can I compare keywords?**

    Yes. Send several `keywords` with `compareKeywords: true` so they share one 0 to 100 scale.

*   **Which time ranges are supported?**

    Use `timeframe` values such as `past_7_days` or `past_12_months`, or set `customTimeframe`.

*   **How many results does one call return?**

    Up to `maxItems` results (20 by default, up to 100 per request).

*   **Is the data live?**

    Yes. Each call collects fresh data, and every item carries a `scrapedAt` time.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Google Trends data as JSON: interest over time and by region, rising and top related queries and topics, for several keywords compared on one scale.

Google Trends API: Interest Over Time, Regions and Queries