API overview
Look up any IPv4 or IPv6 address and get location, network, anonymizer detection, threat flags and a fraud score in one JSON response.
The GeoIPHub API is a JSON REST API with one endpoint. Send it an IP address and it returns everything we know about that address, grouped into ten parts, from where it is to how risky it looks.
Base URL
https://api.geoiphub.comEvery path in this reference is relative to it. All requests use HTTPS.
Quick start
Create an API key
Sign in to the dashboard, open API keys and click Create key. Copy the key. It's shown once. See Authentication.
You can also skip this and try the API without a key, at up to 30 lookups a minute.
Keep it on your server
Store the key as an environment variable, like GEOIPHUB_API_KEY. Never put it in a browser, a mobile app or a public repository.
Look up an IP
curl https://api.geoiphub.com/v1/lookup/8.8.8.8 \
-H "x-api-key: $GEOIPHUB_API_KEY"You get one JSON object. Here are three of its groups, trimmed from a real lookup:
{
"ip": "8.8.8.8",
"geo": { "country_code": "US", "city": "Mountain View" },
"detection": { "is_vpn": false, "is_hosting": true, "is_anycast": true },
"scoring": { "fraud_score": 10, "recommended_action": "allow", "detection_methods": ["datacenter_ip"] }
}Conventions
- The IP goes in the path:
/v1/lookup/{ip}. There is no?ip=parameter. - Fields are nested. Read
data.geo.country_codeanddata.scoring.fraud_score, not top-level names. See Response fields. - No nulls. A field with no value is the string
"none", or0for numbers. - Every plan gets every field, including requests without a key. Plans differ only in how many lookups a day you can make.
- Errors are
{ "message": "..." }with a matching HTTP status. See Errors.