Measurement Protocol reference

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:

  1. Query parameters.
  2. A JSON POST body.

Query parameters

Parameter Name Description

api_secret

 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

user_id

 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.

timestamp_micros

 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 user_property or event timestamps. Events can be backdated up to 3 calendar days based on the property's timezone.

user_properties

 object Optional. The user properties for the measurement.

user_data

 object Optional. User-provided data.
object Optional. Consent settings for the request. See the consent section for more information.

non_personalized_ads

 boolean Optional. Set to true to indicate the user's data shouldn't be used for personalized ads.

user_location

 object Optional. Sets the geographic information for the request in a structured format.

ip_override

 string Optional. IP address Google Analytics uses to derive geographic information for the request.

events[]

 array Required. An array of event items. Up to 25 events can be sent per request. See the events reference for all valid events.

events[].name

 string Required. Name of the event. See Events for all options.

events[].params

 object Optional. Parameters for the event. See Events for the suggested parameters for each event.

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

ad_user_data

 string

Optional. Consent for sending user data from the request's events and user properties to Google for advertising purposes.

Either GRANTED or DENIED.

ad_personalization

 string

Optional. Consent for personalized advertising for the user.

Either GRANTED or DENIED.

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

city

 string Optional. The city's name.

region_id

 string Optional. The ISO 3166 country and subdivision. For example, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Optional. The country in ISO 3166-1 alpha-2 format. For example, US, AU, ES, FR.

subcontinent_id

 string Optional. The subcontinent in UN M49 format. For example, 011, 021, 030, 039.

continent_id

 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.

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_