# 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 User Country API
  version: 1.0.0
extends: openapi/matomo-usercountry-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: 8
- target: $.paths['/index.php?module=API&method=UserCountry.getCountry'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by country
      effect: read
      questions:
      - Which countries do most of my visitors come from?
      - Can I see visits per country for a segment like mobile users?
      instructions:
      - text: Show visits by country for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down visitor countries for site {idSite} on {date} limited to segment {segment}.
        slots:
          idSite: query.idSite
          date: query.date
          segment: query.segment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UserCountry.getContinent'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by continent
      effect: read
      questions:
      - How is my traffic split between Europe, Asia and the Americas?
      - What share of visits come from each continent?
      instructions:
      - text: Show visits by continent for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Summarize continental traffic 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=UserCountry.getRegion'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by region
      effect: read
      questions:
      - Which states or provinces send me the most visitors?
      - Can I see traffic broken down by region within countries?
      instructions:
      - text: Show visits by region for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: List the states and provinces visitors came from 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=UserCountry.getCity'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by city
      effect: read
      questions:
      - Which cities are my visitors located in?
      - What are the top cities for traffic last week?
      instructions:
      - text: Show visits by city for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank visitor cities 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=UserCountry.getCountryCodeMapping'].get
  update:
    x-apievangelist-phrasing:
      intent: Map ISO country codes to country names
      effect: read
      questions:
      - Can I get a lookup of ISO country codes to translated country names?
      - What country name does a two-letter code like 'de' map to?
      instructions:
      - text: Get the ISO country code to country name mapping.
      - text: Give me the list of country codes with their translated names.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UserCountry.getLocationFromIP'].get
  update:
    x-apievangelist-phrasing:
      intent: Geolocate an IP address
      effect: read
      questions:
      - Where in the world is a particular IP address located?
      - Can I test geolocation for an IP using a specific location provider?
      instructions:
      - text: Look up the location of IP {ip}.
        slots:
          ip: query.ip
      - text: Geolocate IP {ip} using location provider {provider}.
        slots:
          ip: query.ip
          provider: query.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UserCountry.setLocationProvider'].get
  update:
    x-apievangelist-phrasing:
      intent: Set the active geolocation provider
      effect: write
      questions:
      - How do I switch which geolocation provider is used for visitor locations?
      - Can I make a GeoIP database the active location provider?
      instructions:
      - text: Set the active geolocation provider to {providerId}.
        slots:
          providerId: query.providerId
      - text: Switch visitor geolocation to use provider {providerId}.
        slots:
          providerId: query.providerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=UserCountry.getNumberOfDistinctCountries'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct visitor countries in a period
      effect: read
      questions:
      - How many different countries did visitors come from this month?
      - Can I get just the number of unique countries for a period?
      instructions:
      - text: Count the distinct countries for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me how many unique countries visited site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'