API Evangelist conversational phrasing for Interactive Map API v1 Read Features API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Interactive Map API v1 Read Features API
  version: 1.0.0
extends: openapi/here-read-features-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['/layers/{layerId}/features'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several map features by their IDs
      effect: read
      questions:
      - How do I fetch a list of features by ID from an interactive map layer?
      - What comes back if none of the feature IDs exist?
      instructions:
      - text: Get features {ids} from layer {layer_id}.
        slots:
          ids: query.id
          layer_id: path.layerId
      - text: Fetch features {ids} from layer {layer_id} at version {version_ref}.
        slots:
          ids: query.id
          layer_id: path.layerId
          version_ref: query.versionRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features/{featureId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one map feature by ID
      effect: read
      questions:
      - Can I retrieve a single feature from a layer by its identifier?
      - Is it possible to read an older version of one feature?
      instructions:
      - text: Get feature {feature_id} from layer {layer_id}.
        slots:
          feature_id: path.featureId
          layer_id: path.layerId
      - text: Show feature {feature_id} in layer {layer_id} as 2D with force2D {force2d}.
        slots:
          feature_id: path.featureId
          layer_id: path.layerId
          force2d: query.force2D
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/statistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get statistics about a map layer
      effect: read
      questions:
      - What statistics can I see about an interactive map layer?
      - Can I bypass the cache when reading layer statistics?
      instructions:
      - text: Get statistics for layer {layer_id}.
        slots:
          layer_id: path.layerId
      - text: Show fresh statistics for layer {layer_id} with skip cache {skip_cache}.
        slots:
          layer_id: path.layerId
          skip_cache: query.skipCache
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/bbox'].get
  update:
    x-apievangelist-phrasing:
      intent: Get map features inside a bounding box
      effect: read
      questions:
      - Which features fall inside a rectangular area of my map layer?
      - Can I cluster or clip features returned for a bounding box?
      instructions:
      - text: Get features in layer {layer_id} inside bounding box {bbox}.
        slots:
          layer_id: path.layerId
          bbox: query.bbox
      - text: Return up to {limit} features in layer {layer_id} within bbox {bbox}, clipped.
        slots:
          limit: query.limit
          layer_id: path.layerId
          bbox: query.bbox
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/tile/{tileType}/{tileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get map features in a tile
      effect: read
      questions:
      - How do I load layer features for one map tile?
      - Which tile types can I request features by?
      instructions:
      - text: Get features in layer {layer_id} for {tile_type} tile {tile_id}.
        slots:
          layer_id: path.layerId
          tile_type: path.tileType
          tile_id: path.tileId
      - text: Load tile {tile_id} of type {tile_type} from layer {layer_id} with margin {margin}.
        slots:
          tile_id: path.tileId
          tile_type: path.tileType
          layer_id: path.layerId
          margin: query.margin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/spatial'].get
  update:
    x-apievangelist-phrasing:
      intent: Find map features within a radius of a point
      effect: read
      questions:
      - Which features are within 500 meters of a coordinate?
      - Can I search around an existing feature or an H3 cell instead of a lat/lng?
      instructions:
      - text: Find features in layer {layer_id} within {radius} meters of {lat},{lng}.
        slots:
          layer_id: path.layerId
          radius: query.radius
          lat: query.lat
          lng: query.lng
      - text: Find features in layer {layer_id} near H3 cell {h3_index}.
        slots:
          layer_id: path.layerId
          h3_index: query.h3Index
      - text: Search layer {layer_id} for features within {radius} of feature {ref_feature_id}.
        slots:
          layer_id: path.layerId
          radius: query.radius
          ref_feature_id: query.refFeatureId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/spatial'].post
  update:
    x-apievangelist-phrasing:
      intent: Find map features intersecting a posted geometry
      effect: read
      questions:
      - Can I send my own polygon and get back the features it intersects?
      - How do I query features against a custom geometry in the request body?
      instructions:
      - text: Find features in layer {layer_id} intersecting a {geometry_type} geometry I send.
        slots:
          layer_id: path.layerId
          geometry_type: requestBody.type
      - text: Return features in layer {layer_id} within {radius} of my posted {geometry_type} geometry.
        slots:
          layer_id: path.layerId
          radius: query.radius
          geometry_type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search a map layer's features by property
      effect: read
      questions:
      - Can I search features by their property values in a layer?
      - Are search results ordered or resumable?
      instructions:
      - text: Search layer {layer_id} for features matching {params}.
        slots:
          layer_id: path.layerId
          params: query.params
      - text: Search layer {layer_id} for features by author {author}.
        slots:
          layer_id: path.layerId
          author: query.author
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/iterate'].get
  update:
    x-apievangelist-phrasing:
      intent: Iterate through every feature in a layer
      effect: read
      questions:
      - How do I read every feature in a layer without duplicates?
      - Can I continue iterating a layer with a page token?
      instructions:
      - text: Iterate all features in layer {layer_id}.
        slots:
          layer_id: path.layerId
      - text: Continue iterating layer {layer_id} from page token {page_token}.
        slots:
          layer_id: path.layerId
          page_token: query.pageToken
      method: generated
      generated: '2026-09-26'