> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/tools/get_trends_by_region

# get_trends_by_region

> Google Trends interest for up to five keywords, state by state within a country. ₹0.33 per call; a result that finds nothing is ₹0.

## What it does

Where in a country people search most for up to five keywords, from Google Trends: data.items[0].interests[] with, for each keyword, values[] of geo_name (a US state, an Indian state and so on) and value, the relative interest from 0 to 100 (100 is the region that searches most), over the date range you give or the last year.

Use it to pick the states to target for ads, events or a sales push, or to compare two terms region by region; [`keyword_data`](https://parel.si/docs/tools/keyword_data.md) gives interest over time for the whole country, [`keyword_volume`](https://parel.si/docs/tools/keyword_volume.md) absolute monthly searches. Flat price per call for up to five keywords; a keyword nobody searches is free. Under three seconds.

India: location_name "India" gives the Indian states.

## Inputs

Generated from the contract captured from staging on 2026-11-20.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_to` | string | no | Last day, yyyy-mm-dd. Default today. |
| `keywords` | array of string | one of | One to five keywords, compared on one scale. |
| `date_from` | string | no | First day, yyyy-mm-dd. Default a year ago. |
| `time_range` | string | no | Instead of dates: past_30_days, past_90_days, past_12_months or past_5_years. |
| `location_name` | string | no | The country by name ("United States", "India"). |

One of these sets must be complete (anything else is `invalid_input`, ₹0): `keywords`.

## What drives the cost

Flat price per call. A keyword nobody searches for is free. A result that finds nothing is `class: "ok_free"`, ₹0. The timeout is 30 seconds.

## Price today

| | |
|---|---|
| Price today | **₹0.33** per call (`cost_paise: 33`) at ₹93.93 per US dollar on 17 November 2026 |
| Hold before the call | ₹0.50 (`hold_paise: 50`); when the call settles the real price is charged and the unused part is released |
| ₹0 when | it fails, or the provider answers but there is nothing in it (an empty list, no email, no page): `class: "ok_free"`, ₹0 |
| Timeout | 30 s, then `upstream_timeout` (₹0, retryable) |
| Over MCP | `run_tool` with `tool: "get_trends_by_region"` |
| Over REST | `POST https://api.parel.si/v1/run` with `"tool": "get_trends_by_region"` |
| Confirmation | not needed (the estimate is under the ₹200 threshold) |

## Request

```bash
curl https://api.parel.si/v1/run \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_trends_by_region","input":{"keywords":["predictive maintenance","machine monitoring"],"time_range":"past_12_months","location_name":"United States"}}'
```

## What comes back

`data`, as the live check of 2026-11-20 recorded it, trimmed:

```json
{
  "keywords": [
    "predictive maintenance",
    "machine monitoring"
  ],
  "type": "trends",
  "location_code": 2840,
  "items_count": 1,
  "items": [
    {
      "keywords": [
        "predictive maintenance",
        "machine monitoring"
      ],
      "interests": [
        {
          "keyword": "predictive maintenance",
          "values": [
            {
              "geo_name": "Alabama",
              "value": 25
            },
            {
              "geo_name": "Arizona",
              "value": 15
            },
            {
              "geo_name": "Arkansas",
              "value": 30
            }
          ]
        },
        {
          "keyword": "machine monitoring",
          "values": [
            {
              "geo_name": "Alabama",
              "value": 25
            },
            {
              "geo_name": "Arizona",
              "value": 21
            },
            {
              "geo_name": "Arkansas",
              "value": 0
            }
          ]
        }
      ],
      "interests_comparison": {
        "items": [
          {
            "geo_id": null,
            "geo_name": "Alabama",
            "values": [
              83,
              17
            ]
          },
          {
            "geo_id": null,
            "geo_name": "Arizona",
            "values": [
              78,
              22
            ]
          },
          {
            "geo_id": null,
            "geo_name": "Arkansas",
            "values": [
              100,
              0
            ]
          }
        ],
        "absolute_items": [
          {
            "geo_id": null,
            "geo_name": "Alabama",
            "values": [
              25,
              5
            ]
          },
          {
            "geo_id": null,
            "geo_name": "Arizona",
            "values": [
              15,
              4
            ]
          },
          {
            "geo_id": null,
            "geo_name": "Arkansas",
            "values": [
              30,
              0
            ]
          }
        ]
      }
    }
  ]
}
```

## Notes

- Relative interest, not search counts: 100 is the region that searches most, others are scaled to it.
- Up to five keywords on one scale. Rare keywords cover only some regions.
- Flat price per call. A keyword nobody searches for is free.

## Siblings

- [`keyword_data`](https://parel.si/docs/tools/keyword_data.md)
- [`keyword_volume`](https://parel.si/docs/tools/keyword_volume.md)
