# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Here Routing API
  version: 1.0.0
extends: openapi/here-routing-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: 5
- target: $.paths['/routes'].get
  update:
    x-apievangelist-phrasing:
      intent: Plan a public transit trip
      effect: read
      questions:
      - How do I find a bus or train connection between two coordinates for a given departure time?
      - Can I limit a transit route to rail and metro only?
      - Is there a way to request only wheelchair-accessible transit routes?
      instructions:
      - text: Find public transit routes from {origin} to {destination} leaving at {departureTime}.
        slots:
          origin: query.origin
          destination: query.destination
          departureTime: query.departureTime
      - text: Plan a transit trip from {origin} to {destination} using only {modes} with at most {changes} transfers.
        slots:
          origin: query.origin
          destination: query.destination
          modes: query.modes
          changes: query.changes
      - text: Get transit connections from {origin} to {destination} arriving by {arrivalTime}.
        slots:
          origin: query.origin
          destination: query.destination
          arrivalTime: query.arrivalTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/routes'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate a car, truck or walking route
      effect: read
      questions:
      - How do I calculate a driving route while avoiding a long list of areas I can't fit in the URL?
      - Can I get a truck route that avoids tolls and specific road features?
      - What does it take to compute an EV route with consumption data?
      instructions:
      - text: Calculate a {transportMode} route from {origin} to {destination}, avoiding {avoid}.
        slots:
          transportMode: query.transportMode
          origin: query.origin
          destination: query.destination
          avoid: requestBody.avoid
      - text: Route a {transportMode} from {origin} to {destination} and give me {alternatives} alternatives.
        slots:
          transportMode: query.transportMode
          origin: query.origin
          destination: query.destination
          alternatives: query.alternatives
      - text: Compute an electric {transportMode} route from {origin} to {destination} with EV settings {ev}.
        slots:
          origin: query.origin
          destination: query.destination
          ev: requestBody.ev
          transportMode: query.transportMode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/routes/{routeHandle}'].get
  update:
    x-apievangelist-phrasing:
      intent: Recall a calculated route from its handle
      effect: read
      questions:
      - How do I get a previously calculated route back from its route handle?
      - Can I reroute from my current position using a route handle?
      - Is a route handle safe to store long term?
      instructions:
      - text: Decode route handle {routeHandle} for {transportMode}.
        slots:
          routeHandle: path.routeHandle
          transportMode: query.transportMode
      - text: Reload route {routeHandle} as a {transportMode} route starting from my current position {origin}.
        slots:
          routeHandle: path.routeHandle
          transportMode: query.transportMode
          origin: query.origin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/routes/{routeHandle}'].post
  update:
    x-apievangelist-phrasing:
      intent: Recall a route handle with a POST body
      effect: read
      questions:
      - How do I decode a route handle when my avoid-areas list is too long for the query string?
      - Can I send exclusions in the request body when restoring a route from its handle?
      instructions:
      - text: Decode route handle {routeHandle} via POST for {transportMode}, avoiding {avoid} in the body.
        slots:
          routeHandle: path.routeHandle
          transportMode: query.transportMode
          avoid: requestBody.avoid
      - text: Restore route {routeHandle} by POST with body exclusions {exclude} for a {transportMode}.
        slots:
          routeHandle: path.routeHandle
          exclude: requestBody.exclude
          transportMode: query.transportMode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Build a route from a GPS trace
      effect: read
      questions:
      - How do I turn a recorded GPS track into a route with travel time and distance?
      - What trace point density gives the best results when importing a route?
      instructions:
      - text: Create a {transportMode} route from GPS trace {trace}.
        slots:
          transportMode: query.transportMode
          trace: requestBody.trace
      - text: Match trace points {trace} to roads and return a {transportMode} route.
        slots:
          trace: requestBody.trace
          transportMode: query.transportMode
      method: generated
      generated: '2026-09-26'