Introduction

GRE GeoIP API offers a very powerful and quick geolocation API capable of looking up your website’s visitors accurate information. By retrieving the most important information about the visitors. Such as IP Address, Location, Timezone, Device information and security threats using the most common response formats XML & JSON. By using this API you will be able to know more about your website visitors to adjust better user experience.

This documentation shows the way you can use this API. By highlighting the API methods, options and some other features that allows you get the most of this API.

This API offers test mode. So you can integrate the API with your website/app without affecting your subscription. Please note that the test mode of this API will retrieve random (fake) information. And also, the test mode will simulate the live mode exactly.

Quickstart

GRE GeoIP API can be used by both free and paid API subscriptions. No matter if you purchased a plan or not, you can get full access of the API functions in order to try it’s accuracy, speed and security.

Each user has a unique API Key that can be used to use all the APIs we offer. If you don’t have an account yet, kindly please click the button below to create an account.

Create an account

API Key

It’s your unique authentication key that will be used to access the API. You can get your API Key from your account’s settings.

In order to authenticate your request you should add the key parameter in your request with the API Key you get from your account settings. For example:

Base URL:
https://gregeoip.com/GeoIP

Add your API Key to the key parameter just like this:

https://gregeoip.com/GeoIP?key=12345

Response

After sending a request to our API you will get a response (JSON by default). Here is an example of the full API response:

{
    "status": "success",
    "data": {
        "ip": "68.235.60.237",
        "ipType": "ipv4",
        "IPNumber": 1156267245,
        "continentName": "North America",
        "continentCode": "NA",
        "countryCode": "US",
        "countryName": "United States of America",
        "regionName": "Illinois",
        "cityName": "Chicago",
        "zipCode": "60605",
        "latitude": 41.8672,
        "longitude": -87.6259,
        "location": {
            "capital": "Washington, D.C.",
            "population": 331000000,
            "language": {
                "name": "English",
                "code": "en",
                "native": "English"
            },
            "flag": {
                "emoji": "🇺🇸",
                "unicode": "U+1F1FA U+1F1F8",
                "png": {
                    "1000px": "https://www.gredev.io/img/flags/png1000px/us.png",
                    "250px": "https://www.gredev.io/img/flags/png250px/us.png",
                    "100px": "https://www.gredev.io/img/flags/png100px/us.png"
                },
                "svg": "https://www.gredev.io/img/flags/svg/us.svg"
            },
            "phoneCode": "1",
            "countryIsEU": false,
            "tld": ".us"
        },
        "timezone": {
            "name": "America/Adak",
            "abbreviation": "HST",
            "offset": -36000,
            "currentTime": "13:28:00",
            "currentTimestamp": 1611962880,
            "isDST": false,
            "sunInfo": {
                "sunset": "13:02:07",
                "sunrise": "03:05:15",
                "transit": "08:03:41",
                "civilTwilightBegin": "02:35:40",
                "civilTwilightEnd": "13:31:42",
                "nauticalTwilightBegin": "02:02:09",
                "nauticalTwilightEnd": "14:05:13",
                "astronomicalTwilightBegin": "01:29:22",
                "astronomicalTwilightEnd": "14:38:00",
                "dayLength": "9:56:52"
            }
        },
        "currency": {
            "currencyName": "United States Dollar",
            "currencyCode": "USD",
            "currencySymbol": "$"
        },
        "security": {
            "isProxy": false,
            "isTor": false,
            "isBot": false
        },
        "device": {
            "OS": "Mac OS X",
            "isMobile": false,
            "browser": "Chrome"
        }
    }
}

HTTPS Support

This API supports HTTPS requests. No matter which plan you have (free or paid), the HTTPS protocol will be available for all users to be used in their websites/apps for free. Kindly please note that this API DOES NOT support HTTP protocol.

Error Codes

In case an error occured while sending a request to our API, you will get an error response. The error response contains code, type and description. Let us show you an example of the error response:

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

The following table contains all the possible error codes you need to learn about:

Code Type Description
101 invalid_key The API Key is missing or invalid.
102 inactive_user The API Key owner (the account) is inactive right now. Kindly please contact the support team for more information.
103 limit_reached You reached the limit of your plan for this month. Please change your account’s plan or wait this month to end.
104 invalid_parms Please check out the parms parameter’s value.
105 plan_expired Your plan has been expired. Please renew required to enable using the API.
106 flood_detected Our system has detected too many requests in the same time. Kindly please try to slow down.
107 invalid_callback_name The value of the callback parameter cannot be a funtion name.
108 invalid_format The value of format parameter is not a valid format. Use JSON, XML or Newline.
109 callback_not_allowd You can use the callback feature only with the JSON format.
110 invalid_language The value of lang parameter is not a valid format. Use EN, AR, FR, DE, ES, JA, ZH or RU.
111 invalid_mode The value of mode parameter is not a valid format. Use test or live.
112 invalid_ip The IP Address is not valid or empty.
113 domain_not_whitelisted You are sending the request from a domain which is not the domain name you set in the API settings of your account’s dashboard.
114 security_module_not_allowed You cannot use the security module in the free plan. Please upgrade your API plan to unlock this feature.
115 ip_verstion_not_supported The IP verstion is not IPv4, which is not supported at the moment.

Usage Limits

The only limit you have is the number of requests you can send through the current month. So, all you need to do is using the API in accordance with the available requests you have for this month. Note that you can check your API usage in real-time from your account’s dashboard.

Additional Information

• This API can be used to retrieve vistors/users IP and it’s full information (e.g: location, timezone, currency, device, browser and security threats). And it can be also used to retrieve an IP full information (without retrieving the current IP of the visitor/user).
• All the options can be used for each method of this API (If there’s difference we will mention it in the method description page).
• This API does not support HTTP requests. You should use HTTPS all the time.

Custom Modules Response

You can use the API be specifying the needed modules only (except the basic modules). For example, you can get only the user device information without getting the timezone. This can be done by passing the parms parameter to the request, just like this:

https://gregeoip.com/GeoIP?key=12345&parms=security
You can also pass multiple modules to the parameter by seperate the needed modules with comma:

https://gregeoip.com/GeoIP?key=12345&parms=timezone,currency,security
Here is a list of the possible values you can use:

Module Description
security Retrieves the security threats of an IP Address.
timezone Retrieves the timezone information from the IP Address location.
currency This can be used to get more information about the user country’s currency such as the currency simbol and it’s name.
device Use this value to get the device information of your visitors, such as the browser and the operation system.
Note: this option can be used for all GeoIP modules (GeoIP & IPLookup).

Response Format

You can change the format of the API responses easily. Just pass the format parameter to the request with the format type you want.

The available formats are: JSON, XML, CSV and Newline.

The JSON is the default format. So, there’s no need to add this parameter if you want the response format to be in JSON.

https://gregeoip.com/GeoIP?key=12345&parms=country_name&format=JSON
https://gregeoip.com/GeoIP?key=12345&parms=country_name&format=XML
https://gregeoip.com/GeoIP?key=12345&parms=country_name&format=CSV
https://gregeoip.com/GeoIP?key=12345&parms=country_name&format=Newline

Localization

You can retrieve the response in your language! We’re working hard to add more languages to our API.

You can simply add the lang parameter to the request, so you will get the response in the language you choose. Currently, we support EN, AR, DE, FR, ES, JA, ZH and RU.

Please not that only countryName, continentName and language.name fields will be translated from the response. Please check out the following example:

https://gregeoip.com/GeoIP?key=12345&parms=location,currency&lang=AR
Response:

{
    "status": "success",
    "data": {
        "ip": "68.235.60.237",
        "ipType": "ipv4",
        "IPNumber": 1156267245,
        "continentName": "أمريكا الشمالية",