GA4 Data Import

0.1.66 verified Sat May 09 auth: no python

A Python library for importing data into Google Analytics 4 (GA4) via the Data API. Version 0.1.66 supports batch data uploads for user, item, and event-scoped dimensions and metrics. It uses the google-analytics-data library under the hood. Active development with frequent releases.

pip install ga4-data-import

Common errors

error TypeError: __init__() got an unexpected keyword argument 'property_id' ↓

cause Using an older version of the library where the constructor argument was named 'property_id' differently (e.g., 'view_id' for universal analytics).

fix

Upgrade to latest version: pip install --upgrade ga4-data-import and use 'property_id' as documented.

error google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission ↓

cause Service account lacks the 'GA4 Data Import' role or the data source ID does not exist.

fix

Ensure service account has the 'roles/analytics.edit' role and that the data source ID is correct (found in GA4 Admin > Data Imports).

error ValueError: Dimension 'customItem:myParam' is not valid. ↓

cause Using custom dimension/metric names incorrectly. GA4 expects camelCase or snake_case depending on the scope.

fix

Refer to GA4 documentation for correct naming: e.g., 'customItem:my_param' (snake_case) for item-scoped dimensions.

Warnings

breaking Property ID must be a numeric string without 'properties/' prefix. Using 'properties/123456789' will fail. ↓

fix Pass a plain numeric string, e.g., '123456789'.

gotcha The library does not support deletion or overwrite of existing data rows. Uploads are additive only. ↓

fix You must delete data via the GA4 UI or the Admin API before re-uploading if needed.

deprecated The 'ga4_data_import.ga4' module is deprecated and will be removed. Use 'ga4_data_import.GA4DataImport' directly. ↓

fix Change import to: from ga4_data_import import GA4DataImport

Imports

GA4DataImport

wrong

from ga4_data_import.ga4 import GA4DataImport

correct

from ga4_data_import import GA4DataImport

Incorrect submodule path, might have been guessed from older docs.

Quickstart

Initializes the GA4DataImport client and uploads a small dataset.

import os
from ga4_data_import import GA4DataImport

credentials_path = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '/path/to/service-account.json')
client = GA4DataImport(
    property_id='123456789',
    credentials_path=credentials_path
)
response = client.upload_data(
    data_source_id='your-datasource-id',
    dataset=[
        {'item_id': 'SKU123', 'item_name': 'Example', 'quantity': 2}
    ]
)
print(response)