# 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 Azure Maps Service Spatial API
  version: 1.0.0
extends: openapi/microsoft-azure-spatial-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: 9
- target: $.paths['/spatial/geofence/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a device against an uploaded geofence
      effect: read
      questions:
      - Is my tracked device inside or near a geofence I uploaded to Azure Maps?
      - Can I add a search buffer around my stored geofence?
      instructions:
      - text: Check device {deviceId} at {lat},{lon} against uploaded geofence {udId}.
        slots:
          deviceId: query.deviceId
          lat: query.lat
          lon: query.lon
          udId: query.udId
      - text: Get geofence proximity for device {deviceId} at {lat},{lon} using fence {udId} in {format} format.
        slots:
          deviceId: query.deviceId
          lat: query.lat
          lon: query.lon
          udId: query.udId
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/geofence/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a device against geofences in the request
      effect: read
      questions:
      - Can I test a coordinate against a geofence without uploading it first?
      - How do I send my own fence features and get the device's proximity back?
      instructions:
      - text: Check device {deviceId} at {lat},{lon} against the fence features {features} I provide.
        slots:
          deviceId: query.deviceId
          lat: query.lat
          lon: query.lon
          features: requestBody.features
      - text: Evaluate an inline geofence of type {type} for device {deviceId} at {lat},{lon} in {format}.
        slots:
          type: requestBody.type
          deviceId: query.deviceId
          lat: query.lat
          lon: query.lon
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/buffer/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Buffer features from an uploaded dataset
      effect: read
      questions:
      - How do I draw a buffer zone around features I've uploaded to Azure Maps?
      - Can I use a negative distance to buffer inside a stored polygon?
      instructions:
      - text: Create buffers of {distances} meters around uploaded dataset {udid}.
        slots:
          distances: query.distances
          udid: query.udid
      - text: Buffer the features in uploaded data {udid} by {distances} and return {format}.
        slots:
          distances: query.distances
          udid: query.udid
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/buffer/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Buffer geometries sent in the request
      effect: read
      questions:
      - Can I buffer geometries I send directly instead of uploading them?
      - What does the inline buffer API return for each input feature?
      instructions:
      - text: Buffer the geometries {geometries} I'm sending by {distances}.
        slots:
          geometries: requestBody.geometries
          distances: requestBody.distances
      - text: Return {format} buffers around my inline geometries {geometries}.
        slots:
          geometries: requestBody.geometries
          format: path.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/closestPoint/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find nearest points in an uploaded dataset
      effect: read
      questions:
      - Which of my uploaded points is closest to a given location?
      - Can I get more than one closest point back from a stored dataset?
      instructions:
      - text: Find the closest point in uploaded dataset {udid} to {lat},{lon}.
        slots:
          udid: query.udid
          lat: query.lat
          lon: query.lon
      - text: Return the {numberOfClosestPoints} nearest points in dataset {udid} to {lat},{lon} in {format}.
        slots:
          format: path.format
          numberOfClosestPoints: query.numberOfClosestPoints
          udid: query.udid
          lat: query.lat
          lon: query.lon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/closestPoint/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Find nearest points among points in the request
      effect: read
      questions:
      - Can I find the nearest of a set of target points I send in the request body?
      - How do I get the closest point without uploading a dataset?
      instructions:
      - text: Find which of my inline points {features} is closest to {lat},{lon}.
        slots:
          features: requestBody.features
          lat: query.lat
          lon: query.lon
      - text: Return the {numberOfClosestPoints} closest of the posted points to {lat},{lon} as {format}.
        slots:
          format: path.format
          numberOfClosestPoints: query.numberOfClosestPoints
          lat: query.lat
          lon: query.lon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/pointInPolygon/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Test if a point is inside uploaded polygons
      effect: read
      questions:
      - Is a coordinate inside any of the polygons I uploaded to Azure Maps?
      - Which stored polygon contains a given latitude and longitude?
      instructions:
      - text: Check whether {lat},{lon} falls inside the polygons in uploaded dataset {udid}.
        slots:
          lat: query.lat
          lon: query.lon
          udid: query.udid
      - text: Tell me if point {lat},{lon} is within stored polygon set {udid}, answering in {format}.
        slots:
          format: path.format
          lat: query.lat
          lon: query.lon
          udid: query.udid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/pointInPolygon/{format}'].post
  update:
    x-apievangelist-phrasing:
      intent: Test if a point is inside polygons in the request
      effect: read
      questions:
      - Can I check point-in-polygon against polygons I post rather than upload?
      - Are non-polygon geometries ignored when I send inline features?
      instructions:
      - text: Check whether {lat},{lon} is inside the polygons {features} I'm sending.
        slots:
          lat: query.lat
          lon: query.lon
          features: requestBody.features
      - text: Test point {lat},{lon} against my inline polygon collection of type {type}, returning {format}.
        slots:
          format: path.format
          lat: query.lat
          lon: query.lon
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/spatial/greatCircleDistance/{format}'].get
  update:
    x-apievangelist-phrasing:
      intent: Calculate great-circle distance between points
      effect: read
      questions:
      - What is the shortest distance over the earth's surface between two coordinates?
      - How do I get the great-circle distance rather than a straight-line one?
      instructions:
      - text: Calculate the great-circle distance for coordinates {query}.
        slots:
          query: query.query
      - text: Give me the surface distance between the two points in {query} as {format}.
        slots:
          query: query.query
          format: path.format
      method: generated
      generated: '2026-09-26'