# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Search API
  version: 1.0.0
extends: openapi/microsoft-azure-search-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 18
- target: $.paths['/search/autocomplete'].post
  update:
    x-apievangelist-phrasing:
      intent: Autocomplete catalog discovery keywords
      effect: read
      questions:
      - Can I get autocomplete options while a user types catalog search keywords?
      - How do I complete a partial keyword against the data discovery catalog?
      instructions:
      - text: Autocomplete the catalog keyword {keywords}.
        slots:
          keywords: requestBody.keywords
      - text: Give me {limit} autocomplete options for {keywords} using filter {filter}.
        slots:
          limit: requestBody.limit
          keywords: requestBody.keywords
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the data catalog for assets
      effect: read
      questions:
      - How do I search the data catalog for assets that match keywords?
      - Can I get facets and sort order back when querying catalog assets?
      instructions:
      - text: Search the data catalog for {keywords}.
        slots:
          keywords: requestBody.keywords
      - text: Query catalog assets matching {keywords} with filter {filter} and facets {facets}.
        slots:
          keywords: requestBody.keywords
          filter: requestBody.filter
          facets: requestBody.facets
      - text: Fetch the next page of catalog search results with token {continuationToken}.
        slots:
          continuationToken: requestBody.continuationToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/suggest'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest catalog assets for a search term
      effect: read
      questions:
      - What asset suggestions does the catalog offer for a term I'm typing?
      - Can I show suggested catalog results instead of full search results?
      instructions:
      - text: Suggest catalog assets for {keywords}.
        slots:
          keywords: requestBody.keywords
      - text: Return {limit} catalog search suggestions for {keywords} filtered by {filter}.
        slots:
          limit: requestBody.limit
          keywords: requestBody.keywords
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/polygon/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get outline geometry for places
      effect: read
      questions:
      - How do I get the boundary outline of a city or country I already found in Azure Maps?
      - Can I fetch polygon geometry for geometry IDs returned by an earlier search?
      instructions:
      - text: Get the polygon outlines for geometry IDs {geometries} as {format}.
        slots:
          geometries: query.geometries
          format: path.format
      - text: Fetch the boundary shape for geometry {geometries}.
        slots:
          geometries: query.geometries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/fuzzy/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Free-form search for addresses and places
      effect: read
      questions:
      - Can one search box handle both addresses and points of interest?
      - What's the way to search places with a messy free-text query near a location?
      instructions:
      - text: Free-form search for {query} near {lat}, {lon}.
        slots:
          query: query.query
          lat: query.lat
          lon: query.lon
      - text: Fuzzy search {query} limited to countries {countrySet}.
        slots:
          query: query.query
          countrySet: query.countrySet
      - text: Run a free-form search for {query} and return {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/poi/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find points of interest by name
      effect: read
      questions:
      - How do I find a point of interest like a specific restaurant by its name?
      - Can I search POIs by name and filter by brand?
      instructions:
      - text: Find points of interest named {query}.
        slots:
          query: query.query
      - text: Search POIs named {query} within {radius} meters of {lat}, {lon}.
        slots:
          query: query.query
          radius: query.radius
          lat: query.lat
          lon: query.lon
      - text: Look up the POI named {query} and return {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/nearby/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find points of interest around a location
      effect: read
      questions:
      - What points of interest are around a given coordinate without a search term?
      - Can I just list nearby places within a radius of my location?
      instructions:
      - text: Show points of interest near {lat}, {lon}.
        slots:
          lat: query.lat
          lon: query.lon
      - text: List nearby places within {radius} meters of {lat}, {lon} in categories {categorySet}.
        slots:
          radius: query.radius
          lat: query.lat
          lon: query.lon
          categorySet: query.categorySet
      - text: Return nearby POIs around {lat}, {lon} as {format}.
        slots:
          lat: query.lat
          lon: query.lon
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/poi/category/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find points of interest by category
      effect: read
      questions:
      - How do I find all gas stations or cafes by category rather than by name?
      - Can I search a POI category within a bounding area?
      instructions:
      - text: Find points of interest in category {query}.
        slots:
          query: query.query
      - text: Search the POI category {query} near {lat}, {lon}.
        slots:
          query: query.query
          lat: query.lat
          lon: query.lon
      - text: Return places in POI category {query} as {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/poi/category/tree/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: List supported POI categories
      effect: read
      questions:
      - Which point of interest categories and subcategories does Azure Maps support?
      - Where can I get category IDs to use in a categorySet filter?
      instructions:
      - text: Get the full POI category tree as {format}.
        slots:
          format: path.format
      - text: List the POI categories with names in {language}.
        slots:
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Geocode an address to coordinates
      effect: read
      questions:
      - How do I convert an address into latitude and longitude?
      - Can I geocode only addresses without getting business results?
      instructions:
      - text: Geocode the address {query}.
        slots:
          query: query.query
      - text: Find coordinates for {query} limited to countries {countrySet}.
        slots:
          query: query.query
          countrySet: query.countrySet
      - text: Geocode {query} and return the result as {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/reverse/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Reverse geocode a coordinate to an address
      effect: read
      questions:
      - How do I turn a latitude and longitude into a street address?
      - Can reverse geocoding also return the speed limit at that point?
      instructions:
      - text: Reverse geocode {query} to a street address.
        slots:
          query: query.query
      - text: Get the address and speed limit at {query}.
        slots:
          query: query.query
      - text: Reverse geocode {query} and return the address as {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/reverse/crossStreet/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the nearest cross street to a coordinate
      effect: read
      questions:
      - What is the nearest intersection to a given coordinate?
      - Can I get cross street names for a location instead of a full address?
      instructions:
      - text: Find the nearest cross street to {query}.
        slots:
          query: query.query
      - text: Get the intersection closest to {query} while heading {heading} degrees.
        slots:
          query: query.query
          heading: query.heading
      - text: Return the cross street nearest {query} as {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/structured/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Geocode an address given as separate fields
      effect: read
      questions:
      - Can I geocode an address when I have street, city and postal code as separate fields?
      - Is a country code required for structured address lookup?
      instructions:
      - text: Geocode {streetNumber} {streetName}, {municipality} in country {countryCode}.
        slots:
          streetNumber: query.streetNumber
          streetName: query.streetName
          municipality: query.municipality
          countryCode: query.countryCode
      - text: Look up postal code {postalCode} in country {countryCode} as a structured address.
        slots:
          postalCode: query.postalCode
          countryCode: query.countryCode
      - text: Geocode the structured address in {municipality}, {countryCode} and return {format}.
        slots:
          municipality: query.municipality
          countryCode: query.countryCode
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/geometry/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Search for places inside a geometry
      effect: read
      questions:
      - How do I find places that fall inside a polygon or circle I draw?
      - Can I restrict a free-form search to one or more geometries?
      instructions:
      - text: Search for {query} inside the geometry {geometry}.
        slots:
          query: query.query
          geometry: requestBody.geometry
      - text: 'Find {query} within these shapes limited to {limit} results: {geometry}.'
        slots:
          query: query.query
          limit: query.limit
          geometry: requestBody.geometry
      - text: Search {query} inside {geometry} and return {format}.
        slots:
          query: query.query
          geometry: requestBody.geometry
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/alongRoute/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Find places along a driving route
      effect: read
      questions:
      - Can I find gas stations along my route without a long detour?
      - How do I search points of interest on a route with a maximum detour time?
      instructions:
      - text: Find {query} along route {route} with at most {maxDetourTime} seconds of detour.
        slots:
          query: query.query
          route: requestBody.route
          maxDetourTime: query.maxDetourTime
      - text: 'Search {query} on this route within a {maxDetourTime}-second detour: {route}.'
        slots:
          query: query.query
          maxDetourTime: query.maxDetourTime
          route: requestBody.route
      - text: Search {query} along {route} within {maxDetourTime} seconds detour, returning {format}.
        slots:
          query: query.query
          route: requestBody.route
          maxDetourTime: query.maxDetourTime
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/fuzzy/batch/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Run many free-form place searches in one batch
      effect: read
      questions:
      - Can I send many fuzzy place searches in a single request?
      - What's the batch option for free-form search on the S1 tier?
      instructions:
      - text: 'Run this batch of fuzzy searches: {batchItems}.'
        slots:
          batchItems: requestBody.batchItems
      - text: 'Submit these free-form place queries as one batch and return {format}: {batchItems}.'
        slots:
          format: path.format
          batchItems: requestBody.batchItems
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/batch/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Geocode many addresses in one batch
      effect: read
      questions:
      - How do I geocode a list of addresses at once?
      - Is there a batch version of address geocoding?
      instructions:
      - text: 'Geocode this batch of addresses: {batchItems}.'
        slots:
          batchItems: requestBody.batchItems
      - text: 'Batch-geocode these address queries as {format}: {batchItems}.'
        slots:
          format: path.format
          batchItems: requestBody.batchItems
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search/address/reverse/batch/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Reverse geocode many coordinates in one batch
      effect: read
      questions:
      - Can I reverse geocode a whole list of coordinates in one call?
      - Which endpoint turns many latitude/longitude pairs into addresses together?
      instructions:
      - text: 'Reverse geocode this batch of coordinates: {batchItems}.'
        slots:
          batchItems: requestBody.batchItems
      - text: 'Batch-convert these points to addresses as {format}: {batchItems}.'
        slots:
          format: path.format
          batchItems: requestBody.batchItems
      method: generated
      generated: '2026-09-26'