API documentation

Your first API request

curl --get 'https://www.geoipy.com/api/IPsInfo' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'X-API-Key: YOUR_API_KEY'

Use HTTPS and X-API-Key. Query-string keys can appear in logs. Different header and query keys return HTTP 400.

Create a key in your dashboard. The full key appears once. Keep it in private server settings, never in browser code or public repositories. Replacement invalidates the old key immediately. Revocation or expiry stops new requests; accepted requests may finish.

Response and freshness

HTTP 200 returns JSON. This shortened example is illustrative; available fields depend on provider data.

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "country_code": "US"
}

Cache freshness defaults to 12 hours. X-Data-Fetched-At reports retrieval time in UTC. Expired data is not served on refresh failure; retrieval time is not the data's age.

X-Request-ID identifies a request for support. Geolocation is an approximate network location, not a person's exact position.

Usage and retries

Successful requests, including cache hits, use your allowance. Pending requests reserve capacity; failures release it. Usage resets on the first day of each month at 00:00 UTC. Changing a plan or key does not reset usage.

For HTTP 429 or temporary 503/504 errors, honor Retry-After and use limited retries with increasing delays. Fix invalid input or credentials before retrying.

Errors

Errors return application/json with an HTTP error status. API identifiers and example payloads stay in their documented form.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "usage_limit_reached",
    "info": "The monthly API allowance has been reached."
  }
}

Server-side examples

JavaScript · server

const url = new URL('https://www.geoipy.com/api/IPsInfo');
url.searchParams.set('ip', '8.8.8.8');
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.GEOIPY_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.info);
console.log(data);

C#

using (var client = new System.Net.Http.HttpClient())
{
    client.DefaultRequestHeaders.Add("X-API-Key",
        System.Environment.GetEnvironmentVariable("GEOIPY_API_KEY"));
    var response = await client.GetAsync(
        "https://www.geoipy.com/api/IPsInfo?ip=8.8.8.8");
    var json = await response.Content.ReadAsStringAsync();
    // Inspect response.StatusCode and parse json before retrying.
}

Python

import os, requests
response = requests.get(
    'https://www.geoipy.com/api/IPsInfo',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': os.environ['GEOIPY_API_KEY']},
    timeout=15)
data = response.json()
response.raise_for_status()

PHP

$url = 'https://www.geoipy.com/api/IPsInfo?' . http_build_query(['ip' => '8.8.8.8']);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GEOIPY_API_KEY')]]);
$json = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($json === false) { throw new RuntimeException('The request failed.'); }
curl_close($ch);
$data = json_decode($json, true);
// Inspect $status and $data['error'] when the status is not 200.