Documenttion

Documentation

Using IP GEO API you can get the location information of your visitors based on the IP address. We support both IPv4 and IPv6 addresses. This API provides the response in json and xml formats.

If you have any questions that are not coved by this documentation, please feel free to contact us.

Authentication

To use an API you must have an API key. You can find it in the dashboard after the registration.

You can authenticate in the two following ways:

1. Passing an API Key via Query Parameter

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/check?api-key={YOUR API KEY}'

2. Passing an API Key via Header

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/check' \
     --header 'api-key: {YOUR API KEY}'

Specific IP Lookup

IP Lookup returns geo location data of any provided IPv4 or IPv6 address.

Endpoint

https://api.getgeoapi.com/v2/ip/{ip}
?api-key={api-key}&format={format}&filter={filter}&language={language}

Example

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/37.140.128.10?format=json&language=en' \
     --header 'api-key: {YOUR API KEY}'

Request parameters

Parameter	Description
ip (required)	Any IPv4 or IPv6 address
api-key (required)	Api Key that every registered user has and can be found in the Dashboard
format (optional)	Specifies the output format. It can be json or xml
filter (optional)	Filter the response and get only the required data. Options: asn, city, country, continent, area, currency, security, time, postcode. Can be comma separated.
language (optional)	Return data in one of the following languages: en,ru,zh,es,ar,fr,fa,ja,pl,it,pt,de

Go to the section IP Lookup Response to see the example of the response.

Visitor's IP Lookup

Visitor's IP Lookup return the IP address and the location data of the client.

Endpoint

https://api.getgeoapi.com/v2/ip/check
?api-key={api-key}&format={format}&filter={filter}&language={language}

Example

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/check?format=json&language=en' \
     --header 'api-key: {YOUR API KEY}'

Request parameters

Parameter	Description
api-key (required)	Api Key that every registered user has and can be found in the Dashboard
format (optional)	Specifies the output format. It can be json or xml
filter (optional)	Filter the response and get only the required data. Options: asn, city, country, continent, area, currency, security, time, postcode. Can be comma separated.
language (optional)	Return data in one of the following languages: en,ru,zh,es,ar,fr,fa,ja,pl,it,pt,de

Go to the section IP Lookup Response to see the example of the response.

Response example

For the following request

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/check?format=json&language=en' \
     --header 'api-key: {YOUR API KEY}'

the response will be as shown below

{
    "status": "success",
    "ip":"37.140.128.10",
    "type":"IPv4",
    "city":{
        "geonameid":524901,
        "name":"Moscow",
        "population":10381222
    },
    "area":{
        "code":"RU-MOW",
        "geonameid":524894,
        "name":"Moscow"
    },
    "country":{
        "code":"RU",
        "name":"Russia",
        "phone_code":"7",
        "area_size":"17100000.00 sq. km",
        "capital":"Moscow",
        "population":140702000,
        "geonameid":2017370,
        "is_in_eu":false,
        "flag":{
          "emoji":"🇷🇺",
          "file":"http://commons.wikimedia.org/wiki/Special:FilePath/Flag_of_Russia.svg",
          "unicode":"U+1F1F7 U+1F1FA"
        }
        "languages": {
          "ru": "Russian",
    },
    "time":{
        "timezone":"Europe/Moscow",
        "time":"2019-01-24 15:17:07 +0300",
        "gtm_offset": 10800
    },
    "asn":{
        "organisation":"YANDEX LLC",
        "number":13238
    },
    "currency":{
        "code":"RUB",
        "name":"Russian Ruble"
    },
    "location":{
        "latitude":55.7522,
        "longitude":37.6156
    },
    "security":{
        "is_tor":false,
        "is_proxy":false,
        "is_thread":false,
        "is_crawler":false
    },
    "continent":{
        "geonameid":6255148,
        "code":"EU",
        "name":"Europe"
    },
    "postcode":"102087"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>success</status>
    <ip>37.140.128.10</ip>
    <type>IPv4</type>
    <city>
        <geonameid>524901</geonameid>
        <name>Moscow</name>
        <population>10381222</population>
    </city>
    <area>
        <geonameid>524894</geonameid>
        <code>RU-MOW</code>
        <name>Moscow</name>
    </area>
    <country>
        <geonameid>2017370</geonameid>
        <code>RU</code>
        <name>Russia</name>
        <phone_code>7</phone_code>
        <area_size>17100000.00 sq. km</area_size>
        <capital>Moscow</capital>
        <population>140702000</population>
        <is_in_eu>False</is_in_eu>
        <flag>
            <emoji>🇷🇺</emoji>
            <file>http://commons.wikimedia.org/wiki/Special:FilePath/Flag_of_Russia.svg</file>
            <unicode>U+1F1F7 U+1F1FA</unicode>
        </flag>
        <languages>
            <ru>Russian</ru>
        </languages>
    </country>
    <time>
        <timezone>Europe/Moscow</timezone>
        <time>2019-01-24 15:36:10 +0300</time>
        <gtm_offset>10800</time>
    </time>
    <asn>
        <organisation>YANDEX LLC</organisation>
        <number>13238</number>
    </asn>
    <currency>
        <code>RUB</code>
        <name>Russian Ruble</name>
    </currency>
    <location>
        <latitude>55.7522</latitude>
        <longitude>37.6156</longitude>
    </location>
    <security>
        <is_tor>False</is_tor>
        <is_proxy>False</is_proxy>
        <is_thread>False</is_thread>
        <is_crawler>False</is_crawler>
    </security>
    <continent>
        <geonameid>6255148</geonameid>
        <code>EU</code>
        <name>Europe</name>
    </continent>
    <postcode>102087</postcode>
</root>

Response object

Property	Description
status	Returns the status of the request. Can be 'success' or 'fail'
ip	Returns the requested IP address
type	Returns the type of the requested IP address. Can be IPv4 or IPv6
city -> name	Returns the name of the city of the requested IP address or empty value.
city -> geonameid	Returns the id of the record in the geonames database.
city -> population	Returns the population of the city of the requested IP address or empty value.
area -> code	Returns the region or area code of the requested IP address or empty value.
area -> geonameid	Returns the id of the record in the geonames database.
area -> name	Returns the region or area name of the requested IP address or empty value.
country -> code	Returns the country code of the requested IP address or empty value.
country -> geonameid	Returns the id of the record in the geonames database.
country -> name	Returns the country name of the requested IP address or empty value.
country -> phone_code	Returns the country phone number prefix of the requested IP address or empty value.
country -> area_size	Returns the country size in sq. km. of the requested IP address or empty value.
country -> capital	Returns the country capital of the requested IP address or empty value.
country -> population	Returns the country population of the requested IP address or empty value.
country -> is_in_eu	Returns true if the country of the requested IP is in Euro Union .
country -> flag -> emoji	Returns the emoji of the country flag .
country -> flag -> file	Returns the url of the file of the country flag in wikipedia.
country -> flag -> unicode	Returns the unicode of the country flag.
country -> languages	Returns a list of languages spoken in the country.
time -> timezone	Returns timezone of the requested IP address or empty value.
time -> time	Returns local time of the requested IP address or empty value.
time -> gtm_offset	Returns GTM offset in seconds
asn -> organisation	Returns company name of the requested IP address or empty value.
asn -> number	Returns Autonomous System Number of the requested IP address or empty value.
currency -> code	Returns local currency code of the requested IP address or empty value.
currency -> name	Returns local currency name of the requested IP address or empty value.
location -> latitude	Returns latitude of the requested IP address or empty value.
location -> longitude	Returns longitude of the requested IP address or empty value.
security -> is_tor	Returns true if the requested IP address is tor.
security -> is_proxy	Returns true if the requested IP address is proxy.
security -> is_thread	Returns true if the requested IP address is known to be as thread.
security -> is_crawler	Returns true if the requested IP address is crawler.
continent -> code	Returns continent code of the requested IP address or empty value.
continent -> geonameid	Returns the id of the record in the geonames database.
continent -> name	Returns continent code of the requested IP address or empty value.
postcode	Returns postal code of the requested IP address or empty value.

In case the request fails or the resource is not available the error will be returned in JSON or XML format.

Error response example

{
    "status":"failed",
    "error":{
        "message":"Invalid key.",
        "code":"403"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<root>
    <status>failed</status>
    <error>
        <message>Invalid key.</message>
        <code>403</code>
    </error>
</root>

Error codes

Code	Description
400	Bad request.
403	Authentication credentials were not provided. Invalid key. You reached the limit of your requests. User is not active. Please use the link in the email to activate the user.
404	Resource is not found or requested format is incorrect
405	Method is not allowed.
500	Server error. We hope you will never see this error.

Code Examples

Below you can see some code examples.

Python


import requests

url = "https://api.getgeoapi.com/v2/ip/check?format=json"

headers = {'api-key': "****************"}

response = requests.request("GET", url, headers=headers)

print(response.text)

PHP


<?php

$request = new HttpRequest();
$request->setUrl('https://api.getgeoapi.com/v2/ip/check');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(['format' => 'json']);

$request->setHeaders(['api-key' => '****************']);

$response = $request->send();
echo $response->getBody();

Ruby

			
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.getgeoapi.com/v2/ip/check?format=json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["api-key"] = '****************'

response = http.request(request)
puts response.read_body

GO


package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.getgeoapi.com/v2/ip/check?format=json"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api-key", "****************")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

Curl

curl --request GET \
     --url 'https://api.getgeoapi.com/v2/ip/check?format=json&language=en' \
     --header 'api-key: ****************'

Node JS


var unirest = require("unirest");

var req = unirest("GET", "https://api.getgeoapi.com/v2/ip/check");

req.query({"format": "json"});

req.headers({
	"api-key": "****************",
	"useQueryString": true
});

req.end(function (res) {
	console.log(res.body);
});