Google Trends API endpoint
Returns only the interest-by-region widget from the Google Trends Explore widget flow. Supports multiple comparison terms and returns an empty interest_by_region array when Google returns no rows.
/google/trends/explore/interest-by-regionReturns only the interest-by-region widget from the Google Trends Explore flow. It supports up to 5 comparison terms.
If Google returns no region rows for the requested term/filter combination, the response is still 200 with interest_by_region: [].
Request body:
keywords: required array of 1 to 5 keywords.geo: optional country/territory location code. Defaults to worldwide when omitted. Allowed values: WORLDWIDE, AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, VG, BN, BG, BF, BI, KH, CM, CA, CV, BQ, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, KP, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, BL, SH, KN, LC, MF, PM, VC, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UM, VI, UG, UA, AE, GB, US, UY, UZ, VU, VA, VE, VN, WF, EH, YE, ZM, ZW.time_range: optional Trends time range. Allowed values: now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all. Defaults to today 12-m.hl: optional locale. Defaults to en-US.tz: optional timezone offset in minutes. Defaults to 0.category: optional Trends category id. Defaults to 0.type: optional search type. Allowed values: web, image, news, youtube, shopping. Defaults to web.property: optional legacy Trends property filter. Prefer type; if both are supplied they must describe the same search type.Notes:
503 with a Retry-After header and an error message naming the failing widget endpoint and upstream status, for example google trends widgetdata/comparedgeo rate limited by upstream (status 429).| Field | Filled in, of 51 checked | Values in the sample |
|---|---|---|
| geo_code | 51 | |
| geo_name | 51 | “California” and 50 other values |
| values | 51 | median 1 entry |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| request (body) | object | Yes | Explore request | ||
| x-api-key (header) | string | Yes | API key required |
curl -X POST "https://api.crawlora.net/api/v1/google/trends/explore/interest-by-region" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category":0,"geo":"US","hl":"en-US","keywords":["chatgpt","openai"],"property":"","time_range":"today 12-m","type":"web","tz":0}'{
"category": 0,
"geo": "US",
"hl": "en-US",
"keywords": [
"chatgpt",
"openai"
],
"property": "",
"time_range": "today 12-m",
"type": "web",
"tz": 0
}{
"code": 200,
"msg": "OK",
"data": {
"keywords": [
"google"
],
"geo": "HK",
"time_range": "today 12-m",
"interest_by_region": [
{
"geo_code": "HK",
"geo_name": "Hong Kong",
"values": [
{
"keyword": "google",
"value": 100,
"formatted_value": "100",
"has_data": true
}
]
}
]
}
}Request schema
#/definitions/trends.ExploreRequest
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| category | integer | No | 0 | |||
| geo | string | No | WORLDWIDE, AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, VG, BN, BG, BF, BI, KH, CM, CA, CV, BQ, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, KP, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, BL, SH, KN, LC, MF, PM, VC, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UM, VI, UG, UA, AE, GB, US, UY, UZ, VU, VA, VE, VN, WF, EH, YE, ZM, ZW | US | ||
| hl | string | No | en-US | |||
| keywords | array | No | chatgpt,openai | |||
| property | string | No | ||||
| time_range | string | No | now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all | today 12-m | ||
| type | string | No | web, image, news, youtube, shopping | web | ||
| tz | integer | No | 0 |
Response schema
#/definitions/trends.interestByRegionResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | trends.InterestByRegionResponse | No | ||||
| data.category | integer | No | 0 | Trends category ID that was applied. `0` means all categories. | ||
| data.geo | string | No | US | Location code the data covers, such as `US`. | ||
| data.hl | string | No | en-US | Locale that was applied, such as `en-US`. | ||
| data.interest_by_region | array | No | Interest in each keyword by region. | |||
| data.interest_by_region[].geo_code | string | No | US-CA | Code of the region, such as `US-CA`. | ||
| data.interest_by_region[].geo_name | string | No | California | Name of the region, such as `California`. | ||
| data.interest_by_region[].values | array | No | Interest value for each keyword in this region. | |||
| data.interest_by_region[].values[].formatted_value | string | No | 87 | Interest score as Google Trends displays it. | ||
| data.interest_by_region[].values[].has_data | boolean | No | true | Whether Google Trends has data for this keyword at this point. | ||
| data.interest_by_region[].values[].keyword | string | No | chatgpt | Keyword the value belongs to. | ||
| data.interest_by_region[].values[].value | integer | No | 87 | Relative interest score for the keyword, as Google Trends reports it. | ||
| data.keywords | array | No | Keywords that were compared. | |||
| data.property | string | No | Google property filter that was applied, matching `type`. | |||
| data.time_range | string | No | today 12-m | Time range that was applied, such as `today 12-m`. | ||
| data.type | string | No | web | Search type that was applied: `web`, `image`, `news`, `youtube` or `shopping`. | ||
| data.tz | integer | No | 0 | Timezone offset in minutes that was applied. | ||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid input | #/definitions/app.Response |
| 429 | Rate limit exceeded | #/definitions/app.Response |
| 500 | Internal server error | #/definitions/app.Response |
| 503 | Google Trends upstream request failed | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X POST "https://api.crawlora.net/api/v1/google/trends/explore/interest-by-region" \
-H "x-api-key: $CRAWLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category":0,"geo":"US","hl":"en-US","keywords":["chatgpt","openai"],"property":"","time_range":"today 12-m","type":"web","tz":0}'