Interfejs programistyczny

Spis treści

  1. Informacje
  2. Parametry
    1. Format
    2. IP
  3. Odpowiedzi
    1. Odpowiedź poprawna
    2. Odpowiedź pusta
    3. Błąd
  4. Przykłady
    1. PHP
    2. XML
    3. JS
    4. JSON
    5. JSONP
    6. TXT
  5. 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:

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

© 2015 by Jacekk.net