GeoPluck IP Geolocation API Documentation

Introduction

GeoPluck provides a free web service that can be used to find the location of an IP address. The service provides information such as the country, region, city, latitude and longitude, timezone, and ISP for both IPv4 and IPv6 addresses.

GeoPluck is free to use right now. Simply include your API key with each request. Requests are rate limited to keep the service fast and reliable for everyone.

Rate Limits

GeoPluck is free and rate limited per user to protect reliability.

Basic Usage

The GeoPluck API provides a simple way to retrieve geolocation information for any IP address. Our service is RESTful and returns JSON responses.

GET https://www.geopluck.com/api/lookup?ip=8.8.8.8&auth=YOUR_API_KEY_HERE

Query Parameters

Example Request

GET https://www.geopluck.com/api/lookup?ip=8.8.8.8&auth=gp_your_api_key_here

Example Response

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "continent": "North America",
    "continent_code": "NA",
    "country": "United States",
    "country_code": "US",
    "city": "Mountain View",
    "region": "California",
    "region_code": "CA",
    "postal": "94043",
    "latitude": 37.4056,
    "longitude": -122.0775,
    "timezone": "America/Los_Angeles",
    "time_zone": {
      "id": "America/Los_Angeles",
      "current_time": "01/03/2026, 09:00:00 AM",
      "code": "PST",
      "utc_offset": -28800
    },
    "currency": "USD",
    "language": "en",
    "language_details": {
      "code": "en",
      "name": "English",
      "native": "English"
    },
    "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "isp": "Google LLC",
    "organization": "Google LLC",
    "asn": "AS15169",
    "user_agent": {
      "is_mobile": false,
      "is_tablet": false,
      "is_desktop": true,
      "is_bot": false,
      "browser": "Chrome",
      "browser_version": "120.0.0.0",
      "operating_system": "Windows 10.0",
      "platform": "Microsoft Windows",
      "source": "Mozilla/5.0"
    }
  }
}

Current IP Detection

You can detect the location of the requesting IP address without specifying an IP parameter. Simply omit the IP parameter from the request, or use the dedicated endpoint.

Method 1: Omit IP Parameter

GET https://www.geopluck.com/api/lookup?auth=YOUR_API_KEY_HERE

Method 2: Use /me Endpoint

GET https://www.geopluck.com/api/me?auth=YOUR_API_KEY_HERE

Country Flags

The GeoPluck API can also provide country flag images for IP addresses.

GET https://www.geopluck.com/api/flag?ip=8.8.8.8&auth=YOUR_API_KEY_HERE

Query Parameters

Example Request

GET https://www.geopluck.com/api/flag?ip=8.8.8.8&auth=gp_your_api_key_here

The flag_url returned by the API can be used directly in an HTML img tag:

<img src="https://www.geopluck.com/api/flag/64/us.png" alt="US Flag" width="64" height="64">

Response Format

All GeoPluck API responses follow a consistent JSON format with a success flag and data object.

Field Descriptions

Additional fields may appear when available: continent, continent_code, currency, language, language_details, country_flag_emoji_unicode, time_zone, user_agent.

Error Handling

When an error occurs, the GeoPluck API returns an appropriate HTTP status code along with an error message.

Error Response Format

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes