Measurement Protocol Reference

This document describes how to send data to Google Analytics using the Measurement Protocol.

Overview

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.

Transport

URL Endpoint

You send data using the Measurement Protocol by making HTTP requests to the following end point:

https://www.google-analytics.com/collect

All data should be sent securely with the HTTPS protocol.

You can send data using either POST or GET requests.

Using POST

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

Where:

  • 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 BODY of 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.

GET

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.

Cache Busting

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.

https://www.google-analytics.com/collect?payload_data&z=123456

Response Codes

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.

Payload Data

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 = character, and each pair is delimited by an & character. For example:

key1=val1&key2=val2

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:

Name Parameter Example Description
Protocol Version v v=1 The protocol version. The value should be 1.
Tracking ID tid tid=UA-123456-1 The ID that distinguishes to which Google Analytics property to send data.
Client ID cid cid=xxxxx An ID unique to a particular user.
Hit Type t t=pageview The type of interaction collected for a particular user.

The Client ID and Hit Type data are values that map directly to the Google Analytics data model. If you wanted to track user 5555 who went to /pageA, /pageB, and /pageC, 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 %2F.

URL Encoding Values

All values sent to Google Analytics must be both UTF-8 and URL Encoded. 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:

dp=%2Fmy%20page%20%E2%82%AC

If any of the characters are encoded incorrectly, they will be replaced with the unicode replacement character xFFFD.

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.

Maximum Length

Some text values in the Measurement Protocol have specific maximum lengths in bytes. For example, the document referrer field dr has a maximum length of 2,048 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 be truncated.

Supported Data Types

Each data field in the Measurement Protocol belongs to a specific type, each with its 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.

Text

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:

   Hello      World

will become:

Hello World

Currency

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:

1000.000001

Once the value is sent to Google Analytics, all text is removed up until the first digit, the - character or the . (decimal) character. So:

$-55.00

will become:

-55.00

Boolean

Used to determine if a value is true or false. Valid values are:

  • 1 – True
  • 0 – False

Integer

Used to represent an integer. The value is stored as a signed int64

Number

Used to represent an integer or a floating point number.