> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google My Business as a data source

> Bring data from Google Business Profile to Nekt.

Google Business Profile (formerly Google My Business) is Google's platform for managing how businesses appear on Google Search and Maps. It allows business owners to manage their listings, respond to reviews, publish posts, and track performance metrics like search impressions, direction requests, and website clicks.

<img width="200" src="https://mintlify.s3.us-west-1.amazonaws.com/nekt/assets/logo/logo-google-my-business.png" />

## Configuring Google My Business as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Google My Business option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

You'll need to authorize Nekt to access your Google Business Profile data. Using the UI, you can click on the `Google Authorization` button and log in with the Google account associated with your business locations. Alternatively, you can configure your own OAuth app credentials.

The following configurations are available:

* **Start date**: (Optional) Records created or updated after the start date will be extracted from the source. Used for incremental streams like reviews and performance metrics.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. The following streams are available:

* **accounts**: Business Profile accounts accessible to the authenticated user.
* **locations**: Business locations under each account, including address, hours, categories, and metadata.
* **reviews**: Customer reviews for each location, including star rating, comment, and owner replies.
* **posts**: Local posts published on each location (standard, event, offer, and alert types).
* **daily\_performance\_metrics**: Daily performance data per location, including search impressions, direction requests, call clicks, and website clicks.
* **search\_keywords**: Monthly search keyword impressions showing which terms led users to find each location.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data), and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster.
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: every time the extraction happens, we'll get only the new data, which is useful when you want to keep historical records.
  * Full table: every time the extraction happens, we'll get the current state of the data, which is useful when you do not want deleted records in your catalog.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how frequently you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

Below you'll find the available data streams from Google My Business and their corresponding fields:

<AccordionGroup>
  <Accordion title="Accounts">
    Stream for retrieving Google Business Profile accounts accessible to the authenticated user.

    **Sync behavior:**

    * Primary key: `name`
    * Replication: Full table

    | Field                | Type   | Description                                                               |
    | :------------------- | :----- | :------------------------------------------------------------------------ |
    | `name`               | String | Resource name of the account.                                             |
    | `account_name`       | String | Display name of the account.                                              |
    | `type`               | String | Type of account (PERSONAL, LOCATION\_GROUP, etc).                         |
    | `role`               | String | Role of the authenticated user for this account.                          |
    | `verification_state` | String | Verification state of the account.                                        |
    | `vetted_state`       | String | Vetted state of the account.                                              |
    | `account_number`     | String | Account reference number.                                                 |
    | `permission_level`   | String | Permission level of the caller.                                           |
    | `primary_owner`      | String | Resource name of the primary owner.                                       |
    | `organization_info`  | Object | Organization info including registered domain, address, and phone number. |
  </Accordion>

  <Accordion title="Locations">
    Stream for retrieving business locations under each account, including address, operating hours, categories, and metadata.

    **Sync behavior:**

    * Primary key: `name`
    * Replication: Full table
    * Parent stream: `accounts`

    | Field                | Type   | Description                                                         |
    | :------------------- | :----- | :------------------------------------------------------------------ |
    | `name`               | String | Resource name of the location.                                      |
    | `language_code`      | String | Language of the location.                                           |
    | `store_code`         | String | External identifier for the location.                               |
    | `title`              | String | Location name (business name).                                      |
    | `phone_numbers`      | Object | Primary and additional phone numbers.                               |
    | `categories`         | Object | Primary and additional business categories.                         |
    | `storefront_address` | Object | Physical address of the location.                                   |
    | `website_uri`        | String | Website URL.                                                        |
    | `regular_hours`      | Object | Standard operating hours.                                           |
    | `special_hours`      | Object | Special hours for holidays and other exceptions.                    |
    | `labels`             | Array  | User-provided labels for the location.                              |
    | `latlng`             | Object | Latitude and longitude coordinates.                                 |
    | `open_info`          | Object | Open/closed status and opening date.                                |
    | `metadata`           | Object | Additional metadata including Maps URI, place ID, and capabilities. |
    | `profile`            | Object | Profile description of the location.                                |
    | `relationship_data`  | Object | Parent/children location relationships and chain info.              |
  </Accordion>

  <Accordion title="Reviews">
    Stream for retrieving customer reviews for each location, including star rating, comment, and owner reply.

    **Sync behavior:**

    * Primary key: `review_id`
    * Replication key: `update_time` (incremental sync supported)
    * Parent stream: `locations`

    | Field          | Type     | Description                                               |
    | :------------- | :------- | :-------------------------------------------------------- |
    | `name`         | String   | Resource name of the review.                              |
    | `review_id`    | String   | Encrypted unique identifier.                              |
    | `reviewer`     | Object   | Author info including display name and profile photo URL. |
    | `star_rating`  | String   | Star rating (ONE through FIVE).                           |
    | `comment`      | String   | Body of the review.                                       |
    | `create_time`  | Datetime | When the review was written.                              |
    | `update_time`  | Datetime | When the review was last modified.                        |
    | `review_reply` | Object   | Owner reply including comment and update time.            |
    | `account_id`   | String   | ID of the account.                                        |
    | `location_id`  | String   | ID of the location.                                       |
  </Accordion>

  <Accordion title="Posts">
    Stream for retrieving local posts published on each location, including standard posts, events, offers, and alerts.

    **Sync behavior:**

    * Primary key: `name`
    * Replication key: `update_time` (incremental sync supported)
    * Parent stream: `locations`

    | Field            | Type     | Description                                                      |
    | :--------------- | :------- | :--------------------------------------------------------------- |
    | `name`           | String   | Resource name of the post.                                       |
    | `language_code`  | String   | Language of the post.                                            |
    | `summary`        | String   | Body of the post.                                                |
    | `call_to_action` | Object   | Call-to-action including action type and URL.                    |
    | `create_time`    | Datetime | When the post was created.                                       |
    | `update_time`    | Datetime | When the post was last modified.                                 |
    | `state`          | String   | Lifecycle state of the post.                                     |
    | `search_url`     | String   | Link to the post in Google Search.                               |
    | `topic_type`     | String   | Type of post (STANDARD, EVENT, OFFER, ALERT).                    |
    | `alert_type`     | String   | Alert type (for ALERT posts only).                               |
    | `event`          | Object   | Event info including title and schedule (for EVENT/OFFER posts). |
    | `offer`          | Object   | Offer details including coupon code and terms (for OFFER posts). |
    | `media`          | Array    | Media items attached to the post.                                |
    | `account_id`     | String   | ID of the account.                                               |
    | `location_id`    | String   | ID of the location.                                              |
  </Accordion>

  <Accordion title="Daily Performance Metrics">
    Stream for retrieving daily performance data per location, including impressions, direction requests, call clicks, and website clicks.

    **Sync behavior:**

    * Primary keys: `location_id`, `date`, `metric`
    * Replication key: `date` (incremental sync supported)
    * Parent stream: `locations`

    **Available metrics:**

    * `BUSINESS_IMPRESSIONS_DESKTOP_MAPS` / `BUSINESS_IMPRESSIONS_DESKTOP_SEARCH`
    * `BUSINESS_IMPRESSIONS_MOBILE_MAPS` / `BUSINESS_IMPRESSIONS_MOBILE_SEARCH`
    * `BUSINESS_CONVERSATIONS`, `BUSINESS_DIRECTION_REQUESTS`
    * `CALL_CLICKS`, `WEBSITE_CLICKS`
    * `BUSINESS_BOOKINGS`, `BUSINESS_FOOD_ORDERS`, `BUSINESS_FOOD_MENU_CLICKS`

    | Field         | Type    | Description                                |
    | :------------ | :------ | :----------------------------------------- |
    | `location_id` | String  | ID of the location.                        |
    | `date`        | Date    | Date of the metric.                        |
    | `metric`      | String  | Name of the metric (e.g. WEBSITE\_CLICKS). |
    | `value`       | Integer | Metric value for the date.                 |
  </Accordion>

  <Accordion title="Search Keywords">
    Stream for retrieving monthly search keyword impressions, showing which search terms led users to find each location on Google.

    **Sync behavior:**

    * Primary keys: `location_id`, `month`, `search_keyword`
    * Replication key: `month` (incremental sync supported)
    * Parent stream: `locations`

    | Field            | Type    | Description                            |
    | :--------------- | :------ | :------------------------------------- |
    | `location_id`    | String  | ID of the location.                    |
    | `month`          | String  | Month in YYYY-MM format.               |
    | `search_keyword` | String  | The search keyword.                    |
    | `value`          | Integer | Number of impressions for the keyword. |
  </Accordion>
</AccordionGroup>

# Data Model

The following diagram illustrates the parent-child relationships between the core data streams in the Google My Business API. Extractions happen hierarchically by first pulling accounts, then discovering locations within those accounts, and finally retrieving all related data for each location.

```mermaid theme={null}
graph TD;
    subgraph "Core Entities"
        Accounts("Accounts");
        Locations("Locations");
    end

    subgraph "Location Data"
        Reviews("Reviews");
        Posts("Posts");
        DailyPerformanceMetrics("Daily Performance Metrics");
        SearchKeywords("Search Keywords");
    end

    Locations -- "belongs to" --> Accounts;
    Reviews -- "location_id" --> Locations;
    Posts -- "location_id" --> Locations;
    DailyPerformanceMetrics -- "location_id" --> Locations;
    SearchKeywords -- "location_id" --> Locations;
```

## Implementation Notes

### Data behavior considerations

* The connector uses a parent-child stream hierarchy: accounts are fetched first, then locations under each account, and finally reviews, posts, and metrics for each location.
* Reviews are sorted by `updateTime desc` from the API but there is no server-side date filter. The connector paginates through all reviews and uses client-side filtering for incremental sync.
* Posts similarly lack a server-side date filter. All posts are fetched and filtered client-side based on `update_time`.
* Performance metrics support true date-range filtering. The API allows a maximum of 18 months of historical data.
* Search keywords are reported on a monthly basis. The current (incomplete) month is excluded.

### API limits & performance

* The connector accesses multiple Google sub-APIs (Account Management, Business Information, Performance). Ensure all necessary APIs are enabled in your Google Cloud project if providing custom credentials.
* If your account has many locations, extraction times will increase proportionally since child streams (reviews, posts, metrics, keywords) run per location.

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Google My Business skills file" icon="wand-magic-sparkles" href="/sources/google-my-business.md">
  Google My Business connector documentation as plain markdown, for use in AI agent contexts.
</Card>