Google Analytics Measurement Protocol (GA4)

openapi: 3.0.3
info:
  title: Google Analytics Measurement Protocol (GA4)
  description: >-
    The Google Analytics Measurement Protocol lets you send events directly to
    Google Analytics servers via HTTP requests to augment existing GA4 data with
    server-to-server and offline interactions.
  version: '1.0'
  contact:
    name: Google Analytics
    url: https://developers.google.com/analytics
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/analytics/terms
  x-logo:
    url: https://www.google.com/analytics/images/google-analytics-logo.png
externalDocs:
  description: Measurement Protocol documentation
  url: https://developers.google.com/analytics/devguides/collection/protocol/ga4
servers:
- url: https://www.google-analytics.com/mp
  description: Global endpoint
- url: https://region1.google-analytics.com/mp
  description: EU endpoint
paths:
  /collect:
    post:
      operationId: collectEvents
      summary: Google Analytics Send Events to Google Analytics
      description: >-
        Sends one or more events to Google Analytics for processing. Up to 25
        events can be sent per request. Events can be backdated up to 72 hours.
      parameters:
      - name: api_secret
        in: query
        required: true
        description: >-
          The API Secret generated in the Google Analytics UI. Found under
          Admin > Data Streams > Choose your stream > Measurement Protocol > Create.
        schema:
          type: string
        example: secret_abc123
      - name: measurement_id
        in: query
        required: false
        description: >-
          The Measurement ID for a web data stream. Required for web streams.
          Found in the Google Analytics UI under Admin > Data Streams.
        schema:
          type: string
        example: '123456'
      - name: firebase_app_id
        in: query
        required: false
        description: >-
          The Firebase App ID for an app data stream. Required for app streams.
          Found in the Firebase console under Project Settings.
        schema:
          type: string
        example: '123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementPayload'
      responses:
        '204':
          description: >-
            Events accepted. Note that a 2xx response does not guarantee the
            events are valid or will appear in reports. The Measurement Protocol
            does not return error details for malformed payloads.
        '400':
          description: Malformed request
        '403':
          description: Invalid api_secret
      tags:
      - Events
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /collect/debug:
    post:
      operationId: validateEvents
      summary: Google Analytics Validate Events Without Sending to Google Analytics
      description: >-
        Validates the event payload and returns validation messages without
        actually sending the events to Google Analytics. Use this endpoint
        during development to verify your implementation.
      parameters:
      - name: api_secret
        in: query
        required: true
        description: The API Secret generated in the Google Analytics UI.
        schema:
          type: string
        example: secret_abc123
      - name: measurement_id
        in: query
        required: false
        description: The Measurement ID for a web data stream. Required for web streams.
        schema:
          type: string
        example: '123456'
      - name: firebase_app_id
        in: query
        required: false
        description: The Firebase App ID for an app data stream. Required for app streams.
        schema:
          type: string
        example: '123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementPayload'
      responses:
        '200':
          description: Validation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
      tags:
      - Validation
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    MeasurementPayload:
      type: object
      required:
      - events
      properties:
        client_id:
          type: string
          description: >-
            Uniquely identifies a user instance of a web client. Required for
            web streams.
          example: '123456789.1234567890'
        app_instance_id:
          type: string
          description: >-
            Uniquely identifies a user instance of an app. Required for app
            streams.
          example: '123456'
        user_id:
          type: string
          description: >-
            A unique identifier for a user. Enables cross-platform analysis.
            Must contain only UTF-8 characters.
          example: '123456'
        timestamp_micros:
          type: integer
          format: int64
          description: >-
            Unix timestamp in microseconds for the request. Used to backdate
            events up to 72 hours.
          example: 1713355200000000
        user_properties:
          type: object
          description: User-scoped properties for the measurement.
          additionalProperties:
            $ref: '#/components/schemas/UserPropertyValue'
        user_data:
          type: object
          description: User-provided data for enhanced measurement.
        consent:
          $ref: '#/components/schemas/Consent'
        non_personalized_ads:
          type: boolean
          description: Deprecated. Use consent.ad_personalization instead.
          deprecated: true
          example: true
        user_location:
          $ref: '#/components/schemas/UserLocation'
        ip_override:
          type: string
          description: IP address used to derive geographic information.
          example: '123456'
        device:
          $ref: '#/components/schemas/Device'
        validation_behavior:
          type: string
          description: >-
            Controls validation strictness. RELAXED only rejects malformed
            requests. ENFORCE_RECOMMENDATIONS also rejects invalid types and
            exceeded limits.
          enum:
          - RELAXED
          - ENFORCE_RECOMMENDATIONS
          default: RELAXED
          example: RELAXED
        events:
          type: array
          description: Array of event objects. Maximum 25 events per request.
          maxItems: 25
          items:
            $ref: '#/components/schemas/Event'
    Event:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: >-
            The name of the event. Must not use reserved names (ad_click,
            app_exception, error, session_start, etc.) or reserved prefixes
            (_, firebase_, ga_, google_, gtag.).
          example: Example Name
        params:
          type: object
          description: >-
            Event parameters as key-value pairs. Common parameters include
            session_id, engagement_time_msec, and timestamp_micros.
          additionalProperties: true
          properties:
            session_id:
              type: string
              description: Session identifier for accurate session metrics.
            engagement_time_msec:
              type: integer
              description: User engagement duration in milliseconds.
            timestamp_micros:
              type: integer
              format: int64
              description: Unix epoch time in microseconds to override event timestamp.
    UserPropertyValue:
      type: object
      properties:
        value:
          oneOf:
          - type: string
          - type: number
          - type: boolean
          description: The value of the user property.
          example: example_value
    Consent:
      type: object
      properties:
        ad_user_data:
          type: string
          description: Consent for using user data in advertising.
          enum:
          - GRANTED
          - DENIED
          example: GRANTED
        ad_personalization:
          type: string
          description: Consent for ad personalization.
          enum:
          - GRANTED
          - DENIED
          example: GRANTED
    UserLocation:
      type: object
      properties:
        city:
          type: string
          description: City name.
          example: example_value
        region_id:
          type: string
          description: Region identifier.
          example: '123456'
        country_id:
          type: string
          description: Country identifier.
          example: '123456'
        subcontinent_id:
          type: string
          description: Subcontinent identifier.
          example: '123456'
        continent_id:
          type: string
          description: Continent identifier.
          example: '123456'
    Device:
      type: object
      properties:
        category:
          type: string
          description: Device category (e.g., mobile, tablet, desktop).
          example: example_value
        language:
          type: string
          description: Device language setting.
          example: example_value
        screen_resolution:
          type: string
          description: Screen resolution (e.g., 1920x1080).
          example: example_value
        operating_system:
          type: string
          description: Operating system name.
          example: example_value
        operating_system_version:
          type: string
          description: Operating system version.
          example: example_value
        model:
          type: string
          description: Device model.
          example: example_value
        brand:
          type: string
          description: Device brand.
          example: example_value
        browser:
          type: string
          description: Browser name.
          example: example_value
        browser_version:
          type: string
          description: Browser version.
          example: example_value
    ValidationResponse:
      type: object
      properties:
        validationMessages:
          type: array
          items:
            $ref: '#/components/schemas/ValidationMessage'
    ValidationMessage:
      type: object
      properties:
        fieldPath:
          type: string
          description: Path to the field that caused the validation error.
          example: /example/path
        description:
          type: string
          description: Description of the validation error.
          example: Example description
        validationCode:
          type: string
          description: A code identifying the type of validation error.
          enum:
          - VALUE_INVALID
          - VALUE_REQUIRED
          - NAME_INVALID
          - NAME_RESERVED
          - VALUE_OUT_OF_BOUNDS
          - EXCEEDED_MAX_ENTITIES
          - NAME_DUPLICATED
          example: VALUE_INVALID