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": "🇺🇸"
        },
        "region": { "code": "CA", "name": "California" },
        "district": "Santa Clara County",
        "city": "Mountain View",
        "postalCode": "94043",
        "coordinates": {
            "latitude": 37.386,
            "longitude": -122.084,
            "accuracyRadius": 386
        },
        "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"
    }
}

Conditional fields

Null or unavailable fields are omitted from the response. The unions array is only present for countries belonging to a political/economic union (e.g. EU). On successful responses, meta.requestId requires the X-Debug: timing header. Error responses always include meta.requestId.

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.unions`	string[]	Political/economic unions (e.g. ["EU"]). Omitted when empty.
`location.region.code`	string	ISO 3166-2 subdivision code
`location.region.name`	string	Region/state/province name
`location.district`	string	Subdivision level 2 (e.g. county). Omitted when unavailable.
`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 miles
`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)

sources

Field	Type	Description
`sources.geo`	string[]	Geo data providers (e.g. ["dbip", "ip2location"])
`sources.asn`	string[]	ASN data providers (e.g. ["ipinfo"])
`sources.tz`	string[]	Timezone data providers (e.g. ["derived"])

Field	Type	Description
`meta.precision`	string	"city", "region", "country", "continent", or "none"
`meta.tier`	string	Plan tier (e.g. "pro", "starter", "anonymous")
`meta.requestId`	string	Unique request ID (requires X-Debug: timing header)
`meta.degraded`	boolean	true when the response is limited due to cap exceeded

Error Response Format

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

JSON

{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid API key"
    },
    "meta": {
        "requestId": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Geo endpoint errors also include a query echo:

JSON

{
    "error": {
        "code": "INVALID_IP",
        "message": "Invalid IP address format"
    },
    "meta": {
        "requestId": "550e8400-e29b-41d4-a716-446655440000"
    },
    "query": {
        "type": "ip",
        "value": "not-an-ip"
    }
}

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
400	`VALIDATION_ERROR`	Request validation failed (e.g. missing required field)
401	`UNAUTHORIZED`	API key is missing, invalid, or revoked
403	`FORBIDDEN`	Key does not have the required scope or access is denied
404	`NOT_FOUND`	Endpoint or resource does not exist
413	`PAYLOAD_TOO_LARGE`	Request body exceeds the 10 KB size limit
429	`RATE_LIMIT_EXCEEDED`	Too many requests — slow down or upgrade plan
500	`INTERNAL_ERROR`	Unexpected server error — contact support
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable — retry with backoff

Request ID for debugging

Error responses include a meta.requestId field. Include it when contacting support to help us trace the problem.