How to create custom report in Piwik (Matomo) to display geo location information

In this tutorial, we are going to share with you on how to create a custom report in Piwik. In this custom report, we will display the country code, region name, city name, latitude and longitude information of the visitors’ IP address. Before we could generate the custom report, we need a plugin to host the report. For this, we will use the IP2Location plugin. We also need an IP database to obtain the relevant geo location information for display. For this, we will use IP2Location DB5 BIN database.

Please take note that knowledge of PHP programming languages is required for this tutorial.

Below are the steps to create the custom report:

  1. Install the IP2Location Piwik plugin. You may find the installation steps at
  2. Download IP2Location DB5 BIN database. You can download either the commercial or LITE version.
  3. Unzip the downloaded data file.
  4. Copy the BIN file (ended with .BIN extension) into plugins/IP2Location/data inside Piwik folder where you installed the platform.
  5. Before you can create the custom report, you need to turn on the developer mode. Go to the installed Piwik folder, and enter the below command.
    ./console development:enable
  6. Create a custom report by entering the below command.
    ./console generate:report
  7. This command will prompt you through several questions for the custom report creation. Please enter the value as below:
    • Enter IP2Location for plugin name.
    • Enter IP2Location Report for report name.
    • Enter Visitors for the report category.
    • Leave empty for the rest of the questions.
  8. The console will then create a file called GetIP2LocationReport.php inside plugins/IP2Location/Reports folder. In addition, the console will also add the getIP2LocationReport function into the plugins/IP2Location/API.php file. Below please find the screenshot after the custom report has been successfully created.
    Generate custom report
  9. Open the API.php file and look for the getIP2LocationReport function. You shall see the below default function added.
    Modify Piwik API file
  10. This function will be invoked whenever user view the IP2Location Report custom report. Therefore, this shall be the place to put in the code to display the geo location information that we want.
  11. Replace the function with the below codes. Basically, this code will get the visitor details from Live.getLastVisitsDetailsAPI based on the filters parameter supplied. After that, the code will recursively fetch the record of each visit, get the IP address, and then call the IP2Location lookup function for country, region, city, latitude and longitude information.
    $data = \Piwik\API\Request::processRequest('Live.getLastVisitsDetails', array(
    		'idSite' => $idSite,
    		'period' => $period,
    		'date' => $date,
    		'segment' => $segment,
    		'numLastVisitorsToFetch' => 100,
    		'minTimestamp' => false,
    		'flat' => false,
    		'doNotFetchActions' => true
    	// Create a new database
    	$result = $data->getEmptyClone($keepFilters = false);
    	foreach ($data->getRows() as $visitRow) {
    		// Get the visitor IP
    		$visitor_ip = $visitRow->getColumn('visitIp');
    		// Look up for geo location information using IP2Location plugin
    		$geodata = $this->lookup($visitor_ip, realpath(dirname(__FILE__)) . '/data/IP2LOCATION-LITE-DB5.BIN');
    			'label'     => $visitor_ip,
    			'ip_country' => $geodata['countryCode'],
    			'ip_region' => $geodata['regionName'],
    			'ip_city' => $geodata['cityName'],
    			'ip_latitude' => $geodata['latitude'],
    			'ip_longitude' => $geodata['longitude'],
    return $result;
  12. Save the API.php file.
  13. Open GetIP2LocationReport.php for editing.
  14. Inside the Init() function, enter the menu title for this report so that IP2Location Report will be shown under Visitors report section.
    $this->menuTitle = 'IP2Location Report';

    Piwik custom report menu

  15. Inside the Init() function, define the array of the table data. This data array will be used to keep the geo location information for display that we added in the getIP2LocationReport function.
    $this->metrics = array('ip_country', 'ip_region', 'ip_city', 'ip_latitude', 'ip_longitude');
  16. Inside the configureView function, configure the column headers for display.
    $view->config->addTranslation('label', 'IP Address');
    $view->config->addTranslation('ip_country', 'Country');
    $view->config->addTranslation('ip_region', 'Region Name');
    $view->config->addTranslation('ip_city', 'City Name');
    $view->config->addTranslation('ip_latitude', 'Latitude');
    $view->config->addTranslation('ip_longitude', 'Longitude');
  17. You can now go to the admin area and view the report that you have just created. Below is the example of the report.
    example of IP2Location geo location report

Was this article helpful?

Related Articles