Home | About Chris Hope | Contact Chris Hope | Search:

Google Analytics API PHP Class data method parameters

Posted June 12th, 2009 in PHP

This post documents the parameters that can be passed to the data() method of my PHP class for interfacing with the Google Analytics API. You can read more about my class here as well as download it along with an example script.

Summary

First of all a brief bullet point summary of the parameters:

• $id - the profile id to query data for
• $dimension - the dimension(s) to retrieve data for
• $metric - the metric(s) to retrive data for
• $sort - the sort order for data
• $start - the start date in YYYY-MM-DD format
• $end - the end date in YYYY-MM-DD format
• $max_results - the maximum number of results to return
• $start_index - the index to start from, if $max_results is 1000 then the second "page" of data would have a start index of 1001
• $filters - information to filter the data
• $debug - if true will echo out the URL that is called when asking Google for data

And now more detailed information for each of the above parameters.

$id

This is the profile id that you want to query data for. It should be in the format ga:12345 where the 12345 part if the actual profile id. You can get this id from either the GA Web Interface (I've posted about this here) or using the load_accounts() method and associated accounts() array in my class (details about that here). Ideally you don't want to do the latter on every request because it is a little slow so it's a good idea to cache it in some way (e.g. in a database or config file) or hard code it etc.

$dimension

This specifies the dimensions to fetch data for, as a comma delimited string. For example to get data for the browser and browser version it would be 'ga:browser,ga:browserVersion'. You can read more about the various dimensions available in the Google Analytics documentation about dimensions and metrics. The GA API allows you to pass in a maximum of 7 dimensions. My class currently only allows for 3 but I will address this is a later release.

$metric

This specifies the metrics to fetch data for, as a comma delimited string. For example to get data the number of visits and pageviews it would be 'ga:visits,ga:pageviews'. Again refer to the Google Analytics documentation about dimensions and metrics for information about the various metrics available. You can specify a maximum of 10 metrics. Some dimensions and metrics cannot be combined and will result in an error.

$sort

This is the sort order to get data and will affect what is returned if there are more records than $max_results in the resultset. The code in my class defaults this to -$metric. In the above example of 'ga:visits,ga:pageviews' $sort would default to '-ga:visits,ga:pageviews' if you do not specify a value yourself.

$start

The start date to get data for. If not specified it defaults to one month ago, calculated like this:

date('Y-m-d', strtotime('1 month ago'));

If it's a date it needs to be in YYYY-MM-DD format. Other valid values are "today", "yesterday" and "week". "today" gets data for today, although there is some delay between data being recorded and being displayed in GA data. "yesterday" gets it for yesterday. And "week" gets it for the week ending yesterday.

$end

The end date to get data for. If it's an empty string/false then it defaults to yesterday's date, or today's date if "today" was specified as the $start parameter.

$max_results

The maximum number of rows of data to return from the GA API. The maximum Google allows is 1000. The default if not specified in the data() method is 10. See my "looping through the data" post for more details if you need to get more than 1000 records.

$start_index

This is the row offset to start returning data from. If you had already retrieved 1000 records then this should be set to 1001. Again, refer to my "looping through the data" post for more details if you need to get more than 1000 records.

$filters

The GA API allows the data to be filtered, such as filtering by page path, country, browser and so on. The value passed can either be an object of my analytics_filters class or a string. For more details about how to work with this refer to my "using filters" post and also the GA API documentation about filters.

$debug

The debug parameter defaults to false. If true it will echo the URL called when making a request to the Google Analytics API out to standard output. This can be useful if you need to see what the actual URL being called is.