REST API

REST API allows you to get the most current and advanced IP information using the latest Sypex Geo Max database using a simple request over HTTP or HTTPS.

Each user without registration is provided with 10,000 requests per month (identification by IP and REFERER). When registering on the site, a unique key is issued to record requests, and bonus requests are added to the account (30 000 per month). Unused bonus requests do not carry over to the next month. At the same time, paid requests have no time limits. For users who purchased requests, free bonus requests are used up first, and after they are finished, paid ones begin to be used up. Thus, if you have 40,000 requests per month, then a portion of 100 thousand paid requests will last you 10 months.

REST API allows you to receive data in JSON, JSONP, XML and MessagePack formats. All data is encoded in UTF-8. In one request you can obtain information from up to 100 IPs. Please note that in batch mode (when more than one IP is requested at a time), requests will be charged for each IP address in the packet.

Description

Send a GET request to

api.sypexgeo.net/{format}/[{ip}][?callback={callback}]

or to one of the regional servers, for example, a server in Moscow 

ru.sxgeo.city/{format}/[{ip}][?callback={callback}]

API supports HTTP and HTTPS requests.

Supported formats are xml, json, jsonp and msg.

In ip you can specify either one IPv4 or several IPv4 separated by a comma, semicolon, space or line feed.

If no IP is specified, information about your IP is displayed, from which the request to the API is made.

callback - the JSON response is wrapped in a callback function. If the callback function is not specified, then the console.dir function is automatically added.

You can also use POST requests, in which case the required IPs must be specified in the ip parameter.

For registered users, the key is specified:

api.sypexgeo.net/{key}/{format}/[{ip}][?callback={callback}]

Attention! Be sure to take into account that not only ordinary visitors, but also search bots visit the site , which can create many requests to the site and, accordingly, to the API.

Therefore, be sure to filter requests from search bots. This can be done with a simple regular expression, like:

<?php
// We filter bots so that there are no unnecessary requests to the API
$is_bot = empty($_SERVER['HTTP_USER_AGENT']) || preg_match(
 "~(Google|Yahoo|Rambler|Bot|Yandex|Spider|Snoopy|Crawler|Finder|Mail|curl|request|Guzzle|Java)~i",
 $_SERVER['HTTP_USER_AGENT']
);
$geo = !$is_bot ? json_decode(
 file_get_contents('http://api.sypexgeo.net/json/' . $_SERVER['REMOTE_ADDR']),
 true) : [];
// All IP data
print_r($geo);

// Select the required data
if ($is_bot) {
 echo 'Hello Google Bot, and other bots';
}
elseif ($geo->country->iso == 'UA'){
 switch($geo->city->name_en) {
 case 'Kyiv': echo 'Your city - Kyiv'; break;
 case 'Lviv': echo 'Your city is Lviv'; break;
 default: echo 'Another city in Ukraine';
 }
}
else {
 echo 'You are not from Ukraine';
}

You should also cache query results for users, so that when a user visits 100 pages of the site, you do not make 100 requests to the API.

Sypex Geo API regional servers

In 2016, additional Sypex Geo API servers were launched. Servers are located in different countries and cities. Thanks to this, you can significantly reduce the ping to the server, and, accordingly, the time to access the API.

There are currently 14 servers available:

Eastern Europe and Asia:

  • ua.sxgeo.city - Ukraine, Khmelnitsky (GMhost)
  • ru.sxgeo.city - Russia, Moscow (Ihor)
  • ru2.sxgeo.city - Russia, St. Petersburg (Vscale)
  • ru3.sxgeo.city - Russia, Ekaterinburg (NetAngels)

Western Europe:

  • de.sxgeo.city - Germany, Falkenstein (Hetzner)
  • nl.sxgeo.city - Netherlands, Amsterdam (Vultr)
  • fr.sxgeo.city - France, Gravelines (OVH)
  • it.sxgeo.city - Italy, Arezzo (ArubaCloud)
  • uk.sxgeo.city - England, London (ArubaCloud)

North America:

Asia:

  • jp.sxgeo.city - Japan, Tokyo (Amazon)
  • sg.sxgeo.city - Singapore (Amazon)

Usage Examples

GET http://api.sypexgeo.net/

Outputs information about your IP in JSON.

GET http://api.sypexgeo.net/json/123.45.67.89

Outputs information in JSON about IP 123.45.67.89.

GET http://api.sypexgeo.net/json/123.45.67.89,12.34.56.78

Outputs information in JSON about IP 123.45.67.89 and 12.34.56.78.

GET http://api.sypexgeo.net/xml/123.45.67.89

Outputs information in XML about IP 123.45.67.89.

GET http://api.sypexgeo.net/jsonp/123.45.67.89?callback=alert

Outputs information in JSONP about IP 123.45.67.89, with the alert callback function.

Example results

Result of calling the API in JSON

GET http://api.sypexgeo.net/json/123.45.67.89
{"ip":"123.45.67.89",
"city":{"id":1835848,"lat":37.566,"lon":126.9784,
 "name_ru":"Сеул","name_en":"Seoul","okato":""},
"region":{"id":1835847,"lat":37.58,"lon":127,"name_ru":"Сеул",
 "name_en":"Seoul","iso":"KR-11","timezone":"Asia/Seoul","okato":""
},
"country":{"id":119,"iso":"KR","continent":"AS","lat":36.5,"lon":127.75,
 "name_ru":"Южная Корея","name_en":"South Korea","timezone":"Asia/Seoul"
}}

Result of API call in XML

GET http://api.sypexgeo.net/xml/123.45.67.89
<?xml version="1.0" encoding="UTF-8"?>
<sxgeo>
<ip num="123.45.67.89">
<city>
<id>1835848</id>
<lat>37.566</lat>
<lon>126.9784</lon>
<name_ru>Сеул</name_ru>
<name_en>Seoul</name_en>
<okato></okato>
</city>
<region>
<id>1835847</id>
<lat>37.58</lat>
<lon>127</lon>
<name_ru>Сеул</name_ru>
<name_en>Seoul</name_en>
<iso>KR-11</iso>
<timezone>Asia/Seoul</timezone>
<okato></okato>
</region>
<country>
<id>119</id>
<iso>KR</iso>
<continent>AS</continent>
<lat>36.5</lat>
<lon>127.75</lon>
<name_ru>Южная Корея</name_ru>
<name_en>South Korea</name_en>
<timezone>Asia/Seoul</timezone>
</country>
</ip>
</sxgeo>