Skip to content
iplyt

Handbook

Lookup endpoints

The iplyt platform exposes GeoIP lookup endpoints that match the public API contract. All requests require authentication.

Base path: https://YOUR_PLATFORM_HOST/api/v1

Responses use Content-Type: application/json. Gzip compression is applied when the client supports it.

GET /api/v1/lookup

Look up a single IP address.

Query parameters

Name Required Description
ip yes IPv4 or IPv6 address

Example

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://YOUR_PLATFORM_HOST/api/v1/lookup?ip=8.8.8.8"

Errors

Status Code When
400 MISSING_IP ip query parameter is empty
400 LOOKUP_FAILED Invalid IP address
404 LOOKUP_FAILED IP not found in database
500 LOOKUP_FAILED Internal lookup error

POST /api/v1/lookup

Look up one or many IPs. The body must be valid JSON in one of these forms:

  1. Single IP — JSON string: "8.8.8.8"
  2. Multiple IPs — JSON array: ["8.8.8.8", "1.1.1.1"]

Limits

  • Maximum 100 IPs per request (array body).

Examples

# Single IP
curl -X POST "https://YOUR_PLATFORM_HOST/api/v1/lookup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"8.8.8.8"'

# Multiple IPs
curl -X POST "https://YOUR_PLATFORM_HOST/api/v1/lookup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", "1.1.1.1"]'

Response

  • Single IP (string body or one-element array): one lookup response object.
  • Multiple IPs (array with 2+ elements): JSON array of lookup response objects in the same order as the input.

For multi-IP requests, individual IPs that fail validation or are not found appear in the response array with an error field on each object rather than failing the whole HTTP request.

Errors

Status Code When
400 MISSING_IPS Empty array
400 TOO_MANY_IPS More than 100 IPs (max field included)
400 INVALID_JSON Body is not a string or string array
400 / 404 / 500 LOOKUP_FAILED Per-IP failure (single-IP requests only)
500 MULTI_LOOKUP_FAILED Batch lookup failure 
{
  "error": "too many IPs requested",
  "code": "TOO_MANY_IPS",
  "max": 100
}

Lookup response object

Successful lookups return an object with the following structure. Omitted fields are excluded from JSON.

{
  "ip": "8.8.8.8",
  "asn": {
    "number": "15169",
    "name": "GOOGLE",
    "domain": "google.com"
  },
  "location": {
    "city": "Mountain View",
    "state": "California",
    "country_code": "US",
    "continent": "North America",
    "continent_code": "NA",
    "latitude": 37.386,
    "longitude": -122.0838,
    "postcode": "94035",
    "timezone": "America/Los_Angeles"
  },
  "network": {
    "is_hosting": false,
    "ipv4_count": 1024,
    "ipv6_count": 0
  },
  "organization": {
    "name": "Google LLC",
    "website": "https://google.com",
    "address": "1600 Amphitheatre Parkway",
    "city": "Mountain View",
    "state": "CA",
    "zipcode": "94043",
    "country": "US"
  },
  "geo_reference": {
    "city": {
      "name": "Mountain View",
      "latitude": "37.386",
      "longitude": "-122.0838",
      "country": {
        "name": "United States",
        "iso2": "US",
        "iso3": "USA"
      },
      "state": {
        "name": "California",
        "code": "CA",
        "latitude": "36.7783",
        "longitude": "-119.4179"
      }
    }
  }
}
Field Type Description
ip string Queried IP address
asn object Autonomous system info
location object Geographic location
network object Hosting flag and address counts
organization object Organization and contact details
geo_reference object Optional extended city, state, and country reference data
error string Present when lookup failed for this IP (batch responses)

Related

  • Bulk lookup — paginated lookups for large IP lists
  • Errors — full error code reference
PreviousAuthenticationNextBulk lookup