openapi: 3.0.3
info:
  title: ipify IP Geolocation API
  description: >-
    The ipify IP Geolocation API (geo.ipify.org) is the commercial counterpart to
    the free public IP API. It is operated by WhoisXML API and resolves an IPv4 or
    IPv6 address — or a domain or email — into a geolocation, ISP, Autonomous System
    (ASN), and reverse-DNS profile. Authentication uses an API key passed as the
    `apiKey` query parameter. Plans are credit-metered (Country = 1 credit,
    Country+City = 2, Country+City+VPN = 3).
  version: '2.0.0'
  contact:
    name: ipify Geolocation API
    url: https://geo.ipify.org/
  license:
    name: Commercial
    url: https://geo.ipify.org/
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
servers:
  - url: https://geo.ipify.org/api/v2
    description: Production IP Geolocation API.
  - url: https://geo.ipify.org
    description: Account / service root for non-versioned utility endpoints.
tags:
  - name: Geolocation
    description: Resolve an IP, domain, or email to a country, region, city, and ISP.
  - name: Account
    description: Account balance and credit utilities.
paths:
  /country:
    servers:
      - url: https://geo.ipify.org/api/v2
        description: Country-tier geolocation endpoint.
    get:
      operationId: getCountryLocation
      summary: ipify Get Country-Level Geolocation
      description: >-
        Look up an IP, domain, or email and return its country-level geolocation
        and ISP. Costs 1 credit per successful request.
      tags:
        - Geolocation
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/IpAddress'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Email'
        - $ref: '#/components/parameters/ReverseIp'
        - $ref: '#/components/parameters/EscapedUnicode'
      responses:
        '200':
          description: Geolocation payload (country level).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - ApiKeyQuery: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /country,city:
    servers:
      - url: https://geo.ipify.org/api/v2
        description: Country+City-tier geolocation endpoint.
    get:
      operationId: getCountryCityLocation
      summary: ipify Get Country and City Geolocation
      description: >-
        Look up an IP, domain, or email and return its full geolocation (country +
        region + city + postal code + lat/lng + timezone) plus ISP and AS details.
        Costs 2 credits per successful request.
      tags:
        - Geolocation
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/IpAddress'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Email'
        - $ref: '#/components/parameters/ReverseIp'
        - $ref: '#/components/parameters/EscapedUnicode'
      responses:
        '200':
          description: Geolocation payload (country + city level).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - ApiKeyQuery: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /country,city,vpn:
    servers:
      - url: https://geo.ipify.org/api/v2
        description: Country+City+VPN-tier geolocation endpoint (deprecated proxy block).
    get:
      operationId: getCountryCityVpnLocation
      summary: ipify Get Country, City, and VPN Geolocation
      description: >-
        Look up an IP, domain, or email and return full geolocation, ISP, AS, and a
        VPN/proxy-detection block. The `proxy` field is deprecated and always
        returns `false`. Costs 3 credits per successful request.
      tags:
        - Geolocation
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/IpAddress'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Email'
        - $ref: '#/components/parameters/ReverseIp'
        - $ref: '#/components/parameters/EscapedUnicode'
      responses:
        '200':
          description: Geolocation payload with deprecated VPN/proxy block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationVpnResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - ApiKeyQuery: []
      deprecated: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /service/account-balance:
    servers:
      - url: https://geo.ipify.org
        description: Service utility endpoint root.
    get:
      operationId: getAccountBalance
      summary: ipify Get Account Balance
      description: >-
        Return the remaining credit balance on the API key for the IP Geolocation
        product line.
      tags:
        - Account
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Current credit balance for the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyQuery: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: >-
        Personal API key issued by WhoisXML API for the ipify Geolocation product.
        Passed as the `apiKey` query parameter on every request.
  parameters:
    ApiKey:
      name: apiKey
      in: query
      required: true
      description: Personal API key for the ipify Geolocation product.
      schema:
        type: string
      example: at_DEMO_KEY_REDACTED
    IpAddress:
      name: ipAddress
      in: query
      required: false
      description: >-
        IPv4 or IPv6 address to look up. Defaults to the requester's IP when
        omitted and no `domain`/`email` is supplied.
      schema:
        type: string
      example: 8.8.8.8
    Domain:
      name: domain
      in: query
      required: false
      description: Domain name whose A/AAAA record should be resolved and looked up.
      schema:
        type: string
        format: hostname
      example: example.com
    Email:
      name: email
      in: query
      required: false
      description: Email address whose MX server IP should be looked up.
      schema:
        type: string
        format: email
      example: user@example.com
    ReverseIp:
      name: reverseIp
      in: query
      required: false
      description: When `1`, include up to five reverse-DNS associated domains in the response.
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      example: 1
    EscapedUnicode:
      name: escapedUnicode
      in: query
      required: false
      description: When `1`, leave Unicode characters in escaped form rather than decoding them.
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      example: 0
  responses:
    BadRequest:
      description: Missing or invalid required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient credits or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Invalid request parameter values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded — the service caps callers at 100 requests per second.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    GeolocationResponse:
      type: object
      description: Geolocation, ISP, and AS lookup result for an IP, domain, or email.
      required:
        - ip
        - location
      properties:
        ip:
          type: string
          description: The resolved IPv4 or IPv6 address the result describes.
          example: 8.8.8.8
        isp:
          type: string
          description: Name of the Internet Service Provider that owns the IP.
          example: Google LLC
        location:
          $ref: '#/components/schemas/Location'
        as:
          $ref: '#/components/schemas/AutonomousSystem'
        domains:
          type: array
          description: Up to five reverse-DNS associated domains (only when `reverseIp=1`).
          items:
            type: string
            format: hostname
          example:
            - dns.google
            - 8.8.8.8.in-addr.arpa
    GeolocationVpnResponse:
      type: object
      description: Geolocation result including the deprecated VPN/proxy block.
      required:
        - ip
        - location
      properties:
        ip:
          type: string
          description: The resolved IPv4 or IPv6 address.
          example: 8.8.8.8
        isp:
          type: string
          description: ISP name.
          example: Google LLC
        location:
          $ref: '#/components/schemas/Location'
        as:
          $ref: '#/components/schemas/AutonomousSystem'
        domains:
          type: array
          items:
            type: string
            format: hostname
        proxy:
          $ref: '#/components/schemas/ProxyBlock'
    Location:
      type: object
      description: Country + region + city + postal code + lat/lng + timezone block.
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: US
        region:
          type: string
          description: Region, state, or province name.
          example: California
        city:
          type: string
          description: City name (Country+City plans only).
          example: Mountain View
        lat:
          type: number
          format: double
          description: Latitude in decimal degrees.
          example: 37.40599
        lng:
          type: number
          format: double
          description: Longitude in decimal degrees.
          example: -122.078514
        postalCode:
          type: string
          description: Postal code for the location.
          example: '94043'
        timezone:
          type: string
          description: UTC offset for the location, formatted like `+10:00`.
          example: '-07:00'
        geonameId:
          type: integer
          format: int64
          description: GeoNames database identifier for the location.
          example: 5375480
    AutonomousSystem:
      type: object
      description: Autonomous System (AS) profile for the IP.
      properties:
        asn:
          type: integer
          format: int64
          description: Autonomous System Number.
          example: 15169
        name:
          type: string
          description: AS organization name.
          example: GOOGLE
        route:
          type: string
          description: Announced route in CIDR notation.
          example: 8.8.8.0/24
        domain:
          type: string
          description: AS organization website.
          example: https://about.google/
        type:
          type: string
          description: AS classification (e.g. `Content`, `Hosting`, `ISP`).
          example: Content
    ProxyBlock:
      type: object
      deprecated: true
      description: Deprecated proxy/VPN detection block — always returns `false`.
      properties:
        proxy:
          type: boolean
          example: false
        vpn:
          type: boolean
          example: false
        tor:
          type: boolean
          example: false
    AccountBalanceResponse:
      type: object
      description: Remaining credit balance for the API key.
      properties:
        credits:
          type: integer
          format: int64
          description: Remaining credits available for IP Geolocation requests.
          example: 9876
    ErrorResponse:
      type: object
      description: Generic error envelope returned for non-2xx responses.
      properties:
        messages:
          type: string
          description: Human-readable error message describing what went wrong.
          example: Missing apiKey parameter.
        code:
          type: integer
          description: Provider-specific numeric error code.
          example: 401