Geo IP and VPN Lookup API

The following document outlines the details of the Geo IP and VPN Lookup API

Objective

The Geo IP and VPN Lookup API returns detailed IP address information including geolocation data, network information, connection type, and privacy indicators (VPN, proxy, TOR detection). The API provides comprehensive location details such as timezone, languages, and country-specific information, enabling applications to implement location-based services, network security measures, and content delivery controls.

Input	Output
User's IP address	Detailed information about the queried IP address. A complete list of details returned by the API is provided under the Success Response Details section.

API URL

https://ind-engine.thomas.hyperverge.co/v1/geoIpWithVPN

API Endpoint

geoIpWithVPN

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

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

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
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	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`ip`	The IP Address to be checked	Optional When no IP address is provided, the API automatically fetches the public IP address of the device making the API request.	Not Applicable	The Public IP* address of the end user's system

note

*A Public IP is assigned by your Internet Service Provider (ISP) and is visible on the internet, allowing the 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.

Request

The following code shows a standard cURL request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoIpWithVPN' \
--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_valid_IP_Address>"
}'

Success Response

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

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "ip": "<IP_Address>",
        "type": "<IP_Type>",
        "continentCode": "<Continent_Code>",
        "continentName": "<Continent_Name>",
        "country": "<Country_Code>",
        "countryName": "<Country_Name>",
        "regionCode": "<Region_Code>",
        "region": "<Region_Name>",
        "city": "<City_Name>",
        "postal": "<Postal_Code>",
        "lat": "<Latitude>",
        "long": "<Longitude>",
        "ipRoutingType": "<IP_Routing_Type>",
        "connectionType": "<Connection_Type>",
        "location": {
            "geonameId": <Geoname_ID>,
            "capital": "<Country_Capital>",
            "languages": [
                {
                    "code": "<Language_Code>",
                    "name": "<Language_Name>",
                    "native": "<Native_Language_Name>"
                }
            ],
            "countryFlag": "<Country_Flag_URL>",
            "countryFlagEmoji": "🇮🇳",
            "countryFlagEmojiUnicode": "<Country_Flag_Unicode>",
            "callingCode": "<Country_Calling_Code>",
            "isEu": <Is_EU_Country>
        },
        "timeZone": "<Timezone>",
        "connection": {
            "asn": <ASN_Number>,
            "isp": "<ISP_Name>",
            "sld": "<Second_Level_Domain>",
            "tld": "<Top_Level_Domain>",
            "carrier": "<Carrier_Name>",
            "home": <Is_Home_Connection>,
            "organizationType": "<Organization_Type>",
            "isicCode": "<ISIC_Code>",
            "naicsCode": "<NAICS_Code>"
        },
        "privacy": {
            "proxy": <Is_Proxy>,
            "tor": <Is_Tor>,
            "service": <Privacy_Service>,
            "hosting": <Is_Hosting>,
            "vpn": <Is_VPN>
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

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

Parameter	Type	Description
ip	string	The queried IP address
type	string	The type of IP address
continentCode	string	The code of the continent associated with the IP address
continentName	string	The full name of the continent associated with the IP address
country	string	The country code of the IP address location
countryName	string	The name of the country associated with the IP address
regionCode	string	The code of the region associated with the IP address
region	string	The name of the region associated with the IP address
city	string	The city where the IP address is geographically located
postal	string	The postal/ZIP code corresponding to the IP address location
lat	string	The latitude of the IP address
long	string	The longitude of the IP address
ipRoutingType	string	The routing method of the IP address (e.g., mobile gateway, residential, business)
connectionType	string	The type of connection used for the IP address
location	object	Geographical location details associated with the IP address
location.geonameId	number	The unique ID for the geographical location
location.capital	string	The capital city of the country associated with the IP address
location.languages	array	The official languages spoken in the region associated with the IP address
location.countryFlag	string	URL to the flag image of the country associated with the IP address
location.countryFlagEmoji	string	The emoji representation of the country flag
location.countryFlagEmojiUnicode	string	The unicode value of the country flag emoji
location.callingCode	string	Calling code for the country associated with the IP address
location.isEu	boolean	Indicates whether the country is part of the European Union
timeZone	string	The time zone of the IP address location
connection	object	Network connection details associated with the IP address
connection.asn	number	The Autonomous System Number (ASN) associated with the IP address
connection.isp	string	The Internet Service Provider (ISP) associated with the IP address
connection.sld	string	The second-level domain associated with the IP address
connection.tld	string	The top-level domain associated with the IP address
connection.carrier	string	The carrier name associated with the IP address
connection.home	boolean	Indicates whether the connection is a home connection
connection.organizationType	string	The type of organization associated with the IP address
connection.isicCode	string	The International Standard Industrial Classification (ISIC) code associated with the IP address
connection.naicsCode	string	The North American Industry Classification System (NAICS) code associated with the IP address
privacy	object	Information indicating if the IP is using privacy services like VPN, proxy, or TOR
privacy.proxy	boolean	Indicates whether the IP is using a proxy server
privacy.tor	boolean	Indicates whether the IP is part of the TOR network
privacy.service	string	Name of the privacy service, if applicable
privacy.hosting	boolean	Indicates whether the IP is associated with hosting services
privacy.vpn	boolean	Indicates whether the IP is using a VPN

Error Responses

The following are some error responses from the API:

Missing/Invalid credentials
Invalid IP Address
Internal Server Error

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "status": "failure",
    "statusCode": 404,
    "error": "Please provide a valid IP address",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

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

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
403	Access Denied	Please contact the HyperVerge team
404	Please provide a valid IP address	The provided Id address is invalid
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​