API - Geolocate IP Addresses (geo_lookup)

Endpoint

POST https://opensolr.com/solr_manager/api/geo_lookup

Parameters

How It Works

Every address you send is validated first, then resolved. Duplicates are collapsed, so sending the same address forty times costs one lookup. Results already known to Opensolr are served from cache: a resolved address is cached for a week, an address the locator has no data for is cached for an hour, and an upstream failure is cached for one minute only — a transient outage never masquerades as “this address has no geography”.

Addresses with no geography are refused before any lookup happens: loopback, RFC1918 private ranges, CGNAT, link-local, multicast, documentation and reserved ranges, and their IPv6 equivalents (unique-local, link-local, Teredo, NAT64, documentation). An IPv4-mapped IPv6 address such as ::ffff:8.8.8.8 is unwrapped to its IPv4 form and judged by the IPv4 rules. These come back as ERROR_NOT_A_PUBLIC_IP inside the results rather than failing your request.

Results are keyed by the address exactly as you sent it (reduced to the characters an address can contain), so you can look up what you asked for without re-normalising anything. The ip field inside each entry is the canonical form.

Absent facts are absent

On a resolved entry only found, ip and country_code are guaranteed. Every other field is omitted when the locator does not know it — never an empty string, never a zero standing in for “unknown”. Test with isset() and you never have to guess whether a value is real:

• Coordinates are omitted, not faked. A missing, non-numeric or out-of-range pair is dropped; so is exactly 0,0, which is a real place in the Gulf of Guinea and would put a false cluster on your map; and so is the locator's continental-US centroid when no city was resolved, which would otherwise spike every map in the middle of Kansas. Country and timezone are still returned in that case.
• timezone is always a real IANA identifier (validated against the timezone database) or absent. Never an offset, never an invented string.

Versioned contract

The response shape is Opensolr's, not the locator's, and it carries contract_version. The provider behind the endpoint can be replaced without breaking your integration, and the field names on this page do not change when it is.

Limits

Response

The envelope:

A resolved entry:

An unresolved entry carries found: false, the canonical ip when the address was at least valid, and a msg naming the reason.

Errors

Per-address problems are not request failures — they appear inside results, so one bad line in a log batch never voids the other forty-nine:

Code Examples

cURL

# A single address
curl -s "https://opensolr.com/solr_manager/api/geo_lookup?email=YOUR_EMAIL&api_key=YOUR_API_KEY&ip=8.8.8.8"

# A batch, as a plain separated list
curl -s -X POST "https://opensolr.com/solr_manager/api/geo_lookup" \
     -d "email=YOUR_EMAIL" -d "api_key=YOUR_API_KEY" \
     -d "ips=8.8.8.8, 1.1.1.1, 208.67.222.222"

# A batch, as a JSON body
curl -s -X POST "https://opensolr.com/solr_manager/api/geo_lookup" \
     -H "Content-Type: application/json" \
     -d '{"email":"YOUR_EMAIL","api_key":"YOUR_API_KEY","ips":["8.8.8.8","1.1.1.1"]}'

PHP

$payload = json_encode([
    'email'   => 'YOUR_EMAIL',
    'api_key' => 'YOUR_API_KEY',
    'ips'     => ['8.8.8.8', '1.1.1.1', '10.0.0.5'],
]);

$ch = curl_init('https://opensolr.com/solr_manager/api/geo_lookup');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => $payload,
]);
$out = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($out['capped'] ?? false) {
    echo "Only the first {$out['max_ips']} of {$out['submitted']} addresses were resolved\n";
}

foreach ($out['results'] as $sent => $entry) {
    if (empty($entry['found'])) {
        echo "{$sent}: {$entry['msg']}\n";
        continue;
    }
    // Never assume city/coordinates are there — absent means unknown.
    $where = $entry['city'] ?? $entry['region'] ?? $entry['country_name'] ?? $entry['country_code'];
    $pin   = isset($entry['latitude']) ? " ({$entry['latitude']}, {$entry['longitude']})" : '';
    echo "{$sent}: {$entry['country_code']} — {$where}{$pin}\n";
}

Python

import requests

r = requests.post(
    "https://opensolr.com/solr_manager/api/geo_lookup",
    json={
        "email": "YOUR_EMAIL",
        "api_key": "YOUR_API_KEY",
        "ips": ["8.8.8.8", "1.1.1.1", "10.0.0.5"],
    },
    timeout=60,
)
data = r.json()

for sent, entry in data["results"].items():
    if not entry.get("found"):
        print(sent, entry["msg"])
        continue
    # .get() everywhere: an absent key means the locator did not know it.
    print(sent, entry["country_code"], entry.get("city"), entry.get("timezone"))

Example Response

{
  "status": true,
  "contract_version": 1,
  "count": 3,
  "submitted": 3,
  "max_ips": 50,
  "capped": false,
  "results": {
    "8.8.8.8": {
      "found": true,
      "ip": "8.8.8.8",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "city": "Mountain View",
      "latitude": 37.386,
      "longitude": -122.0838,
      "timezone": "America/Los_Angeles"
    },
    "1.1.1.1": {
      "found": true,
      "ip": "1.1.1.1",
      "country_code": "AU",
      "country_name": "Australia",
      "timezone": "Australia/Sydney"
    },
    "10.0.0.5": {
      "found": false,
      "msg": "ERROR_NOT_A_PUBLIC_IP"
    }
  }
}

Use Cases

• Add a country or city column to the addresses returned by the index request log and the traffic monitoring API, so you can see where your search traffic actually comes from
• Draw a map of query volume by country without shipping a geo-IP database with your application, and without a per-lookup bill
• Spot traffic that does not belong: a burst of queries from a country you do not serve usually means a leaked key, a scraper, or an integration nobody remembers deploying
• Decide which region to host an index in, from where your users really are
• Enrich your own application or web server logs — the endpoint does not care whether the addresses came from Opensolr
• Set a per-user timezone from a signup address, using a value that is guaranteed to be a real IANA identifier

Related Documentation