API - IP2geo.pl

Interfejs programistyczny

Spis treści

Informacje
Parametry
1. Format
2. IP
Odpowiedzi
Przykłady
1. PHP
2. XML
3. JS
4. JSON
5. JSONP
6. TXT
Regulamin

Informacje

W celu uzyskania informacji o lokalizacji danego adresu IP można wykorzystać specjalny interfejs API, dostępny pod adresem:

http://api.ip2geo.pl/[FORMAT]/?ip=[IP]

API jest dostępne również po protokole HTTPS.

Parametry

Format

Parametr [FORMAT] określa rodzaj odpowiedzi serwera - możliwe wartości to:

php: zserializowana tablica asocjacyjna
xml: dokument XML ^[CORS]
js: skrypt JavaScript tworzący asocjacyjną tablicę globalną o zadanej nazwie^[1]
json: tablica indeksowana asocjacyjnie, zapisana w formacie JavaScript Object Notation ^[CORS]
jsonp: skrypt JavaScript wywołujący zadaną funkcję^[2] z lokalizacją jako argumentem
txt: plik tekstowy, w każdej linii jedna para: klucz|wartość

^[CORS] Metoda pozwala na zdalne żądania AJAX, zgodnie z CORS.

^[1] Domyślna nazwa to dane. Można ją zmienić przekazując nową nazwę w parametrze var, np. http://api.ip2geo.pl/js/?var=nowaNazwa. Nazwa musi spełniać wyrażenie regularne: ^[$a-zA-Z_][0-9a-zA-Z_$]{0,19}$

^[2] Domyślna nazwa to callback. Można ją zmienić przekazując nową nazwę w parametrze jsonp, np. http://api.ip2geo.pl/jsonp/?jsonp=nowaNazwa. Nazwa musi spełniać wyrażenie regularne: ^[$a-zA-Z_][0-9a-zA-Z_$]{0,19}$

IP

Parametr [IP] określa adres IPv4, dla którego system ma odnaleźć lokalizację. W przypadku pominięcia pola lub błędnej jego wartości, system zastępuje je adresem IP klienta.

Odpowiedzi

W każdym przypadku API powinno zwrócić kod HTTP 200. Jakikolwiek inny kod winien być traktowany jak błąd - w takim przypadku odpowiedź może nie być we właściwym formacie.

Odpowiedź poprawna

Odpowiedź poprawna zawiera jedno lub więcej pól z poniższej listy, zapisanych w kodowaniu UTF-8:

db (string): baza danych, w której znaleziono rekord (MaxMind, ip2geo.pl)
country (string): dwuliterowy kod kraju
city (string): miasto
lat (float): szerokość geograficzna - wartość z zakresu od -90 do 0 dla szerokości geograficznych południowych lub od 0 do 90 dla szerokości geograficznych północnych
lon (float): długość geograficzna - wartość z zakresu od -180 do 0 dla długości geograficznych zachodnich lub od 0 do 180 dla długości geograficznych wschodnich
proxy (bool): klucz występuje, gdy użytkownik łączy się przez IP znanej usługi proxy
satellite (bool): użytkownik łączy się z internetem przez satelitę

Odpowiedź pusta

Jeśli w bazie danych nie odnaleziono wybranego adresu zwracana jest pusta tablica (w przypadku XML - element główny bez potomków).

Błąd

W przypadku wystąpienia błędu zwracany jest plik z następującymi polami:

errcode (int): Kod błędu
err (string): Treść komunikatu o błędzie

Znane kody błędów:

0: Nieznany problem z bazą danych
477: Podany adres IP pochodzi z puli adresów unicast/multicast
478: Podany adres IP pochodzi z puli adresów zarezerwowanych przez IANA
479: Podany adres IP pochodzi z puli adresów prywatnych
503: Przekrocznie ilości dozwolonych zapytań

Przykłady

PHP

Możliwe odpowiedzi:

Odpowiedź poprawna:

a:4:{s:7:"country";s:2:"PL";s:4:"city";s:6:"Krakow";s:3:"lat";d:50.0833;s:3:"lon";d:19.9167;}

Odpowiedź pusta:

a:0:{}

Błąd:

a:2:{s:7:"errcode";i:0;s:3:"err";s:16:"Nieznany problem";}

Kod podający kraj użytkownika (PHP):

Uwaga! Poniższy kod może nie być bezpieczny! W normalnych zastosowaniach skorzystaj z przykładu użycia API JSON.

<?php
$dane = unserialize(
    file_get_contents(
        'http://api.ip2geo.pl/php/?ip='.$_SERVER['REMOTE_ADDR']
    )
);
if(isset($dane['country'])) {
    echo 'Kraj: '.$dane['country']."\n";
}
?>

XML

Możliwe odpowiedzi:

Odpowiedź poprawna:

<ip2geo>
    <country>PL</country>
    <city>Krakow</city>
    <lat>50.0833</lon>
    <lon>19.9167</lat>
</ip2geo>

Odpowiedź pusta:

<ip2geo/>

Błąd:

<ip2geo>
    <errcode>0</errcode>
    <err>Nieznany problem</err>
</ip2geo>

Kod podający kraj użytkownika (PHP):

<?php
$data = file_get_contents(
    'http://api.ip2geo.pl/xml/?ip='.$_SERVER['REMOTE_ADDR']
);
$prevState = libxml_disable_entity_loader(TRUE);
$data = simplexml_load_string($data);
libxml_disable_entity_loader($prevState);

if($data->country) {
    echo 'Kraj: '.$data->country."\n";
}
?>

Kod podający kraj użytkownika (JavaScript):

<p>Kraj: <span id="country"></span></p>
<script type="text/javascript">
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://api.ip2geo.pl/xml/', true);
xhr.onreadystatechange = function (event) {
    if (xhr.readyState == 4 && xhr.status == 200 && xhr.responseXML) {
        var location = xhr.responseXML.getElementsByTagName('country');
        if(location.length > 0) {
            document.getElementById('country').appendChild(
                document.createTextNode(location[0].textContent)
            );
        }
    }
};
xhr.send();
</script>

JS

Możliwe odpowiedzi:

Informacja. Nazwa zmiennej może być zmieniana parametrem var

Odpowiedź poprawna:

var dane = {"db":"MaxMind","country":"PL","city":"Krakow","lat":"50.0833","lon":"19.9167"};

Odpowiedź pusta:

var dane = [];

Błąd:

var dane = {"errcode":"0","err":"Nieznany problem"};

Kod podający kraj użytkownika (JavaScript):

<p>Kraj: <span id="country"></span></p>
<script type="text/javascript" src="http://api.ip2geo.pl/js/?var=data"></script>
<script type="text/javascript">
if(data['country']) {
    document.getElementById('country').appendChild(
        document.createTextNode(data['country'])
    );
}
</script>

JSON

Możliwe odpowiedzi:

Odpowiedź poprawna:

{"country":"PL","city":"Krakow","lat":50.0833,"lon":19.9167}

Odpowiedź pusta:

[]

Błąd:

{"errcode":0,"err":"Nieznany problem"}

Kod podający kraj użytkownika (PHP):

<?php
$data = json_decode(
    file_get_contents(
        'http://api.ip2geo.pl/json/?ip='.$_SERVER['REMOTE_ADDR']
    )
);
if(isset($data->country)) {
    echo 'Kraj: '.$data->country."\n";
}
?>

Kod podający kraj użytkownika (JavaScript):

<p>Kraj: <span id="country"></span></p>
<script type="text/javascript">
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://api.ip2geo.pl/json/', true);
xhr.onreadystatechange = function (event) {
    if (xhr.readyState == 4 && xhr.status == 200 && xhr.response) {
        var location = JSON.parse(xhr.responseText);
        if(location.country) {
            document.getElementById('country').appendChild(
                document.createTextNode(location.country)
            );
        }
    }
};
xhr.send();
</script>

JSONP

Możliwe odpowiedzi:

Informacja. Nazwa wywoływanej funkcji może być zmieniana parametrem jsonp

Odpowiedź poprawna:

callback({"country":"PL","city":"Krakow","lat":50.0833,"lon":19.9167});

Odpowiedź pusta:

callback([]);

Błąd:

callback({"errcode":0,"err":"Nieznany problem"});

Kod podający kraj użytkownika (JavaScript):

<p>Kraj: <span id="country"></span></p>
<script type="text/javascript">
function callback_ip2geo(data) {
    if(data['country']) {
        document.getElementById('country').appendChild(
            document.createTextNode(data['country'])
        );
    }
}
</script>
<script type="text/javascript" src="http://api.ip2geo.pl/jsonp/?jsonp=callback_ip2geo"></script>

TXT

Możliwe odpowiedzi:

Odpowiedź poprawna:

country|PL
city|Krakow
lat|50.0833
lon|19.9167

Odpowiedź pusta:

Błąd:

errcode|0
err|Nieznany problem

Regulamin

Zabrania się wykorzystywania usługi w celu:

osiągnięcia zarobku lub innego wykorzystania komercyjnego
dostarczania reklam w zależności od lokalizacji użytkownika
dalszego rozpowszechniania bazy lub jej części, za wyjątkiem przypadków wskazanych w Ustawie o ochronie baz danych oraz licencjach, na których udostępniane są poszczególne zbiory

Zastrzegamy sobie prawo ograniczenia ilości odpowiedzi interfejsu API do 1 000 w ciągu 1 dnia dla 1 adresu IP.