Geo-IP API

The following document highlights the details of the Geo-IP API.

API Description

Objective

The Geo-IP API accepts an IP address and responds with the geolocation details.

Input	Output
An IP address (optional - defaults to the public IP address of the end user's system)	Geolocation details including city, country, coordinates, ISP, organization, and timezone information

API URL

https://<regionCode>.idv.hyperverge.co/v1/geoIp

API Endpoint

geoIp

regionCode Details

The API URL accepts any of the following region code values against the regionCode placeholder.

Region	regionCode Value
India	ind
USA	usa
Africa	zaf
Europe	irl
Singapore	sgp
Indonesia	idn

Overview

The Geo-IP API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send the request body as JSON through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Geo-IP API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

IP Address Requirements

A Public IP is assigned by your Internet Service Provider (ISP) and is visible on the internet, allowing the Geo-IP API to fetch location data.

In contrast, Private IPs are used within local networks, for example, at home or in an office and cannot be used to retrieve such details, as they are not visible on the public internet.

The following table provides the details of the parameters required for the Geo-IP API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
ip	Optional	string	The IP address for verification	Valid IPv4 or IPv6 address	The public IP address of the end user's system

Request

The following code snippet demonstrates a standard curl request for the Geo-IP API:

curl --location --request POST 'https://<regionCode>.idv.hyperverge.co/v1/geoIp' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "ip": "<Enter_the_IP_address>"
}'

Success Response

The following code snippet demonstrates a success response from the Geo-IP API:

  {
  "status": "success",
  "statusCode": "200",
  "metadata": {
    "requestId": "<Unique_Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "ipAddress": "<IP_Address>",
    "geoDetails": {
      "as": "<Autonomous_System>",
      "city": "<City>",
      "country": "<Country>",
      "countryCode": "<Country_Code>",
      "isp": "<Internet_Service_Provider>",
      "lat": "<Latitude>",
      "lon": "<Longitude>",
      "org": "<Organization>",
      "query": "<Query_IP_Address>",
      "region": "<Region_Code>",
      "regionName": "<Region_Name>",
      "status": "<Request_Status>",
      "timezone": "<Timezone>",
      "zip": "<Zip_Code>"
    }
  },
  "summary": {
    "action": "<Action>",
    "details": []
  }
}

Success Response Details

The following table outlines the details of the success response from the Geo-IP API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
metadata	object	The JSON object containing request and transaction identifiers
metadata.requestId	string	A unique identifier for the request
metadata.transactionId	string	A unique transaction identifier for tracking purposes
result	object	The JSON object containing the geolocation details
result.ipAddress	string	The IP address used in the request
result.geoDetails	object	The JSON object containing detailed geolocation information
result.geoDetails.as	string	The Autonomous System (AS) related to the IP address
result.geoDetails.city	string	The city corresponding to the IP address
result.geoDetails.country	string	The country corresponding to the IP address
result.geoDetails.countryCode	string	The country code for the IP address location
result.geoDetails.isp	string	The Internet Service Provider (ISP) associated with the IP address
result.geoDetails.lat	string	The latitude of the geographical location of the IP address
result.geoDetails.lon	string	The longitude of the geographical location of the IP address
result.geoDetails.org	string	The organization associated with the IP address
result.geoDetails.query	string	The IP address query
result.geoDetails.region	string	The region code corresponding to the IP address location
result.geoDetails.regionName	string	The name of the region corresponding to the IP address location
result.geoDetails.status	string	The status of the geolocation request
result.geoDetails.timezone	string	The timezone corresponding to the IP address location
result.geoDetails.zip	string	The zip code corresponding to the IP address location
summary	object	The JSON object containing the summary of the verification process
summary.action	string	The result of the verification process, indicating if the request was successful or required further action
summary.details	array	An array providing additional details of the request

Failure Response

The following code snippet demonstrates a failure response from the Geo-IP API when it fails to locate the geo-IP:

 {
    "status": "failure",
    "statusCode": 400,
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    },
    "result": {
        "error": "Unable to locate geoIp",
        "summary": {
            "action": "fail",
            "details": [
                {
                    "code": "136",
                    "message": "Unable to locate geoIp"
                }
            ]
        }
    }
}

Error Responses

The following are some error responses from the Geo-IP API:

Unable to Locate Geo-IP

{
    "status": "failure",
    "statusCode": 400,
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    },
    "result": {
        "error": "Unable to locate geoIp",
        "summary": {
            "action": "fail",
            "details": [
                {
                    "code": "136",
                    "message": "Unable to locate geoIp"
                }
            ]
        }
    }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
      "message": "Internal Server Error"
  }
}

Server Busy

{
  "status": "failure",
  "statusCode": 503,
  "error": {
      "message": "Server Busy"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Unable to locate geoIp	Geolocation details could not be fetched due to invalid or unresolvable IP	Ensure the IP address is valid and publicly accessible. If not providing an IP, ensure the system has a valid public IP address
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution
503	Server Busy	The Geo-IP API server is currently busy and cannot process the request	Retry the request after some time or contact the HyperVerge team if the issue persists