# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Traffic API v7 Real-Time Traffic API
  version: 1.0.0
extends: openapi/here-real-time-traffic-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['/flow'].get
  update:
    x-apievangelist-phrasing:
      intent: Get real-time traffic flow for an area
      effect: read
      questions:
      - How do I get live traffic speeds and jam factors for a city bounding box?
      - Can I return only heavily congested roads by setting a minimum jam factor?
      instructions:
      - text: Get real-time traffic flow in {in} using {locationReferencing} location referencing.
        slots:
          in: query.in
          locationReferencing: query.locationReferencing
      - text: Show roads in {in} with jam factor of at least {minJamFactor}, referenced as {locationReferencing}.
        slots:
          in: query.in
          minJamFactor: query.minJamFactor
          locationReferencing: query.locationReferencing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flow'].post
  update:
    x-apievangelist-phrasing:
      intent: Get traffic flow for a complex area via POST
      effect: read
      questions:
      - Can I send a long corridor or polygon in a POST body to get traffic flow?
      - What's the option for traffic flow queries whose geospatial filter is too big for a URL?
      instructions:
      - text: Post the large area filter {in} in the body and return live traffic flow for it.
        slots:
          in: requestBody.in
      - text: Fetch flow via the POST endpoint for corridor {in} limited to road classes {functionalClasses}.
        slots:
          in: requestBody.in
          functionalClasses: requestBody.functionalClasses
      method: generated
      generated: '2026-09-26'
- target: $.paths['/incidents'].get
  update:
    x-apievangelist-phrasing:
      intent: List traffic incidents in an area
      effect: read
      questions:
      - What accidents and road closures are happening right now in a given area?
      - Can I filter traffic incidents by criticality or incident type?
      - Which incidents in an area started after a certain time?
      instructions:
      - text: List traffic incidents in {in} with {locationReferencing} referencing.
        slots:
          in: query.in
          locationReferencing: query.locationReferencing
      - text: Show critical incidents of type {type} in {in} with criticality {criticality}, referenced as {locationReferencing}.
        slots:
          type: query.type
          in: query.in
          criticality: query.criticality
          locationReferencing: query.locationReferencing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/incidents'].post
  update:
    x-apievangelist-phrasing:
      intent: List traffic incidents for a large area via POST
      effect: read
      questions:
      - Is there a POST form of the incidents search for large polygons or corridors?
      - Can I put the incident search filters in a request body instead of query parameters?
      instructions:
      - text: Post the area {in} in the body and list the traffic incidents inside it.
        slots:
          in: requestBody.in
      - text: Search incidents via POST in corridor {in} for types {type} in language {lang}.
        slots:
          in: requestBody.in
          type: requestBody.type
          lang: requestBody.lang
      method: generated
      generated: '2026-09-26'
- target: $.paths['/incidents/{originalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a traffic incident by its ID
      effect: read
      questions:
      - How do I look up the current details of one traffic incident by its ID?
      - What namespace does an incident ID use if I don't prefix it?
      instructions:
      - text: Get traffic incident {originalId} with {locationReferencing} referencing.
        slots:
          originalId: path.originalId
          locationReferencing: query.locationReferencing
      - text: Show incident {originalId} described in language {lang}, referenced as {locationReferencing}.
        slots:
          originalId: path.originalId
          lang: query.lang
          locationReferencing: query.locationReferencing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/incidents/{originalId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a traffic incident by ID via POST
      effect: read
      questions:
      - Can I fetch a single incident by ID with the options in a POST body?
      - Is there a POST version of the incident-by-ID lookup?
      instructions:
      - text: Fetch incident {originalId} using the POST lookup with units {units}.
        slots:
          originalId: path.originalId
          units: requestBody.units
      - text: Post a lookup for incident {originalId} with body option location referencing {locationReferencing}.
        slots:
          originalId: path.originalId
          locationReferencing: requestBody.locationReferencing
      method: generated
      generated: '2026-09-26'