API Evangelist conversational phrasing for Meltwater Listening Analytics API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Meltwater Listening Analytics API
  version: 1.0.0
extends: openapi/meltwater-listening-analytics-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: 12
- target: $.paths['/v3/analytics/{searchId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize analytics for a saved search
      effect: read
      questions:
      - How much coverage did my saved search get over a time range in Meltwater?
      - Can I get an overall analytics summary limited to one country or language?
      - Why does unique authors come back as zero for news in my summary?
      instructions:
      - text: Summarize analytics for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Give me the analytics summary for search {searchId} between {start} and {end} ({tz}), only {language} documents from {country}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
          language: query.language
          country: query.country
      - text: Summarize {source} coverage for saved search {searchId} from {start} to {end}, timezone {tz}.
        slots:
          source: query.source
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top tags and hashtags in a saved search
      effect: read
      questions:
      - Which hashtags show up most in the results of my saved search?
      - Can I get more than the default top 10 tags for a search?
      instructions:
      - text: Show the top tags for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: List the top {size} hashtags in {source} results for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          source: query.source
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_locations'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top locations in a saved search
      effect: read
      questions:
      - Where geographically is my saved search being talked about most?
      - Can I break down search coverage by city or state instead of country?
      instructions:
      - text: Rank the top {level}-level locations for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          level: query.level
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top {size} cities mentioned in search {searchId} between {start} and {end} ({tz}), level {level}.
        slots:
          size: query.size
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
          level: query.level
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_shared'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the most shared documents in a saved search
      effect: read
      questions:
      - Which posts matching my saved search were shared the most?
      - Can I rank the most shared documents by retweets instead of another share metric?
      instructions:
      - text: Show the most shared documents for saved search {searchId} from {start} to {end} in {tz}, ranked by {sort_by}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
          sort_by: query.sort_by
      - text: Get the top {size} documents by {sort_by} for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          sort_by: query.sort_by
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_entities'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top named entities in a saved search
      effect: read
      questions:
      - Which people, brands and organizations are named most in my saved search?
      - Can I see the top named entities only in negative coverage?
      instructions:
      - text: List the top named entities for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top named entities in {sentiment} documents for search {searchId} between {start} and {end} ({tz}).
        slots:
          sentiment: query.sentiment
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_sources'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top sources and authors in a saved search
      effect: read
      questions:
      - Which outlets or authors produce the most results for my saved search?
      - Can I leave out low-authority sources when ranking who covers us?
      instructions:
      - text: Rank the top sources for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top authors for search {searchId} between {start} and {end} ({tz}) with authority score at least {min_authority}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
          min_authority: query.min_authority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_keyphrases'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top keyphrases in a saved search
      effect: read
      questions:
      - What phrases keep coming up in coverage matched by my saved search?
      - Can I pull the top keyphrases from positive coverage only?
      instructions:
      - text: List the top keyphrases for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top {size} keyphrases in {sentiment} documents for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          sentiment: query.sentiment
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_mentions'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top @mentions in a saved search
      effect: read
      questions:
      - Which accounts get @mentioned most in my saved search results?
      - Is it possible to see the top mentions from just one source?
      instructions:
      - text: List the top @mentions for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top {size} mentioned accounts in {source} for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          source: query.source
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_topics'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top topics and subtopics in a saved search
      effect: read
      questions:
      - What topics and subtopics dominate my saved search coverage?
      - Can I get a ranked topic breakdown for a single week of a search?
      instructions:
      - text: Rank the top topics and subtopics for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top {size} topics in {source} documents for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          source: query.source
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/top_shared_links'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the top shared links in a saved search
      effect: read
      questions:
      - Which URLs are being linked to most in my saved search results?
      - Can I find the most shared links from one country's coverage?
      instructions:
      - text: List the top shared links for saved search {searchId} from {start} to {end} in {tz}.
        slots:
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      - text: Show the top {size} shared URLs from {country} for search {searchId} between {start} and {end} ({tz}).
        slots:
          size: query.size
          country: query.country
          searchId: path.searchId
          start: query.start
          end: query.end
          tz: query.tz
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/analytics/{searchId}/custom'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a custom analytics query on a saved search
      effect: read
      questions:
      - Can I build my own analytics breakdown for a saved search instead of the fixed top lists?
      - How do I chart mentions of a saved search filtered by sentiment and country?
      - Is it possible to limit a custom analysis to specific keywords or emojis?
      instructions:
      - text: Run custom analytic {analytic} on saved search {searchId} from {start_date} to {end_date} in {tz}.
        slots:
          analytic: requestBody.analytic
          searchId: path.searchId
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          tz: requestBody.tz
      - text: Build a custom analysis of saved search {searchId} for {sentiments} mentions in {countries}, {start_date} to {end_date}, tz {tz}.
        slots:
          searchId: path.searchId
          sentiments: requestBody.sentiments
          countries: requestBody.countries
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          tz: requestBody.tz
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/analytics/custom/catalog'].get
  update:
    x-apievangelist-phrasing:
      intent: List options for custom listening analytics
      effect: read
      questions:
      - Which dimensions and measures can I use in a custom analytics request on a saved search?
      - What analytic types are available for custom listening analytics right now?
      instructions:
      - text: Fetch the catalog of dimensions, measures and analytic types for custom listening analytics.
      - text: Show me what I can put in a custom analytics request for my saved searches.
      method: generated
      generated: '2026-10-01'