# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Esri Geocoding API
  version: 1.0.0
extends: openapi/esri-geocoding-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: 6
- target: $.paths['/World/GeocodeServer/findAddressCandidates'].get
  update:
    x-apievangelist-phrasing:
      intent: Match an address on the World GeocodeServer
      effect: read
      questions:
      - Can I send street, city, region and postal code separately to the World GeocodeServer and get candidate matches back?
      - What limits how many address candidates the World GeocodeServer findAddressCandidates endpoint returns?
      - Which ArcGIS World GeocodeServer call turns a typed address into ranked location candidates?
      instructions:
      - text: Find World GeocodeServer candidates for {address} in {city}, {region}, returning {f}.
        slots:
          address: query.address
          city: query.city
          region: query.region
          f: query.f
      - text: Match the single-line address {SingleLine} against the World GeocodeServer in country {countryCode}, at most {maxLocations} results as {f}.
        slots:
          SingleLine: query.SingleLine
          countryCode: query.countryCode
          maxLocations: query.maxLocations
          f: query.f
      method: generated
      generated: '2026-09-26'
- target: $.paths['/World/GeocodeServer/geocodeAddresses'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch geocode a list of addresses
      effect: read
      questions:
      - How do I geocode hundreds of addresses in one request instead of one at a time?
      - Can a batch geocoding job return its locations in a spatial reference I choose?
      instructions:
      - text: Batch geocode these addresses {addresses} and return the results as {f}.
        slots:
          addresses: requestBody.addresses
          f: requestBody.f
      - text: Geocode the address batch {addresses} in one request with output spatial reference {outSR}, format {f}.
        slots:
          addresses: requestBody.addresses
          outSR: requestBody.outSR
          f: requestBody.f
      method: generated
      generated: '2026-09-26'
- target: $.paths['/World/GeocodeServer/reverseGeocode'].get
  update:
    x-apievangelist-phrasing:
      intent: Reverse geocode a point on the World GeocodeServer
      effect: read
      questions:
      - Can I limit World GeocodeServer reverse geocoding to certain feature types, like a point of interest or street intersection?
      - Which World GeocodeServer endpoint gives me an address for an x,y coordinate with a chosen location type?
      instructions:
      - text: Reverse geocode {location} on the World GeocodeServer as {f}, returning only {featureTypes} features.
        slots:
          location: query.location
          f: query.f
          featureTypes: query.featureTypes
      - text: Look up the World GeocodeServer address at {location} using location type {locationType}, format {f}.
        slots:
          location: query.location
          locationType: query.locationType
          f: query.f
      method: generated
      generated: '2026-09-26'
- target: $.paths['/World/GeocodeServer/suggest'].get
  update:
    x-apievangelist-phrasing:
      intent: Autocomplete a partial address
      effect: read
      questions:
      - How do I show address autocomplete suggestions while a user is still typing?
      - Can address suggestions be biased toward a location or restricted to one country?
      - What caps the number of type-ahead suggestions returned for partial address text?
      instructions:
      - text: Suggest address completions for {text} as {f}.
        slots:
          text: query.text
          f: query.f
      - text: Give me up to {maxSuggestions} autocomplete suggestions for {text} near {location} in {countryCode}, format {f}.
        slots:
          maxSuggestions: query.maxSuggestions
          text: query.text
          location: query.location
          countryCode: query.countryCode
          f: query.f
      method: generated
      generated: '2026-09-26'
- target: $.paths['/findAddressCandidates'].get
  update:
    x-apievangelist-phrasing:
      intent: Geocode an address to coordinates
      effect: read
      questions:
      - How do I convert an address like 380 New York St, Redlands into coordinates with a match score?
      - Can I get forward-geocoding results back in a specific output spatial reference WKID?
      - Is it possible to request all output fields when geocoding an address with Esri?
      instructions:
      - text: Geocode {SingleLine} and return coordinates with match scores.
        slots:
          SingleLine: query.SingleLine
      - text: Forward geocode street {Address}, postal code {Postal}, country {CountryCode} and project the result to WKID {outSR}.
        slots:
          Address: query.Address
          Postal: query.Postal
          CountryCode: query.CountryCode
          outSR: query.outSR
      method: generated
      generated: '2026-09-26'
- target: $.paths['/reverseGeocode'].get
  update:
    x-apievangelist-phrasing:
      intent: Turn coordinates into a readable address
      effect: read
      questions:
      - What address is closest to a latitude and longitude I have?
      - Can I set how many meters from the point the reverse geocoder searches for an address?
      instructions:
      - text: Find the nearest address to point {location}.
        slots:
          location: query.location
      - text: Reverse geocode {location} searching within {distance} meters.
        slots:
          location: query.location
          distance: query.distance
      method: generated
      generated: '2026-09-26'