IP Geolocation
==============

Geolocate IPv4 and IPv6 addresses to country, city, ISP, and detect VPNs,
proxies, and Tor exit nodes.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-geolocate-ip
---------------------

Geolocate an IP address using MaxMind databases. Returns country, continent,
city, ISP, network, and security information including VPN detection, proxy
status, and Tor exit node identification.

**Credit cost:** 5 credits per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``ip``
     - string
     - yes
     - IPv4 or IPv6 address to geolocate.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-geolocate-ip",
     "arguments": {
       "ip": "8.8.8.8"
     }
   }

Response:

.. code-block:: json

   {
     "ip": "8.8.8.8",
     "ip_version": 4,
     "country": {
       "iso_code": "US",
       "name": "United States"
     },
     "continent": {
       "code": "NA",
       "name": "North America"
     },
     "city": {
       "name": null,
       "postal_code": null
     },
     "location": {
       "latitude": 37.751,
       "longitude": -97.822,
       "accuracy_radius": 1000,
       "timezone": "America/Chicago"
     },
     "isp": {
       "name": "Google LLC",
       "organization": "Google LLC",
       "asn": 15169,
       "network": "8.8.8.0/24"
     },
     "security": {
       "is_vpn": false,
       "is_proxy": false,
       "is_tor_exit_node": false,
       "is_hosting": true
     }
   }

Errors
^^^^^^

- **Invalid IP address** -- malformed or unparseable IP strings are rejected.
  Both IPv4 (``192.168.1.1``) and IPv6 (``2001:4860:4860::8888``) formats are
  accepted.
- **Private / reserved IP** -- addresses in private ranges (``10.x.x.x``,
  ``192.168.x.x``, ``::1``, etc.) cannot be geolocated and return an error.