This page describes the transport mechanism and data parameters for the Measurement Protocol.
Transport
All data must be sent securely using HTTPS POST
requests.
Send requests to the following endpoint:
https://www.google-analytics.com/mp/collect
If you want your data to be processed in the EU, use the following endpoint instead:
https://region1.google-analytics.com/mp/collect
Here's a sample POST
request:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
Replace PAYLOAD_DATA with Payload of the request.
The Measurement Protocol returns a 2xx
status code if the HTTP
request is received. The Measurement Protocol doesn't return an error code if
the payload is malformed, or if the data is incorrect or not processed by
Google Analytics.
Payload
The payload has two parts:
- Query parameters.
- A JSON
POST
body.
Query parameters
Parameter Name | Description |
---|---|
|
Required. The API Secret from the Google Analytics UI.
Found under Admin > Data Streams > Choose your stream > Measurement Protocol > Create. Private to your organization. Should be regularly updated to avoid excessive SPAM. |
JSON POST body
Key | Type | Description |
---|---|---|
|
string |
Optional. A unique identifier for a user. See User-ID for cross-platform analysis for more information on this identifier. Can include only utf-8 characters. |
|
number |
Optional. A Unix timestamp, microseconds, not milliseconds. Represents the time of the event. Should be set only to record events that happened
in the past. Can be overridden by
|
|
object |
Optional. The user properties for the measurement. |
|
object |
Optional. User-provided data. |
|
object |
Optional. Consent settings for the request. See the consent section for more information. |
|
boolean |
Optional. Set to true to indicate the user's data shouldn't
be used for personalized ads.
|
|
object |
Optional. Sets the geographic information for the request in a structured format. |
|
string |
Optional. IP address Google Analytics uses to derive geographic information for the request. |
|
array |
Required. An array of event items. Up to 25 events can be sent per
request. See the events
reference for all valid events.
|
|
string |
Required. Name of the event. See Events for all options. |
|
object |
Optional. Parameters for the event. See Events for the suggested parameters for each event. |
Consent
The consent
attribute configures consent types and states.
If you don't specify consent
, Google Analytics uses the consent
settings from corresponding online interactions for the client or app instance.
Key | Type | Description |
---|---|---|
|
string |
Optional. Consent for sending user data from the request's events and user properties to Google for advertising purposes. Either |
|
string |
Optional. Consent for personalized advertising for the user. Either |
Geographic information
The user_location
and ip_override
attributes provide geographic information.
user_location
takes precedence over ip_override
.
Here's the structure of the
user_location
field. Provide as many of the attributes as possible. We
recommend country_id
and region_id
at a minimum.
Key | Type | Description |
---|---|---|
|
string |
Optional. The city's name. |
|
string |
Optional. The ISO 3166 country and
subdivision. For example, US-CA , US-AR ,
CA-BC , GB-LND , CN-HK .
|
|
string |
Optional. The country in ISO 3166-1 alpha-2
format. For example, US , AU ,
ES , FR .
|
|
string |
Optional. The subcontinent in UN M49 format. For
example, 011 , 021 , 030 ,
039 .
|
|
string |
Optional. The continent in UN M49 format. For
example, 002 , 019 , 142 ,
150 .
|
Here's a sample user_location
:
"user_location:" {
"city:" "Mountain View",
"region_id:" "US-CA",
"country_id:" "US",
"subcontinent_id:" "021",
"continent_id:" "019"
}
ip_override
is an alternative to user_location
. If you send ip_override
instead, Google Analytics derives geographic information from the IP address.
If you send user_location
, Google Analytics ignores ip_override
.
If you don't send user_location
or ip_override
, Google
Analytics derives geographic information from tagging events using
client_id
.
Google Analytics applies the property's granular location data settings to the request, regardless of the geographic information sent.
Custom parameters
You can include custom user-scoped, event-scoped and item-scoped parameters in a Measurement Protocol payload.
- User-scoped custom parameters can be included in
user_properties
. - Event-scoped custom parameters can be included in
events[].params
. - Item-scoped custom parameters can be included in
items
.
Recommended values for certain events
Some events have recommended parameters. See events for the recommended parameters for all supported events.
Reserved names
Some event, parameter, and user property names are reserved and can't be used:
Reserved event names
The following event names are reserved and can't be used:
ad_activeview
ad_click
ad_exposure
ad_query
ad_reward
adunit_exposure
app_clear_data
app_exception
app_install
app_remove
app_store_refund
app_update
app_upgrade
dynamic_link_app_open
dynamic_link_app_update
dynamic_link_first_open
error
firebase_campaign
firebase_in_app_message_action
firebase_in_app_message_dismiss
firebase_in_app_message_impression
first_open
first_visit
in_app_purchase
notification_dismiss
notification_foreground
notification_open
notification_receive
notification_send
os_update
session_start
user_engagement
Reserved parameter names
The following parameter names are reserved and can't be used:
firebase_conversion
Parameter names can't begin with the following:
_ (underscore)
firebase_
ga_
google_
gtag.
Reserved user property names
The following user property names are reserved and can't be used:
first_open_time
first_visit_time
last_deep_link_referrer
user_id
first_open_after_install
Additionally, user property names can't begin with:
_ (underscore)
firebase_
ga_
google_