Geoapify Forward Geocoding API

naftiko: 1.0.0-alpha2
info:
  label: Geoapify Forward Geocoding API
  description: 'Geoapify Forward Geocoding API. 1 operations. Lead operation: Forward Geocoding. Self-contained Naftiko capability
    covering one Geoapify business surface.'
  tags:
  - Geoapify
  - Geoapify Forward Geocoding API
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    GEOAPIFY_API_KEY: GEOAPIFY_API_KEY
capability:
  consumes:
  - type: http
    namespace: forward-geocoding
    baseUri: https://api.geoapify.com/v1
    description: Geoapify Forward Geocoding API business capability. Self-contained, no shared references.
    resources:
    - name: geocode-search
      path: /geocode/search
      operations:
      - name: get
        method: GET
        description: Forward Geocoding
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: apiKey
          in: query
          type: string
          description: Your API key for accessing the Geoapify API.
          required: true
        - name: text
          in: query
          type: string
          description: Free-form address input.
        - name: name
          in: query
          type: string
          description: Amenity or place name as part of a structured address.
        - name: housenumber
          in: query
          type: string
          description: House number for a structured address.
        - name: street
          in: query
          type: string
          description: Street name for a structured address.
        - name: postcode
          in: query
          type: string
          description: Postal code or ZIP code.
        - name: city
          in: query
          type: string
          description: City name.
        - name: state
          in: query
          type: string
          description: State name.
        - name: country
          in: query
          type: string
          description: Country name.
        - name: type
          in: query
          type: string
          description: Location type filter to narrow down search by type.
        - name: lang
          in: query
          type: string
          description: Language code for the response (2-character ISO 639-1).
        - name: limit
          in: query
          type: integer
          description: Maximum number of results to return.
        - name: filter
          in: query
          type: string
          description: Filter results by location constraints (e.g., country, boundary).
        - name: bias
          in: query
          type: string
          description: Location bias to prioritize search results by proximity or area.
        - name: format
          in: query
          type: string
          description: Response format.
  exposes:
  - type: rest
    namespace: forward-geocoding-rest
    port: 8080
    description: REST adapter for Geoapify Forward Geocoding API. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/geocode/search
      name: geocode-search
      description: REST surface for geocode-search.
      operations:
      - method: GET
        name: get
        description: Forward Geocoding
        call: forward-geocoding.get
        with:
          apiKey: rest.apiKey
          text: rest.text
          name: rest.name
          housenumber: rest.housenumber
          street: rest.street
          postcode: rest.postcode
          city: rest.city
          state: rest.state
          country: rest.country
          type: rest.type
          lang: rest.lang
          limit: rest.limit
          filter: rest.filter
          bias: rest.bias
          format: rest.format
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: forward-geocoding-mcp
    port: 9090
    transport: http
    description: MCP adapter for Geoapify Forward Geocoding API. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: forward-geocoding
      description: Forward Geocoding
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: forward-geocoding.get
      with:
        apiKey: tools.apiKey
        text: tools.text
        name: tools.name
        housenumber: tools.housenumber
        street: tools.street
        postcode: tools.postcode
        city: tools.city
        state: tools.state
        country: tools.country
        type: tools.type
        lang: tools.lang
        limit: tools.limit
        filter: tools.filter
        bias: tools.bias
        format: tools.format
      outputParameters:
      - type: object
        mapping: $.