API Reference

IP Geolocation

Resolve IP addresses to geographic location, ISP, and ASN information

Map any IPv4 or IPv6 address to its geographic location, ISP, and network details. IP geolocation powers content localization, regulatory compliance (GDPR, data residency), fraud detection based on impossible travel, and analytics dashboards that show where your users are connecting from worldwide.

MaxMind GeoLite2ISP lookupASN resolutioncoordinate mapping

Endpoint

POST /v1/ip/geo
Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.
Open Swagger UI (interactive docs)

Request

{
  "ip": "8.8.8.8"
}

Request Fields

FieldTypeDescription
ip string IPv4 or IPv6 address to check

Response

{
  "ip": "8.8.8.8",
  "country": "US",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.386,
  "longitude": -122.0838,
  "isp": "Google LLC",
  "asn": "AS15169"
}

Response Fields

FieldTypeDescription
ip string IPv4 or IPv6 address to check
country string Country code (ISO 3166-1 alpha-2)
region string Region or state name
city string City name
latitude number Geographic latitude
longitude number Geographic longitude
isp string Internet Service Provider name
asn string Autonomous System Number

Error Codes

StatusMeaning
200Request completed successfully
400Bad request — invalid or missing parameters
401Missing or invalid X-API-Key header
429Rate limit exceeded — check Retry-After header
500Internal server error

Common Error Scenarios

400 Invalid IP address

Request that triggers this:

{"ip": "999.999.999.999"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid IP", "status": 400, "detail": "'999.999.999.999' is not a valid IPv4 or IPv6 address"}

How to fix: Validate the IP format before sending. Accept both IPv4 (e.g., 8.8.8.8) and IPv6 formats.

400 Private/reserved IP

Request that triggers this:

{"ip": "192.168.1.1"}

Error response:

{"type": "/problems/validation-error", "title": "Non-Routable IP", "status": 400, "detail": "Private and reserved IP addresses cannot be geolocated"}

How to fix: Only submit public, routable IP addresses. Filter out RFC 1918 private ranges (10.x, 172.16-31.x, 192.168.x).

Code Examples

curl -X POST /v1/ip/geo \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "ip": "8.8.8.8"
}' 
// Node.js (18+) or modern browser
const response = await fetch("/v1/ip/geo", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ip": "8.8.8.8"
}),
});

const data = await response.json();
console.log(response.status, data);
import requests

response = requests.post(
    "/v1/ip/geo",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "ip": "8.8.8.8"
},
)

print(response.status_code)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "ip": "8.8.8.8"
}`)
	req, _ := http.NewRequest("POST", "/v1/ip/geo", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}
{
  "name": "ip_geo",
  "description": "Resolve IP addresses to geographic location, ISP, and ASN information",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/ip/geo",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference