# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Reporting API for plugin Visitor Interest API
  version: 1.0.0
extends: openapi/matomo-visitorinterest-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 4
- target: $.paths['/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerVisitDuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by visit duration
      effect: read
      questions:
      - How long do visitors typically stay on my site?
      - What share of visits last under 30 seconds?
      instructions:
      - text: Show the distribution of visit durations for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Group visits by time spent on site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerPage'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by pages viewed
      effect: read
      questions:
      - How many pages do visitors usually look at per visit?
      - What portion of visits only view a single page?
      instructions:
      - text: Show the page-depth distribution for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Group visits by number of pages viewed on site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByDaysSinceLast'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by days since previous visit
      effect: read
      questions:
      - How many days pass before returning visitors come back?
      - Do my returning visitors come back within a week?
      instructions:
      - text: Show visits grouped by days since the previous visit for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down return gaps in days for site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByVisitCount'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by lifetime visit count
      effect: read
      questions:
      - How many of my visitors are on their first, second or tenth visit?
      - What does visitor loyalty look like by total number of visits?
      instructions:
      - text: Show visits grouped by lifetime visit count for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down loyalty by visit number for site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'