IP Address

IP Address Geolocation Lookup
Look up geolocation metadata for an IPv4 or IPv6 address.

Method: GET
Path: /v1/location/ip
Demo: https://api.gugudata.io/v1/location/ip/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.

ip (string, required): IP address to lookup (supports both IPv4 and IPv6, e.g., 8.8.8.8 or 2001:4878:b554:aaaa:aaaa:aaaa:aaaa:aaaa)

Response Fields:

dataStatus.requestParameter (string, required): Normalized request parameters echoed by the service. Sensitive credentials are omitted when available.

dataStatus.statusCode (integer, required): Application-level status code returned by the current v1 contract.

dataStatus.status (string, required): Application-level status enum returned by the current v1 contract.

dataStatus.statusDescription (string, required): Application-level status message returned by the current v1 contract.

dataStatus.responseDateTime (string, required): Response timestamp returned by the current service contract.

dataStatus.dataTotalCount (integer, required): Total number of records that match the request.

data.countryCode (string, optional): ISO country code (e.g., US, CN, GB)

data.state (string, optional): State or province name

data.city (string, optional): City name

data.latitude (number, optional): Geographic latitude coordinate

data.longitude (number, optional): Geographic longitude coordinate

HTTP Status Codes:

200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.

400: Invalid request parameters or request format. Check required fields, data types, and request body format.

401: Missing or unknown application key. Provide a valid appkey with the request.

403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.

429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.

500: Internal service error. Retry later or contact support if the error persists.

503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

200 Normal return: IP geolocation information successfully retrieved

400 Parameter error: Invalid IP address format or missing required parameters

429 Request frequency limited: Cannot exceed 100 requests per second

403 Account in arrears: Payment required to continue using the service

402 APPKEY error: Please check whether the APPKEY passed is obtained from the developer center

500 API response error: Internal server error during IP geolocation lookup

503 Service unavailable: IP geolocation service temporarily unavailable

Key Features:

Get geolocation information for any IP address (IPv4 and IPv6).

Retrieve country, state, city, and geographic coordinates.

Support for both IPv4 and IPv6 address formats.

Accurate location data from reliable geolocation databases.

Perfect for fraud detection, content localization, and analytics.

Real-time IP address validation and geolocation lookup.

Full API support for HTTPS (TLS v1.0 / v1.1 / v1.2 / v1.3).

Fully compatible with Apple ATS.

Nationwide multi-node CDN deployment.

Ultra-fast response, API interface load balancing built with multiple servers.

Details:
https://gugudata.io/details/location-ip

application/json

Bodyapplication/json

Example

{
  "dataStatus": {
    "requestParameter": "string",
    "statusCode": 0,
    "status": "string",
    "statusDescription": "string",
    "responseDateTime": "string",
    "dataTotalCount": 0
  },
  "data": {
    "countryCode": "string",
    "state": "string",
    "city": "string",
    "latitude": 0,
    "longitude": 0
  },
  "DataStatus": {
    "StatusCode": 100,
    "StatusDescription": "OK",
    "ResponseDateTime": "2026-01-01 00:00:00",
    "DataTotalCount": 1
  }
}

Request

Request Code Samples

Responses