Running the Google Analytics import (GA3 / GA4)

Note: This guide assumes you have already authorized Matomo to access your Google Analytics data. Please ensure that you have followed those steps first.

Once you’ve authorized Matomo, you can begin importing data. You can initiate this through the admin page, or on the command line. Running your import on the command line allows you to see more detailed information about it’s progress as it’s going. Depending on how much data you are importing it can take a long time to finish an import.

Google imposes a daily limit on the number of API requests you can make each day (at most 50,000) and each site (at most 10,000). The import will hit this limit after importing about 4 months of data where every day has data. This takes just a couple of hours. This means the import has to run over several days until the entire data set is imported.

Setup an import using the admin page

  1. Go to the Google Analytics Import admin page.

  2. Select the Import type.

    Schedule An Import Form

  3. Fill out the Schedule an Import form and click Start:

    Schedule An Import Form for Universal Analytics (GA3)

    Schedule An Import Form for GA4

  4. As the import continues, you will be able to monitor progress through the Import Jobs table below:

    Import Jobs List

    Import Jobs List

    Refresh the page to get an updated status at any time.

  5. Once the import is marked as finished, feel free to delete the status. If an import fails, you can view the logs located in /path/to/your/matomo/tmp/logs/. There should be one for each job.

Setup an import using the Command Line for Universal Analytics (GA3)

  1. First you’ll need some information. In your Google Analytics dashboard, open the property selector.
  2. Take note of the Property ID and the View ID for the property/view you want to import.
  3. ssh into your Matomo instance
  4. Run the following commands to import your site:
    $ cd /path/to/my/matomo
    $ php ./console googleanalyticsimporter:import-reports --property=<property-id> --view=<view-id> --dates=<dates>
    For property-id and view-id substitute the GA property ID and view ID you noted above. For dates specify the date range of date you’d like to import, for example, 2017-01-01,2022-04-31.

Then just wait until the import finishes, which could take some time.

If you would like to resume an existing import, supply the --idsite=<idSite> parameter with the site that was created for this import (this will be in the import status table in the admin page).

Once the import finishes, you can remove the authorization you granted earlier. Matomo only needs access to Google Analytics while importing data, afterwards there’s no need to keep it.

Setup an import using the Command Line for GA4

  1. First you’ll need some information. In your Google Analytics dashboard, open the property selector.
  2. Take note of the Property ID for the property you want to import.
  3. ssh into your Matomo instance
  4. Run the following commands to import your site:
    $ cd /path/to/my/matomo
    $ php ./console googleanalyticsimporter:import-ga4-reports --property="properties/<property-id>" --dates=<dates>
    For property-id substitute the GA4 property ID noted above. For dates specify the date range of date you’d like to import, for example, 2017-01-01,2022-04-31.

Then just wait until the import finishes, which could take some time.

If you would like to resume an existing import, supply the --idsite=<idSite> parameter with the site that was created for this import (this will be in the import status table in the admin page).

Once the import finishes, you can remove the authorization you granted earlier. Matomo only needs access to Google Analytics while importing data, afterwards there’s no need to keep it.

Importer Options

Importing a Mobile App Property

If your GA property is for a mobile app, then you will need to check the Mobile App checkbox before starting your import:

Import Mobile App

This will ensure that Matomo imports the correct data. The Screen Views metric in Google Analytics will be imported and used as the Pageviews metric in matomo. The Screens reports will be imported into the Page Titles reports in Matomo.

If you don’t check this box and your property is for a mobile app, the importer will ignore this data.

Importing Unsupported GA Dimensions

Some GA dimensions do not exist in Matomo, such as the demographics dimensions. You may want to hold onto this information when importing, and it is possible to do so by importing the data into a custom dimension.

In the import form, fill out the “Extra Custom Dimension Mappings” field with the GA dimensions you’d like to import:

Extra Custom Dimension Mappings

Use this list to find the proper IDs for Universal Analytics (GA3) dimensions.
Use this list to find the proper IDs for GA4 dimensions.

When importing, one custom dimension slot will be used up in the imported site for each extra mapping. (Note: there will be an error if there are not enough custom dimension slots in your Matomo.)

After your import

After you finish importing data into Matomo it is a good idea to back up your Matomo’s database. If the imported report data were to be purged or somehow deleted, you would have to re-import the data from GA. And if your GA property has been deleted, the data will be gone forever.

If you regularly backup your database (or your host does it for you), then you don’t really need to worry about this.

Previous FAQ: Setting up a Google Analytics Import (GA3 / GA4)