Trimble Maps API — Routing

naftiko: 1.0.0-alpha2
info:
  label: Trimble Maps API — Routing
  description: 'Trimble Maps API — Routing. 2 operations. Lead operation: Get mileage between stops. Self-contained Naftiko
    capability covering one Trimble business surface.'
  tags:
  - Trimble
  - Routing
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TRIMBLE_API_KEY: TRIMBLE_API_KEY
capability:
  consumes:
  - type: http
    namespace: maps-routing
    baseUri: https://pcmiler.alk.com/apis/rest/v1.0
    description: Trimble Maps API — Routing business capability. Self-contained, no shared references.
    resources:
    - name: Service.svc-mileage
      path: /Service.svc/mileage
      operations:
      - name: getmileage
        method: GET
        description: Get mileage between stops
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: stops
          in: query
          type: string
          required: true
        - name: vehicleType
          in: query
          type: string
        - name: routeType
          in: query
          type: string
        - name: outputFormat
          in: query
          type: string
    - name: Service.svc-route
      path: /Service.svc/route
      operations:
      - name: calculateroute
        method: GET
        description: Calculate a route between stops
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: stops
          in: query
          type: string
          description: 'Semicolon-delimited list of stops in "City,State" or lat/lng format. Example: "Dallas,TX;Chicago,IL;Detroit,MI"'
          required: true
        - name: vehicleType
          in: query
          type: string
        - name: routeType
          in: query
          type: string
          description: Routing optimization type
        - name: height
          in: query
          type: number
          description: Vehicle height in feet
        - name: weight
          in: query
          type: number
          description: Vehicle weight in pounds
        - name: length
          in: query
          type: number
          description: Vehicle length in feet
        - name: hazmat
          in: query
          type: string
        - name: reportType
          in: query
          type: string
        - name: outputFormat
          in: query
          type: string
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.TRIMBLE_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: maps-routing-rest
    port: 8080
    description: REST adapter for Trimble Maps API — Routing. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/service-svc/mileage
      name: service-svc-mileage
      description: REST surface for Service.svc-mileage.
      operations:
      - method: GET
        name: getmileage
        description: Get mileage between stops
        call: maps-routing.getmileage
        with:
          stops: rest.stops
          vehicleType: rest.vehicleType
          routeType: rest.routeType
          outputFormat: rest.outputFormat
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/service-svc/route
      name: service-svc-route
      description: REST surface for Service.svc-route.
      operations:
      - method: GET
        name: calculateroute
        description: Calculate a route between stops
        call: maps-routing.calculateroute
        with:
          stops: rest.stops
          vehicleType: rest.vehicleType
          routeType: rest.routeType
          height: rest.height
          weight: rest.weight
          length: rest.length
          hazmat: rest.hazmat
          reportType: rest.reportType
          outputFormat: rest.outputFormat
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: maps-routing-mcp
    port: 9090
    transport: http
    description: MCP adapter for Trimble Maps API — Routing. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: get-mileage-between-stops
      description: Get mileage between stops
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: maps-routing.getmileage
      with:
        stops: tools.stops
        vehicleType: tools.vehicleType
        routeType: tools.routeType
        outputFormat: tools.outputFormat
      outputParameters:
      - type: object
        mapping: $.
    - name: calculate-route-between-stops
      description: Calculate a route between stops
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: maps-routing.calculateroute
      with:
        stops: tools.stops
        vehicleType: tools.vehicleType
        routeType: tools.routeType
        height: tools.height
        weight: tools.weight
        length: tools.length
        hazmat: tools.hazmat
        reportType: tools.reportType
        outputFormat: tools.outputFormat
      outputParameters:
      - type: object
        mapping: $.