Google Maps Geocoding API — Geocoding

naftiko: 1.0.0-alpha2
info:
  label: Google Maps Geocoding API — Geocoding
  description: 'Google Maps Geocoding API — Geocoding. 1 operations. Lead operation: Geocode an Address or Reverse Geocode
    Coordinates. Self-contained Naftiko capability covering one Google Maps business surface.'
  tags:
  - Google Maps
  - Geocoding
  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: geocoding-geocoding
    baseUri: https://maps.googleapis.com/maps/api
    description: Google Maps Geocoding API — Geocoding business capability. Self-contained, no shared references.
    resources:
    - name: geocode-json
      path: /geocode/json
      operations:
      - name: geocode
        method: GET
        description: Geocode an Address or Reverse Geocode Coordinates
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: address
          in: query
          type: string
          description: The street address or plus code to geocode. Specify addresses in accordance with the format used by
            the national postal service of the country concerned. Additi
        - name: latlng
          in: query
          type: string
          description: The latitude and longitude values for reverse geocoding, specified as a comma-separated string (e.g.,
            40.714224,-73.961452).
        - name: place_id
          in: query
          type: string
          description: The place ID of the place for which to obtain the human-readable address. The place ID uniquely identifies
            a place in the Google Places database and on Google M
        - name: components
          in: query
          type: string
          description: A component filter for which to obtain a geocode, specified as a pipe-separated list of component:value
            pairs. Components can be used to filter results to a par
        - name: bounds
          in: query
          type: string
          description: The bounding box of the viewport within which to bias geocode results more prominently. Specified as
            pipe-separated southwest and northeast coordinates (lat,lng
        - name: region
          in: query
          type: string
          description: The region code, specified as a ccTLD two-character value. This parameter biases results towards a
            particular region.
        - name: language
          in: query
          type: string
          description: The language in which to return results. If not supplied, the geocoder attempts to use the preferred
            language as specified in the Accept-Language header, or the
        - name: result_type
          in: query
          type: string
          description: A pipe-separated list of one or more address types. Used for reverse geocoding to filter results by
            address type (e.g., street_address, route, intersection, pol
        - name: location_type
          in: query
          type: string
          description: 'A pipe-separated list of one or more location types. Used for reverse geocoding to filter results
            by location type. Values include ROOFTOP, RANGE_INTERPOLATED, '
        - name: key
          in: query
          type: string
          description: Your application's API key. This key identifies your application for purposes of quota management.
          required: true
    authentication:
      type: apikey
      key: key
      value: '{{env.GOOGLE_MAPS_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: geocoding-geocoding-rest
    port: 8080
    description: REST adapter for Google Maps Geocoding API — Geocoding. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/geocode/json
      name: geocode-json
      description: REST surface for geocode-json.
      operations:
      - method: GET
        name: geocode
        description: Geocode an Address or Reverse Geocode Coordinates
        call: geocoding-geocoding.geocode
        with:
          address: rest.address
          latlng: rest.latlng
          place_id: rest.place_id
          components: rest.components
          bounds: rest.bounds
          region: rest.region
          language: rest.language
          result_type: rest.result_type
          location_type: rest.location_type
          key: rest.key
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: geocoding-geocoding-mcp
    port: 9090
    transport: http
    description: MCP adapter for Google Maps Geocoding API — Geocoding. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: geocode-address-reverse-geocode-coordinates
      description: Geocode an Address or Reverse Geocode Coordinates
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: geocoding-geocoding.geocode
      with:
        address: tools.address
        latlng: tools.latlng
        place_id: tools.place_id
        components: tools.components
        bounds: tools.bounds
        region: tools.region
        language: tools.language
        result_type: tools.result_type
        location_type: tools.location_type
        key: tools.key
      outputParameters:
      - type: object
        mapping: $.