Google Analytics API — data

naftiko: 1.0.0-alpha2
info:
  label: Google Analytics API — data
  description: 'Google Analytics API — data. 3 operations. Lead operation: data. Self-contained Naftiko capability covering
    one Google Analytics business surface.'
  tags:
  - Google Analytics
  - data
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    GOOGLE_ANALYTICS_API_KEY: GOOGLE_ANALYTICS_API_KEY
capability:
  consumes:
  - type: http
    namespace: management-api-v3-data
    baseUri: https://analytics.googleapis.com/analytics/v3
    description: Google Analytics API — data business capability. Self-contained, no shared references.
    resources:
    - name: data-ga
      path: /data/ga
      operations:
      - name: analyticsdatagaget
        method: GET
        description: Returns Analytics data for a view (profile).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: string
          description: Unique table ID for retrieving Analytics data. Table ID is of the form ga:XXXX, where XXXX is the Analytics
            view (profile) ID.
          required: true
        - name: start-date
          in: query
          type: string
          description: 'Start date for fetching Analytics data. Requests can specify a start date formatted as YYYY-MM-DD,
            or as a relative date (e.g., today, yesterday, or 7daysAgo). '
          required: true
        - name: end-date
          in: query
          type: string
          description: End date for fetching Analytics data. Request can should specify an end date formatted as YYYY-MM-DD,
            or as a relative date (e.g., today, yesterday, or 7daysAgo
          required: true
        - name: metrics
          in: query
          type: string
          description: A comma-separated list of Analytics metrics. E.g., 'ga:sessions,ga:pageviews'. At least one metric
            must be specified.
          required: true
        - name: dimensions
          in: query
          type: string
          description: A comma-separated list of Analytics dimensions. E.g., 'ga:browser,ga:city'.
        - name: filters
          in: query
          type: string
          description: A comma-separated list of dimension or metric filters to be applied to Analytics data.
        - name: include-empty-rows
          in: query
          type: boolean
          description: The response will include empty rows if this parameter is set to true, the default is true
        - name: max-results
          in: query
          type: integer
          description: The maximum number of entries to include in this feed.
        - name: output
          in: query
          type: string
          description: The selected format for the response. Default format is JSON.
        - name: samplingLevel
          in: query
          type: string
          description: The desired sampling level.
        - name: segment
          in: query
          type: string
          description: An Analytics segment to be applied to data.
        - name: sort
          in: query
          type: string
          description: A comma-separated list of dimensions or metrics that determine the sort order for Analytics data.
        - name: start-index
          in: query
          type: integer
          description: An index of the first entity to retrieve. Use this parameter as a pagination mechanism along with the
            max-results parameter.
    - name: data-mcf
      path: /data/mcf
      operations:
      - name: analyticsdatamcfget
        method: GET
        description: Returns Analytics Multi-Channel Funnels data for a view (profile).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: string
          description: Unique table ID for retrieving Analytics data. Table ID is of the form ga:XXXX, where XXXX is the Analytics
            view (profile) ID.
          required: true
        - name: start-date
          in: query
          type: string
          description: 'Start date for fetching Analytics data. Requests can specify a start date formatted as YYYY-MM-DD,
            or as a relative date (e.g., today, yesterday, or 7daysAgo). '
          required: true
        - name: end-date
          in: query
          type: string
          description: End date for fetching Analytics data. Requests can specify a start date formatted as YYYY-MM-DD, or
            as a relative date (e.g., today, yesterday, or 7daysAgo). Th
          required: true
        - name: metrics
          in: query
          type: string
          description: A comma-separated list of Multi-Channel Funnels metrics. E.g., 'mcf:totalConversions,mcf:totalConversionValue'.
            At least one metric must be specified.
          required: true
        - name: dimensions
          in: query
          type: string
          description: A comma-separated list of Multi-Channel Funnels dimensions. E.g., 'mcf:source,mcf:medium'.
        - name: filters
          in: query
          type: string
          description: A comma-separated list of dimension or metric filters to be applied to the Analytics data.
        - name: max-results
          in: query
          type: integer
          description: The maximum number of entries to include in this feed.
        - name: samplingLevel
          in: query
          type: string
          description: The desired sampling level.
        - name: sort
          in: query
          type: string
          description: A comma-separated list of dimensions or metrics that determine the sort order for the Analytics data.
        - name: start-index
          in: query
          type: integer
          description: An index of the first entity to retrieve. Use this parameter as a pagination mechanism along with the
            max-results parameter.
    - name: data-realtime
      path: /data/realtime
      operations:
      - name: analyticsdatarealtimeget
        method: GET
        description: Returns real time data for a view (profile).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: string
          description: Unique table ID for retrieving real time data. Table ID is of the form ga:XXXX, where XXXX is the Analytics
            view (profile) ID.
          required: true
        - name: metrics
          in: query
          type: string
          description: A comma-separated list of real time metrics. E.g., 'rt:activeUsers'. At least one metric must be specified.
          required: true
        - name: dimensions
          in: query
          type: string
          description: A comma-separated list of real time dimensions. E.g., 'rt:medium,rt:city'.
        - name: filters
          in: query
          type: string
          description: A comma-separated list of dimension or metric filters to be applied to real time data.
        - name: max-results
          in: query
          type: integer
          description: The maximum number of entries to include in this feed.
        - name: sort
          in: query
          type: string
          description: A comma-separated list of dimensions or metrics that determine the sort order for real time data.
    authentication:
      type: bearer
      token: '{{env.GOOGLE_ANALYTICS_API_KEY}}'
  exposes:
  - type: rest
    namespace: management-api-v3-data-rest
    port: 8080
    description: REST adapter for Google Analytics API — data. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/data/ga
      name: data-ga
      description: REST surface for data-ga.
      operations:
      - method: GET
        name: analyticsdatagaget
        description: Returns Analytics data for a view (profile).
        call: management-api-v3-data.analyticsdatagaget
        with:
          ids: rest.ids
          start-date: rest.start-date
          end-date: rest.end-date
          metrics: rest.metrics
          dimensions: rest.dimensions
          filters: rest.filters
          include-empty-rows: rest.include-empty-rows
          max-results: rest.max-results
          output: rest.output
          samplingLevel: rest.samplingLevel
          segment: rest.segment
          sort: rest.sort
          start-index: rest.start-index
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/data/mcf
      name: data-mcf
      description: REST surface for data-mcf.
      operations:
      - method: GET
        name: analyticsdatamcfget
        description: Returns Analytics Multi-Channel Funnels data for a view (profile).
        call: management-api-v3-data.analyticsdatamcfget
        with:
          ids: rest.ids
          start-date: rest.start-date
          end-date: rest.end-date
          metrics: rest.metrics
          dimensions: rest.dimensions
          filters: rest.filters
          max-results: rest.max-results
          samplingLevel: rest.samplingLevel
          sort: rest.sort
          start-index: rest.start-index
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/data/realtime
      name: data-realtime
      description: REST surface for data-realtime.
      operations:
      - method: GET
        name: analyticsdatarealtimeget
        description: Returns real time data for a view (profile).
        call: management-api-v3-data.analyticsdatarealtimeget
        with:
          ids: rest.ids
          metrics: rest.metrics
          dimensions: rest.dimensions
          filters: rest.filters
          max-results: rest.max-results
          sort: rest.sort
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: management-api-v3-data-mcp
    port: 9090
    transport: http
    description: MCP adapter for Google Analytics API — data. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: returns-analytics-data-view-profile
      description: Returns Analytics data for a view (profile).
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: management-api-v3-data.analyticsdatagaget
      with:
        ids: tools.ids
        start-date: tools.start-date
        end-date: tools.end-date
        metrics: tools.metrics
        dimensions: tools.dimensions
        filters: tools.filters
        include-empty-rows: tools.include-empty-rows
        max-results: tools.max-results
        output: tools.output
        samplingLevel: tools.samplingLevel
        segment: tools.segment
        sort: tools.sort
        start-index: tools.start-index
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-analytics-multi-channel-funnels
      description: Returns Analytics Multi-Channel Funnels data for a view (profile).
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: management-api-v3-data.analyticsdatamcfget
      with:
        ids: tools.ids
        start-date: tools.start-date
        end-date: tools.end-date
        metrics: tools.metrics
        dimensions: tools.dimensions
        filters: tools.filters
        max-results: tools.max-results
        samplingLevel: tools.samplingLevel
        sort: tools.sort
        start-index: tools.start-index
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-real-time-data-view
      description: Returns real time data for a view (profile).
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: management-api-v3-data.analyticsdatarealtimeget
      with:
        ids: tools.ids
        metrics: tools.metrics
        dimensions: tools.dimensions
        filters: tools.filters
        max-results: tools.max-results
        sort: tools.sort
      outputParameters:
      - type: object
        mapping: $.