Get Google Business search keywords
Get Google Business search keywords is the operation for retrieving Google Business Profile search keywords: the search terms people used to find a connected Google Business Profile location, together with impression counts for a requested number of completed months. The in-progress month is not yet reported, so the response window covers finished months only. Results are sorted by impressions, highest first, and the operation costs 1 credit as documented.
What this operation returns
Use this operation when you need to know which search terms surfaced a connected Google Business Profile location and how many impressions each term generated during a completed-months window. The endpoint returns the search terms people used to find the location, with impression counts, over the requested number of completed months. Because the in-progress month is not yet reported, do not request or expect partial-month data; instead, interpret startMonth and endMonth as the finished window that was actually returned. The keywords array is sorted by impressions, highest first, so the first entries are the highest-volume terms in that window. The documented cost for this operation is 1 credit.
Authorization and query parameters
Send a GET request to the search-keywords path with the access key in the x-access-key header. The header name is x-access-key and its value is the token supplied by the caller. The required query parameter accountId is a string containing the integration ID of the connected Google Business Profile location. The optional query parameter months is an integer specifying how many completed months to include; it defaults to 1 and must be within the range 1 <= value <= 18. Before calling, check that accountId is present and that months, when supplied, is an integer in range, because those are the only documented query parameters for this operation. See the request example titled Request Google Business Profile search keywords for the origin-modular HTTP form.
Interpreting the 200 response
A successful 200 response contains success, startMonth, endMonth and keywords. The startMonth and endMonth fields mark the start and end of the returned completed-months window, so use them to confirm which months the keyword and impressions values cover before comparing results across calls. Each entry in keywords contains keyword, impressions and isLowerBound. The keyword field is the search term, impressions is the integer impression count for that term in the window, and isLowerBound indicates whether the count should be treated as a lower bound. When isLowerBound is true, the term is a low-volume term and impressions is a lower bound rather than an exact count; do not present it as a precise total or rank it as if it were exact. When isLowerBound is false, treat impressions as the reported count for that term. Because the array is sorted by impressions highest first, preserve that order when displaying results, and note that lower-bound entries may appear among exact-count entries according to their reported impressions value. See the response example titled Successful 200 response and the response field map table.
Worked example and failure checks
For a worked call, supply a required accountId and an optional months value within 1 <= value <= 18, then inspect startMonth and endMonth to verify the completed window, review keywords in impressions order, and flag any entry where isLowerBound is true before using its impressions value in reporting. If months is omitted, expect the default of 1 completed month. If the call returns a non-200 status, inspect the documented success and message fields rather than assuming a keyword list is present. The status matrix table lists every documented status for this operation, and the error response example titled Error response shape for 400, 401, 402, 404 and 502 shows the shared shape without adding undocumented causes.
| Parameter | Location | Type | Required | Default / range | Description |
|---|---|---|---|---|---|
| accountId | Query | string | Yes | — | Integration ID of the connected Google Business Profile location. |
| months | Query | integer | No | Default 1; 1 <= value <= 18 | Number of completed months to include. |
Exact documented query contract.
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | Yes | Indicates the response result. |
| startMonth | string | Yes | Start of the returned completed-months window. |
| endMonth | string | Yes | End of the returned completed-months window. |
| keywords | array<object> | Yes | Search keywords sorted by impressions, highest first. |
| keywords[].keyword | string | Yes | Search term used to find the location. |
| keywords[].impressions | integer | Yes | Impression count for the keyword in the window. |
| keywords[].isLowerBound | boolean | Yes | True means impressions is a lower bound rather than an exact count for a low-volume term. |
Exact documented 200 response contract.
| Status | Content type | Response shape | Documented handling |
|---|---|---|---|
| 200 | application/json | success, startMonth, endMonth, keywords | Return keyword results sorted by impressions highest first. |
| 400 | application/json | success, message | Handle using the documented success/message shape. |
| 401 | application/json | success, message | Handle using the documented success/message shape. |
| 402 | application/json | success, message | Handle using the documented success/message shape. |
| 404 | application/json | success, message | Handle using the documented success/message shape. |
| 502 | application/json | success, message | Handle using the documented success/message shape. |
Statuses are documented; specific error causes are not documented in the source and are not stated here.
curl -X GET "{{API_BASE_URL}}/v1/googlebusiness/search-keywords?accountId=string&months=3" \
-H "x-access-key: <token>"{
"success": true,
"startMonth": "string",
"endMonth": "string",
"keywords": [
{
"keyword": "string",
"impressions": 0,
"isLowerBound": true
}
]
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | Integration ID of the connected Google Business Profile location. | |
| months#2 | months | integer | __0 | No | Number of completed months to include (default 1). | kind: schemaDefault; value: 1 | kind: schemaRange; value: 1 <= value <= 18 |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.startMonth | string | __2 | Yes | ||
| response#3 | response.endMonth | string | __3 | Yes | ||
| response#3 | response.keywords | array<object> | __4 | Yes | ||
| response#3 | response.keywords[] | object | __5 | |||
| response#3 | response.keywords[].keyword | string | __6 | Yes | ||
| response#3 | response.keywords[].impressions | integer | __7 | Yes | ||
| response#3 | response.keywords[].isLowerBound | boolean | __8 | Yes | ||
| response#4 | response | object | __0 | |||
| response#4 | response.success | boolean | __1 | Yes | ||
| response#4 | response.message | string | __2 | Yes |