Response Format

Complete reference for the NetLoc8 API response shapes, field descriptions, and error codes.

GeolocationResult

All geolocation endpoints (/v1/ip/me and /v1/ip/{ipAddress}) return this JSON object. Null or unavailable fields are omitted from the response.

JSON

{
    "query": {
        "type": "ip",
        "value": "8.8.8.8",
        "ipVersion": 4
    },
    "location": {
        "continent": { "code": "NA", "name": "North America" },
        "country": {
            "code": "US",
            "name": "United States",
            "flag": "🇺🇸",
            "isEU": false
        },
        "region": { "code": "CA", "name": "California" },
        "city": "Mountain View",
        "postalCode": "94043",
        "coordinates": {
            "latitude": 37.386,
            "longitude": -122.084,
            "accuracyRadius": 621
        },
        "timezone": "America/Los_Angeles",
        "utcOffset": "-07:00",
        "geoConfidence": 1.0
    },
    "network": {
        "asn": "AS15169",
        "organization": "Google LLC",
        "domain": "google.com"
    },
    "sources": {
        "geo": ["dbip", "ip2location"],
        "asn": ["ipinfo"],
        "tz": ["derived"]
    },
    "meta": {
        "precision": "city",
        "tier": "pro",
        "requestId": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Field Reference

query

Field	Type	Description
`query.type`	string	Always "ip"
`query.value`	string	The IP address that was looked up
`query.ipVersion`	number	4 (IPv4) or 6 (IPv6)

location

Field	Type	Description
`location.continent.code`	string	Two-letter continent code (NA, EU, AS, …)
`location.continent.name`	string	Continent full name
`location.country.code`	string	ISO 3166-1 alpha-2 country code
`location.country.name`	string	Country full name (English)
`location.country.flag`	string	Unicode flag emoji
`location.country.isEU`	boolean	Whether the country is an EU member
`location.region.code`	string	ISO 3166-2 subdivision code
`location.region.name`	string	Region/state/province name
`location.city`	string	City name
`location.postalCode`	string	Postal / ZIP code
`location.coordinates.latitude`	number	Latitude (WGS 84)
`location.coordinates.longitude`	number	Longitude (WGS 84)
`location.coordinates.accuracyRadius`	number	Accuracy radius in km
`location.timezone`	string	IANA timezone (e.g. America/Los_Angeles)
`location.utcOffset`	string	Current UTC offset (e.g. -07:00)
`location.geoConfidence`	number	Confidence score: 0.0 – 1.0

network

Field	Type	Description
`network.asn`	string	Autonomous System Number (e.g. AS15169)
`network.organization`	string	ASN organization name
`network.domain`	string	Organization domain (when available)

Field	Type	Description
`meta.precision`	string	"city", "region", "country", "continent", or "none"
`meta.tier`	string	Plan tier that served the request
`meta.requestId`	string	Unique request ID for support / debugging

Error Response Format

When an error occurs, the API returns a JSON object with an error code, message, and HTTP status:

JSON

{
    "error": {
        "code": "INVALID_API_KEY",
        "message": "The provided API key is invalid or has been revoked.",
        "status": 401
    }
}

Error Codes

HTTP	Code	Description
400	`BAD_REQUEST`	Malformed request or invalid parameters
400	`INVALID_IP`	The provided IP address is not a valid IPv4 or IPv6
401	`MISSING_API_KEY`	No API key provided in X-API-Key header
401	`INVALID_API_KEY`	API key is invalid, revoked, or expired
403	`FORBIDDEN`	Key does not have the required scope
403	`ORIGIN_NOT_ALLOWED`	Publishable key: the request origin is not in allowed list
404	`NOT_FOUND`	Endpoint or resource does not exist
409	`CONFLICT`	Resource already exists (e.g. duplicate site)
429	`RATE_LIMIT_EXCEEDED`	Too many requests — slow down or upgrade plan
429	`MONTHLY_CAP_REACHED`	Monthly request quota exhausted
500	`INTERNAL_ERROR`	Unexpected server error — contact support
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable — retry with backoff

Request ID for debugging

Every response includes a meta.requestId field. Include it when contacting support to help us trace the problem.