Skip to content

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.

Query parameters
ParameterLocationTypeRequiredDefault / rangeDescription
accountIdQuerystringYes—Integration ID of the connected Google Business Profile location.
monthsQueryintegerNoDefault 1; 1 <= value <= 18Number of completed months to include.

Exact documented query contract.

200 response fields
FieldTypeRequiredDescription
successbooleanYesIndicates the response result.
startMonthstringYesStart of the returned completed-months window.
endMonthstringYesEnd of the returned completed-months window.
keywordsarray<object>YesSearch keywords sorted by impressions, highest first.
keywords[].keywordstringYesSearch term used to find the location.
keywords[].impressionsintegerYesImpression count for the keyword in the window.
keywords[].isLowerBoundbooleanYesTrue means impressions is a lower bound rather than an exact count for a low-volume term.

Exact documented 200 response contract.

Status codes
StatusContent typeResponse shapeDocumented handling
200application/jsonsuccess, startMonth, endMonth, keywordsReturn keyword results sorted by impressions highest first.
400application/jsonsuccess, messageHandle using the documented success/message shape.
401application/jsonsuccess, messageHandle using the documented success/message shape.
402application/jsonsuccess, messageHandle using the documented success/message shape.
404application/jsonsuccess, messageHandle using the documented success/message shape.
502application/jsonsuccess, messageHandle using the documented success/message shape.

Statuses are documented; specific error causes are not documented in the source and are not stated here.

Request Google Business Profile search keywords
curl -X GET "{{API_BASE_URL}}/v1/googlebusiness/search-keywords?accountId=string&months=3" \
  -H "x-access-key: <token>"
Successful 200 response
{
  "success": true,
  "startMonth": "string",
  "endMonth": "string",
  "keywords": [
    {
      "keyword": "string",
      "impressions": 0,
      "isLowerBound": true
    }
  ]
}
Error response shape for 400, 401, 402, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0YesIntegration ID of the connected Google Business Profile location.
months#2monthsinteger__0NoNumber of completed months to include (default 1).kind: schemaDefault; value: 1 | kind: schemaRange; value: 1 <= value <= 18
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.startMonthstring__2Yes
response#3response.endMonthstring__3Yes
response#3response.keywordsarray<object>__4Yes
response#3response.keywords[]object__5
response#3response.keywords[].keywordstring__6Yes
response#3response.keywords[].impressionsinteger__7Yes
response#3response.keywords[].isLowerBoundboolean__8Yes
response#4responseobject__0
response#4response.successboolean__1Yes
response#4response.messagestring__2Yes