> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greip.io/llms.txt
> Use this file to discover all available pages before exploring further.

# IP Geolocation

> This API allows you to retrieve detailed geolocation information for a visitor’s or user’s IP address.

By using the IP Geolocation method, you can access data such as the user’s country, city, ISP, and more, enabling you to personalize user experiences, enhance security, and make data-driven decisions based on geographic insights.

export const MCPCallout = () => {
  return <div class="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-[rgba(192, 132, 252, 0.2)] bg-[rgba(192, 132, 252, 0.1)] dark:border-[#c084fc4d] dark:bg-[#c084fc1a] text-[#6005BB] dark:text-[#FFFFFF]" data-callout-type="callout">
      <div class="mt-0.5 w-4" data-component-part="callout-icon">
        <svg class="h-4 w-4 !m-0 shrink-0 bg-[#c084fc] [mask-image:url('https://d3gk2c5xim1je2.cloudfront.net/v7.1.0/duotone/fire.svg')] [-webkit-mask-image:url('https://d3gk2c5xim1je2.cloudfront.net/v7.1.0/duotone/fire.svg')] [mask-repeat:no-repeat] [-webkit-mask-repeat:no-repeat] [mask-position:center] [-webkit-mask-position:center]"></svg>
      </div>
      <div class="text-sm prose dark:prose-invert min-w-0 w-full [&_kbd]:bg-background-light dark:[&_kbd]:bg-background-dark text-[#6005BB] dark:text-[#FFFFFF]" data-component-part="callout-content">
        <span data-as="p">
          Want to skip the docs? Use the{" "}
          <a class="link mint-text-xs border-[#C792FC]" href="/docs-mcp-server">
            <b>MCP Server</b>
          </a>
        </span>
      </div>
    </div>;
};

export const Availability = ({plan, color}) => {
  const colorMap = {
    green: "text-green-700 dark:text-green-400",
    blue: "text-blue-700 dark:text-blue-400",
    purple: "text-purple-700 dark:text-purple-400"
  };
  return <div dir="ltr" data-orientation="horizontal" class="p-4 px-5 mt-0 md:mt-4 flex flex-col sm:flex-row flex-wrap gap-2 relative overflow-hidden rounded-2xl border border-gray-950/10 dark:border-white/10 my-0 bg-gray-50 dark:bg-white/5 dark:codeblock-dark text-gray-950 dark:text-gray-50 codeblock-light text-sm prose prose-gray dark:prose-invert font-semibold no-wrap-words">
      Endpoint availability:{" "}
      <span class={` ${colorMap[color]} flex-1`}>{plan}</span>
      <a class="custom-link text-xs" href="https://greip.io/detailed-pricing">
        Learn more
      </a>
    </div>;
};

## Authentication

Include your API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer <api_key>
```

API v2 accepts the key only in this header, not in query parameters or request bodies. See [Authentication](/authentication).

`GET /geo/ip` resolves the IP address of the current request and returns the same rich `data` object as [IP Lookup](/api-reference/v2/endpoint/data-lookup/ip) (geo, optional modules, and related fields). To look up a different address, use the IP in the path on `GET /lookup/ip/{ip}`, not a query parameter.

### Query parameters

<ParamField query="params" type="string" placeholder="The modules you want to use">
  The params command can be used to specify the required modules you want to get in the response.

  Expected values: `security`, `currency`, `timezone`, `location`, and/or `device`

  Sample value: `security,timezone,currency`

  For more information please refer to [Customize response modules](/options/customize-modules).
</ParamField>

<ParamField query="lang" type="string" default="EN" placeholder="Response language">
  The lang command is used to get a response in a specific language.

  Expected values: `EN`, `AR`, `DE`, `FR`, `ES`, `JA`, `ZH`, or `RU`

  For more information please refer to [Localization](/options/localization).
</ParamField>

<ParamField query="callback" type="string" placeholder="JSONP callback">
  The callback command can help you make the response a JSONP format.

  Expected values: any name that can be used as a function name in Javascript, e.g: `myFunctionName`.

  For more information please refer to [JSONP callback](/options/jsonp-callback).
</ParamField>

<ParamField query="format" type="string" default="JSON" placeholder="Response format">
  The format command is used to get a response in a specific format.

  Expected values: `JSON`, `XML`, `CSV`, or `Newline`

  For more information please refer to [Response format](/options/response-format).
</ParamField>

<ParamField query="mode" type="string" default="live" placeholder="Environment">
  The mode command is used in the development stage to simulate the integration process before releasing it to the production environment.

  Expected values: `live`, or `test`.

  For more information please refer to [Development environment](/options/development-environment).
</ParamField>

<ParamField query="source" type="string" placeholder="Integration label">
  Optional label for your own analytics or support correlation (for example a product or channel name).
</ParamField>

<ParamField query="user_id" type="string" placeholder="User identifier">
  The user\_id command can be used to identify requests sent by specific users to monitor in the [Events page](/knowledge-base/events-and-alerts/overview).

  Expected values: email address, phone number, user id, name, etc.

  For more information please refer to [User identifier](/options/user-identifier).
</ParamField>

<Panel>
  <MCPCallout />

  <Availability plan="Standard and above" color="green" />

  <ResponseExample>
    ```json Success theme={null}
    {
      "success": true,
      "data": {
        "ip": {
          "address": "165.227.149.217",
          "version": 4,
          "numeric": 2783155673,
          "bogon": false
        },
        "geo": {
          "continent": "Europe",
          "continent_code": "EU",
          "continent_geo_name_id": 6255148,
          "country": "Germany",
          "country_code": "DE",
          "country_geo_name_id": 2921044,
          "region": "Hessen",
          "city": "Frankfurt am Main",
          "postal": "65931",
          "latitude": 50.11552,
          "longitude": 8.68417
        },
        "location": {
          "capital": "Berlin",
          "population": 83783942,
          "language": { "name": "German", "code": "de", "native": "Deutsch" },
          "flag": {
            "emoji": "🇩🇪",
            "unicode": "U+1F1E9 U+1F1EA",
            "png": {
              "1000px": "https://greip.io/img/flags/png1000px/de.png",
              "250px": "https://greip.io/img/flags/png250px/de.png",
              "100px": "https://greip.io/img/flags/png100px/de.png"
            },
            "svg": "https://greip.io/img/flags/svg/de.svg"
          },
          "phone": "49",
          "is_eu": true,
          "neighbours": "CH,PL,NL,DK,BE,CZ,LU,FR,AT",
          "tld": ".de"
        },
        "currency": {
          "name": "Euro",
          "code": "EUR",
          "symbol": "€"
        },
        "asn": {
          "asn": "AS14061",
          "name": "DIGITALOCEAN-ASN",
          "org": "DigitalOcean, LLC",
          "phone": "+1-347-875-6044",
          "email": "noc@digitalocean.com",
          "domain": "digitalocean.com",
          "created": "2012-05-14",
          "type": "hosting"
        },
        "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CET",
          "offset": 3600,
          "current_time": "03:33:13",
          "current_timestamp": 1709519593,
          "is_dst": false,
          "sun_info": {
            "sunset": "18:14:11",
            "sunrise": "06:59:29",
            "transit": "12:36:50",
            "civil_twilight_begin": "06:28:47",
            "civil_twilight_end": "18:44:53",
            "nautical_twilight_begin": "05:51:20",
            "nautical_twilight_end": "19:22:21",
            "astronomical_twilight_begin": "05:13:27",
            "astronomical_twilight_end": "20:00:13",
            "day_length": "11:14:42"
          }
        },
        "security": {
          "vpn_or_proxy": true,
          "vpn_or_proxy_type": "VPN",
          "tor": false,
          "bot": false,
          "relay": false,
          "relay_country": null,
          "relay_city": null,
          "hosting": true,
          "is_blacklisted": false
        },
        "device": {
          "mobile": { "detected": false },
          "type": "desktop",
          "os": {
            "type": "desktop",
            "name": "MacOS",
            "family": "macintosh",
            "version": "Big Sur",
            "title": "MacOS Big Sur",
            "bits64": "1"
          },
          "browser": {
            "name": "Safari",
            "version": "17.2",
            "version_major": "1",
            "title": "Safari 17.2",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15"
          },
          "fingerprint": null
        },
        "custom_rules_applied": {
          "total": 0,
          "rules": []
        }
      },
      "execution_ms": 4
    }
    ```

    ```json Error theme={null}
    {
      "success": false,
      "code": 101,
      "type": "invalid_key",
      "description": "The API Key is missing or invalid."
    }
    ```
  </ResponseExample>
</Panel>

### Response properties

<ResponseField name="success" type="boolean" required>
  `true` when the request succeeded; `false` on error.
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="ip" type="object" required>
      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="address" type="string" required>
          IP address you're looking up.
        </ResponseField>

        <ResponseField name="version" type="integer" required>
          Type of IP address (`IPv4`, or `IPv6`), expressed as `4` or `6`.
        </ResponseField>

        <ResponseField name="numeric" type="integer" required>
          Numeric representation of the IP address.
        </ResponseField>

        <ResponseField name="bogon" type="boolean" required>
          Indicates if the IP address is a bogon.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="geo" type="object" required>
      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="continent" type="string" required>
          Name of the continent where the IP address is.
        </ResponseField>

        <ResponseField name="continent_code" type="string" required>
          Code representation of the continent.
        </ResponseField>

        <ResponseField name="country_code" type="string" required>
          Code representation of the country in `ISO-3166` format.
        </ResponseField>

        <ResponseField name="continent_geo_name_id" type="integer" required>
          GeoName ID of the continent.
        </ResponseField>

        <ResponseField name="country" type="string" required>
          Name of the country.
        </ResponseField>

        <ResponseField name="country_geo_name_id" type="integer" required>
          GeoName ID of the country.
        </ResponseField>

        <ResponseField name="region" type="string" required>
          Name of the region.
        </ResponseField>

        <ResponseField name="city" type="string" required>
          Name of the city.
        </ResponseField>

        <ResponseField name="postal" type="string" required>
          ZIP code of the location where the IP address belong.
        </ResponseField>

        <ResponseField name="latitude" type="number" required>
          Latitude coordinate of the location.
        </ResponseField>

        <ResponseField name="longitude" type="number" required>
          Longitude coordinate of the location.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="location" type="object" required>
      <Expandable title="details">
        <ResponseField name="capital" type="string" required>
          Capital city of the country.
        </ResponseField>

        <ResponseField name="population" type="integer" required>
          Population of the country.
        </ResponseField>

        <ResponseField name="language" type="object" required>
          <Expandable title="details">
            <ResponseField name="name" type="string" required>
              Official language of the country.
            </ResponseField>

            <ResponseField name="code" type="string" required>
              Language code in `ISO-639` format.
            </ResponseField>

            <ResponseField name="native" type="string" required>
              Native name of the language.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="flag" type="object" required>
          <Expandable title="details">
            <ResponseField name="emoji" type="string" required>
              Flag emoji representation.
            </ResponseField>

            <ResponseField name="unicode" type="string" required>
              Flag Unicode representation.
            </ResponseField>

            <ResponseField name="png" type="object" required>
              <Expandable title="images">
                <ResponseField name="1000px" type="string" required>
                  URL to 1000px PNG flag.
                </ResponseField>

                <ResponseField name="250px" type="string" required>
                  URL to 250px PNG flag.
                </ResponseField>

                <ResponseField name="100px" type="string" required>
                  URL to 100px PNG flag.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="svg" type="string" required>
              URL to SVG flag.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="phone" type="string" required>
          International dialing code for the country.
        </ResponseField>

        <ResponseField name="is_eu" type="boolean" required>
          Indicates if the country is in the EU.
        </ResponseField>

        <ResponseField name="neighbours" type="string" required>
          List of neighboring countries' codes.
        </ResponseField>

        <ResponseField name="tld" type="string" required>
          Top-level domain of the country.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="currency" type="object" required>
      <Expandable title="details">
        <ResponseField name="name" type="string" required>
          Name of the currency.
        </ResponseField>

        <ResponseField name="code" type="string" required>
          Currency code in `ISO-4217` format.
        </ResponseField>

        <ResponseField name="symbol" type="string" required>
          Symbol of the currency.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="asn" type="object" required>
      <Expandable title="details">
        <ResponseField name="number" type="string" required>
          Autonomous System Number (for example `AS15169`).
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Name of the ASN.
        </ResponseField>

        <ResponseField name="org" type="string" required>
          Organization associated with the ASN.
        </ResponseField>

        <ResponseField name="phone" type="string" required>
          Phone contact for the ASN.
        </ResponseField>

        <ResponseField name="email" type="string" required>
          Email contact for the ASN.
        </ResponseField>

        <ResponseField name="domain" type="string" required>
          Domain associated with the ASN.
        </ResponseField>

        <ResponseField name="created" type="string" required>
          Date of ASN creation.
        </ResponseField>

        <ResponseField name="type" type="string" required>
          Type of organization ("isp", "hosting", "business", "education", or
          "government").
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="timezone" type="object" required>
      <Expandable title="details">
        <ResponseField name="name" type="string" required>
          Timezone name.
        </ResponseField>

        <ResponseField name="abbreviation" type="string" required>
          Timezone abbreviation.
        </ResponseField>

        <ResponseField name="offset" type="integer" required>
          Timezone offset from UTC.
        </ResponseField>

        <ResponseField name="current_time" type="string" required>
          Current time in the timezone.
        </ResponseField>

        <ResponseField name="current_timestamp" type="integer" required>
          Current timestamp in the timezone.
        </ResponseField>

        <ResponseField name="is_dst" type="boolean" required>
          Indicates if Daylight Saving Time is active.
        </ResponseField>

        <ResponseField name="sun_info" type="object" required>
          <Expandable title="details">
            <ResponseField name="sunset" type="string" required>
              Sunset time.
            </ResponseField>

            <ResponseField name="sunrise" type="string" required>
              Sunrise time.
            </ResponseField>

            <ResponseField name="transit" type="string" required>
              Solar transit time.
            </ResponseField>

            <ResponseField name="civil_twilight_begin" type="string" required>
              Civil twilight begin time.
            </ResponseField>

            <ResponseField name="civil_twilight_end" type="string" required>
              Civil twilight end time.
            </ResponseField>

            <ResponseField name="nautical_twilight_begin" type="string" required>
              Nautical twilight begin time.
            </ResponseField>

            <ResponseField name="nautical_twilight_end" type="string" required>
              Nautical twilight end time.
            </ResponseField>

            <ResponseField name="astronomical_twilight_begin" type="string" required>
              Astronomical twilight begin time.
            </ResponseField>

            <ResponseField name="astronomical_twilight_end" type="string" required>
              Astronomical twilight end time.
            </ResponseField>

            <ResponseField name="day_length" type="string" required>
              Length of the day.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="security" type="object" required>
      <Expandable title="details">
        <ResponseField name="vpn_or_proxy" type="boolean" required>
          Indicates if the IP address is a proxy service.
        </ResponseField>

        <ResponseField name="vpn_or_proxy_type" type="string" required>
          Type of proxy used.
        </ResponseField>

        <ResponseField name="tor" type="boolean" required>
          Indicates if accessed through Tor network.
        </ResponseField>

        <ResponseField name="bot" type="boolean" required>
          Indicates if the user is a bot.
        </ResponseField>

        <ResponseField name="relay" type="boolean" required>
          Indicates if it's a Apple's Private Relay connection.
        </ResponseField>

        <ResponseField name="relay_country" type="string">
          Country code for Apple Private Relay when detected; otherwise `null`.
        </ResponseField>

        <ResponseField name="relay_city" type="string">
          City for Apple Private Relay when detected; otherwise `null`.
        </ResponseField>

        <ResponseField name="hosting" type="boolean" required>
          Indicates if the IP address belong to a hosting provider.
        </ResponseField>

        <ResponseField name="is_blacklisted" type="boolean" required>
          Indicates if the IP address is blacklisted due to applying [custom
          rules](/knowledge-base/custom-rules/overview) or were found in one of
          your blacklists.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="device" type="object" required>
      <Expandable title="details">
        <ResponseField name="mobile" type="object" required>
          Mobile detection from the user agent.

          <Expandable title="properties" defaultOpen={true}>
            <ResponseField name="detected" type="boolean" required>
              `true` when the user agent looks like a mobile device.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="type" type="string" required>
          Type of device.
        </ResponseField>

        <ResponseField name="os" type="object" required>
          <Expandable title="details">
            <ResponseField name="type" type="string" required>
              Type of operating system.
            </ResponseField>

            <ResponseField name="name" type="string" required>
              Name of the operating system.
            </ResponseField>

            <ResponseField name="family" type="string" required>
              Family of the operating system.
            </ResponseField>

            <ResponseField name="version" type="string" required>
              Version of the operating system.
            </ResponseField>

            <ResponseField name="title" type="string" required>
              Title of the operating system.
            </ResponseField>

            <ResponseField name="bits64" type="string" required>
              64-bit mode hint from the parser (often `Unknown` when not detected).
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="browser" type="object" required>
          <Expandable title="details">
            <ResponseField name="name" type="string" required>
              Name of the browser.
            </ResponseField>

            <ResponseField name="version" type="number" required>
              Version of the browser.
            </ResponseField>

            <ResponseField name="version_major" type="integer" required>
              Major version of the browser.
            </ResponseField>

            <ResponseField name="title" type="string" required>
              Title of the browser.
            </ResponseField>

            <ResponseField name="user_agent" type="string" required>
              The user-agent of the browser.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="fingerprint" type="string">
          Device fingerprint hash when available; `null` on IP lookup routes that omit device capture.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="custom_rules_applied" type="object">
      The custom rules applied to this request, [learn
      more](/knowledge-base/custom-rules/overview).

      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="total" type="integer" required>
          The total number of custom rules applied to this request.
        </ResponseField>

        <ResponseField name="rules" type="object" required>
          The custom rules applied to this request, [learn
          more](/knowledge-base/custom-rules/overview).

          <Expandable title="properties" defaultOpen={true}>
            <ResponseField name="id" type="string" required>
              The rule ID as shown in the dashboard (e.g: `CR104`).
            </ResponseField>

            <ResponseField name="title" type="string" required>
              The rule title you set when creating the rule.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution_ms" type="integer" required>
  Time taken to process the request (milliseconds).
</ResponseField>


## OpenAPI

````yaml openapi/v2.json GET /geo/ip
openapi: 3.0.3
info:
  title: Greip API v2 (docs playground)
  version: 2.0.0
servers:
  - url: https://v2.greipapi.com
security: []
paths:
  /geo/ip:
    get:
      summary: IP geolocation for the current request
      operationId: geoIp
      parameters:
        - name: params
          in: query
          schema:
            type: string
        - name: lang
          in: query
          schema:
            type: string
        - name: callback
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            default: JSON
        - name: mode
          in: query
          schema:
            type: string
            default: live
        - name: source
          in: query
          schema:
            type: string
        - name: user_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.