/ My account / Webservices / Very-GeoIP

GeoIP API Documentation
Table of Contents -
Overview
Authentication & Endpoint
Request Syntax
Parameters
Response Format
Error Handling
Example (PHP)
FAQ

Overview

The Otowui GeoIP API lets you retrieve geographical information for any IP address. It offers two lookup modes for different use cases:

    • locate_full: full GeoLite2 City database lookup, returning the complete record as JSON.
    • locate_city: lightweight lookup, returning only city, region, country, latitude, and longitude.
    • Private server-to-server endpoint with key-based authentication.
    • Unlimited GET requests — no rate limits.
    • Daily automatic MMDB updates via Cron.

Authentication & Endpoint

Register your subscription and obtain your API key via the pricing and My Account pages. Include your key in every request.

Type Endpoint Access Requirements
Private (server-to-server) https://api.otowui.com/geo/v1/private/
  • key parameter in query string or X-API-KEY header
  • Valid subscription

Request Syntax

GET https://api.otowui.com/geo/v1/private/
  ?key=YOUR_API_KEY
  &action=locate_full|locate_city
  &ip=IP_ADDRESS
  &leadid=YOUR_LEAD_ID

Parameters

Name Type Required Description
key string Yes Your Otowui API key (obtainable from My Account).
action locate_full | locate_city Yes Lookup mode: full or lightweight.
ip string (IP address) Yes The IPv4 or IPv6 address to locate.
leadid string No Optional identifier for tracking (e.g., Lead ID).

Response Format

Action: locate_full
Returns the complete GeoIP record:

{
  "success": true,
  "ip": "8.8.8.8",
  "leadid": "12345",
  "data": { /* full MMDB record fields */ },
  "reason": "",
  "errorCode": ""
}

Action: locate_city
Returns a minimal JSON payload:

{
  "success": true,
  "ip": "8.8.8.8",
  "leadid": "12345",
  "data": {
    "city": "Mountain View",
    "region": "California",
    "country": "United States",
    "latitude": 37.386,
    "longitude": -122.0838
  },
  "reason": "",
  "errorCode": ""
}

Error Handling

HTTP Code Meaning
400 Bad request: missing or invalid parameters
401 Unauthorized: missing or invalid API key
403 Forbidden: key not valid for this service
405 Method Not Allowed: only GET and OPTIONS
500 Server error: internal lookup failure

Example (PHP)

$response = file_get_contents(
    'https://api.otowui.com/geo/v1/private/?'
    . 'key=YOUR_API_KEY'
    . '&action=locate_city'
    . '&ip=8.8.8.8'
    . '&leadid=12345'
);
$data = json_decode($response, true);

FAQ

Are GET calls limited? No – all GET requests are unlimited.
What’s the difference between locate_full and locate_city? locate_full returns the entire GeoLite2 City record; locate_city returns only key location fields.
How often is the database updated? Updated daily via a Cron job to ensure up-to-date GeoLite2 data.
Can I call this API from browser-side JavaScript? No – this is a private endpoint requiring a secret API key; use server-to-server calls only.