This document describes how to send data to Google Analytics using the Measurement Protocol.
There are 2 parts to send data to Google Analytics using the Measurement Protocol:
- The transport – to where and how you send data
- The payload – the data you send
This document describes how to format both.
You send data using the Measurement Protocol by making HTTP requests to the following end point:
All data should be sent securely with the HTTPS protocol.
You can send data using either POST or GET requests.
We recommend sending data via POST because it allows for a larger payload. When using POST, issue the following HTTP request:
User-Agent: user_agent_string POST https://www.google-analytics.com/collect payload_data
- user_agent_string – Is a
formatted user agent string that is used to compute the
following dimensions: browser, platform, and mobile capabilities.
If this value is not set, the data above will not be computed.
- payload_data – The
BODYof the post request. The body must include exactly 1 URI encoded payload and must be no longer than 8192 bytes.
- IP Address – Is implicitly sent in the HTTP request and is used to compute all the geo / network dimensions in Google Analytics.
For environments where you can not send POST data, you can also send HTTP GET requests to the same end point:
GET /collect?payload_data HTTP/1.1 Host: https://www.google-analytics.com User-Agent: user_agent_string
Where the payload data is sent as URI escaped query parameters. The length of the entire encoded URL must be no longer than 8000 Bytes.
In some environments, like browsers, HTTP GET requests might get cached.
When a request gets cached, subsequent requests might be retrieved from the
cache, and not sent to Google Analytics. To bust through the cache,
the Measurement Protocol provides a special parameter
z) that can be set with a random number. This ensures all
Measurement Protocol requests are unique, and that subsequent requests are not
retrieved from the cache.
When you use the cache buster, we highly recommend adding this parameter as the last parameter in the payload.
The Measurement Protocol will return a
2xx status code if the HTTP
request was received. The Measurement Protocol does not return an error code if
the payload data was malformed, or if the data in the payload was incorrect
or was not processed by Google Analytics.
If you do not get a
2xx status code, you should
NOT retry the request. Instead, you should stop and correct
any errors in your HTTP request.
All data collected by Google Analytics using the Measurement Protocol is sent as
a payload. The payload resembles a URL query string where each
parameter has a key and value, is separated by an
and each pair is delimited by an
Each payload has rules governing: required values, URI encoding, parameters that can be sent together, and parameter length. Also each parameter has a specific type that requires a particular format. The following sections goes through these rules.
Read the Parameter Reference for a complete listing of all the parameters you can send using the Measurement Protocol.
Required Values For All Hits
The following parameters must be in each payload:
||The protocol version. The value should be
||The ID that distinguishes to which Google Analytics property to send data.|
||An ID unique to a particular user.|
||The type of interaction collected for a particular user.|
Client ID and
data are values that map directly to the Google Analytics data model.
If you wanted to track user
5555 who went to
you would send the following 3 payloads:
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC
Notice that the
/ was encoded to
URL Encoding Values
All values sent to Google Analytics must be both UTF-8 and
To send the key
dp with the value
/my page €, you will first need to make sure this is
UTF-8 encoded, then url encoded, resulting in the final string:
If any of the characters are encoded incorrectly, they will be replaced
with the unicode replacement character
Required Values For Certain Hit Types
Some parameters may only be sent with specific hit types.
For example, the
pageview hit type requires that the
Page Path parameter (
dp) also be set. The
Parameter Reference describes
which parameters are required for which hit types.
All text values in the Measurement Protocol have specific maximum lengths
in bytes. for example the document referrer field,
dr has a maximum
length of 2048 Bytes. If any of the values are greater than the
maximum lengths, they will automatically be truncated. If a multi-byte
character exceeds the maximum length, the entire character will
Supported Data Types
Each data field in the Measurement Protocol belongs to a specific type, each with it's own validation rules. If any of the parameter values do not conform to the validation rules, that specific parameter will be ignored and not processed by Google Analytics. All other parameters will be processed as normal.
The Measurement Protocol supports the following data types:
Note that individual data fields might have their own restrictions. See the Field Reference for a complete list of all the data fields and accepted types.
Used to represent strings. Additional processing is done on text fields. All leading and trailing whitespace characters are removed. Internal runs of two or more whitespace chars (including space, tab, newlines, etc) are reduced to a single space character. This transformation is applied to the raw text before any truncation happens. For example:
Used to represent the total value of a currency. A decimal point is used as a delimiter between the whole and fractional portion of the currency. The precision is up to 6 decimal places. The following is valid for a currency field:
Once the value is sent to Google Analytics, all text is removed up until
the first digit, the
- character or the
(decimal) character. So:
Used to determine if a value is true or false. Valid values are:
Used to represent a number. The value is stored as a signed int64