ipify Geolocation API

openapi: 3.0.3
info:
  title: ipify IP Account 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.
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
components:
  responses:
    Forbidden:
      description: Insufficient credits or revoked API key.
      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'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Invalid request parameter values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Missing or invalid required fields.
      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
    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
    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'
    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
  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
    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
    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
    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
  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.