Google Maps Directions API — Directions

naftiko: 1.0.0-alpha2
info:
  label: Google Maps Directions API — Directions
  description: 'Google Maps Directions API — Directions. 1 operations. Lead operation: Get Directions Between Two or More
    Locations. Self-contained Naftiko capability covering one Google Maps business surface.'
  tags:
  - Google Maps
  - Directions
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    GOOGLE_MAPS_API_KEY: GOOGLE_MAPS_API_KEY
capability:
  consumes:
  - type: http
    namespace: directions-directions
    baseUri: https://maps.googleapis.com/maps/api
    description: Google Maps Directions API — Directions business capability. Self-contained, no shared references.
    resources:
    - name: directions-json
      path: /directions/json
      operations:
      - name: getdirections
        method: GET
        description: Get Directions Between Two or More Locations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: origin
          in: query
          type: string
          description: The address, place ID (prefixed with place_id:), or latitude/longitude coordinates of the starting
            point.
          required: true
        - name: destination
          in: query
          type: string
          description: The address, place ID (prefixed with place_id:), or latitude/longitude coordinates of the ending point.
          required: true
        - name: mode
          in: query
          type: string
          description: The travel mode for calculating directions. Defaults to driving.
        - name: waypoints
          in: query
          type: string
          description: 'An array of intermediate locations to include along the route, specified as pipe-separated values.
            Prefix with optimize:true to allow the Directions service to '
        - name: alternatives
          in: query
          type: boolean
          description: If set to true, instructs the Directions service to return more than one route alternative when available.
        - name: avoid
          in: query
          type: string
          description: Indicates that the calculated route(s) should avoid the indicated features. Pipe-separated list of
            restrictions.
        - name: language
          in: query
          type: string
          description: The language code in which to return results, where available.
        - name: units
          in: query
          type: string
          description: Specifies the unit system to use when displaying results.
        - name: region
          in: query
          type: string
          description: The region code, specified as a ccTLD two-character value. Biases results towards a particular region.
        - name: arrival_time
          in: query
          type: integer
          description: The desired arrival time for transit directions, specified as seconds since midnight, January 1, 1970
            UTC. Cannot be used with departure_time.
        - name: departure_time
          in: query
          type: string
          description: The desired departure time, specified as seconds since midnight, January 1, 1970 UTC. For transit mode
            this is required if arrival_time is not specified. For dr
        - name: traffic_model
          in: query
          type: string
          description: The assumptions to use when calculating travel time in traffic. Only applies when mode is driving and
            departure_time is specified.
        - name: transit_mode
          in: query
          type: string
          description: Specifies one or more preferred modes of transit as a pipe-separated list. Only valid when mode is
            transit.
        - name: transit_routing_preference
          in: query
          type: string
          description: Specifies preferences for transit routes. Only valid when mode is transit.
        - name: key
          in: query
          type: string
          description: Your application's API key.
          required: true
    authentication:
      type: apikey
      key: key
      value: '{{env.GOOGLE_MAPS_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: directions-directions-rest
    port: 8080
    description: REST adapter for Google Maps Directions API — Directions. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/directions/json
      name: directions-json
      description: REST surface for directions-json.
      operations:
      - method: GET
        name: getdirections
        description: Get Directions Between Two or More Locations
        call: directions-directions.getdirections
        with:
          origin: rest.origin
          destination: rest.destination
          mode: rest.mode
          waypoints: rest.waypoints
          alternatives: rest.alternatives
          avoid: rest.avoid
          language: rest.language
          units: rest.units
          region: rest.region
          arrival_time: rest.arrival_time
          departure_time: rest.departure_time
          traffic_model: rest.traffic_model
          transit_mode: rest.transit_mode
          transit_routing_preference: rest.transit_routing_preference
          key: rest.key
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: directions-directions-mcp
    port: 9090
    transport: http
    description: MCP adapter for Google Maps Directions API — Directions. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: get-directions-between-two-more
      description: Get Directions Between Two or More Locations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: directions-directions.getdirections
      with:
        origin: tools.origin
        destination: tools.destination
        mode: tools.mode
        waypoints: tools.waypoints
        alternatives: tools.alternatives
        avoid: tools.avoid
        language: tools.language
        units: tools.units
        region: tools.region
        arrival_time: tools.arrival_time
        departure_time: tools.departure_time
        traffic_model: tools.traffic_model
        transit_mode: tools.transit_mode
        transit_routing_preference: tools.transit_routing_preference
        key: tools.key
      outputParameters:
      - type: object
        mapping: $.