ipify IP Geolocation API — Geolocation

naftiko: "1.0.0-alpha2"

info:
  label: "ipify IP Geolocation API — Geolocation"
  description: >-
    Geolocation — Geolocation. 3 operations. Lead operation: ipify Get Country-Level Geolocation.
    Self-contained Naftiko capability covering one ipify business surface.
  tags:
    - Ipify
    - Geolocation
    - IP Intelligence
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      IPIFY_API_KEY: IPIFY_API_KEY

capability:

  consumes:
    - type: http
      namespace: "geolocation-api-geolocation"
      baseUri: "https://geo.ipify.org/api/v2"
      description: "ipify IP Geolocation API — Geolocation business capability. Self-contained, no shared references."
      authentication:
        type: apikey
        key: apiKey
        value: "{{env.IPIFY_API_KEY}}"
        placement: query
      resources:
        - name: "country"
          path: "/country"
          operations:
            - name: "getCountryLocation"
              method: GET
              description: "Look up an IP, domain, or email and return country-level geolocation and ISP. Costs 1 credit."
              inputParameters:
                - name: "ipAddress"
                  in: query
                  type: string
                  required: false
                  description: "IPv4 or IPv6 address to look up."
                - name: "domain"
                  in: query
                  type: string
                  required: false
                  description: "Domain name to resolve and look up."
                - name: "email"
                  in: query
                  type: string
                  required: false
                  description: "Email address whose MX server IP should be looked up."
                - name: "reverseIp"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, include up to five reverse-DNS associated domains."
                - name: "escapedUnicode"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, leave Unicode characters escaped."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "country-city"
          path: "/country,city"
          operations:
            - name: "getCountryCityLocation"
              method: GET
              description: "Look up an IP, domain, or email and return full country+city geolocation. Costs 2 credits."
              inputParameters:
                - name: "ipAddress"
                  in: query
                  type: string
                  required: false
                  description: "IPv4 or IPv6 address to look up."
                - name: "domain"
                  in: query
                  type: string
                  required: false
                  description: "Domain name to resolve and look up."
                - name: "email"
                  in: query
                  type: string
                  required: false
                  description: "Email address whose MX server IP should be looked up."
                - name: "reverseIp"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, include up to five reverse-DNS associated domains."
                - name: "escapedUnicode"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, leave Unicode characters escaped."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "country-city-vpn"
          path: "/country,city,vpn"
          operations:
            - name: "getCountryCityVpnLocation"
              method: GET
              description: "Look up an IP, domain, or email and return full geolocation plus deprecated VPN/proxy block. Costs 3 credits."
              inputParameters:
                - name: "ipAddress"
                  in: query
                  type: string
                  required: false
                  description: "IPv4 or IPv6 address to look up."
                - name: "domain"
                  in: query
                  type: string
                  required: false
                  description: "Domain name to resolve and look up."
                - name: "email"
                  in: query
                  type: string
                  required: false
                  description: "Email address whose MX server IP should be looked up."
                - name: "reverseIp"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, include up to five reverse-DNS associated domains."
                - name: "escapedUnicode"
                  in: query
                  type: integer
                  required: false
                  description: "When 1, leave Unicode characters escaped."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "geolocation-api-geolocation-rest"
      port: 8080
      description: "REST adapter for ipify IP Geolocation API — Geolocation. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/locations/country"
          name: "country-location"
          description: "REST surface for country-level geolocation lookups."
          operations:
            - method: GET
              name: "getCountryLocation"
              description: "Look up an IP, domain, or email and return country-level geolocation and ISP."
              call: "geolocation-api-geolocation.getCountryLocation"
              with:
                "ipAddress": "rest.ipAddress"
                "domain": "rest.domain"
                "email": "rest.email"
                "reverseIp": "rest.reverseIp"
                "escapedUnicode": "rest.escapedUnicode"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/locations/country-city"
          name: "country-city-location"
          description: "REST surface for country+city geolocation lookups."
          operations:
            - method: GET
              name: "getCountryCityLocation"
              description: "Look up an IP, domain, or email and return full country+city geolocation."
              call: "geolocation-api-geolocation.getCountryCityLocation"
              with:
                "ipAddress": "rest.ipAddress"
                "domain": "rest.domain"
                "email": "rest.email"
                "reverseIp": "rest.reverseIp"
                "escapedUnicode": "rest.escapedUnicode"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/locations/country-city-vpn"
          name: "country-city-vpn-location"
          description: "REST surface for full geolocation including the deprecated VPN/proxy block."
          operations:
            - method: GET
              name: "getCountryCityVpnLocation"
              description: "Look up an IP, domain, or email and return full geolocation plus deprecated VPN/proxy block."
              call: "geolocation-api-geolocation.getCountryCityVpnLocation"
              with:
                "ipAddress": "rest.ipAddress"
                "domain": "rest.domain"
                "email": "rest.email"
                "reverseIp": "rest.reverseIp"
                "escapedUnicode": "rest.escapedUnicode"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "geolocation-api-geolocation-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for ipify IP Geolocation API — Geolocation. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "lookup-country-location"
          description: "Look up an IP, domain, or email and return country-level geolocation and ISP."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "geolocation-api-geolocation.getCountryLocation"
          with:
            "ipAddress": "tools.ipAddress"
            "domain": "tools.domain"
            "email": "tools.email"
            "reverseIp": "tools.reverseIp"
            "escapedUnicode": "tools.escapedUnicode"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "lookup-country-city-location"
          description: "Look up an IP, domain, or email and return full country+city geolocation."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "geolocation-api-geolocation.getCountryCityLocation"
          with:
            "ipAddress": "tools.ipAddress"
            "domain": "tools.domain"
            "email": "tools.email"
            "reverseIp": "tools.reverseIp"
            "escapedUnicode": "tools.escapedUnicode"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "lookup-country-city-vpn-location"
          description: "Look up an IP, domain, or email and return full geolocation plus deprecated VPN/proxy block."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "geolocation-api-geolocation.getCountryCityVpnLocation"
          with:
            "ipAddress": "tools.ipAddress"
            "domain": "tools.domain"
            "email": "tools.email"
            "reverseIp": "tools.reverseIp"
            "escapedUnicode": "tools.escapedUnicode"
          outputParameters:
            - type: object
              mapping: "$."