Skip to content

Endpoints

Jump to bottom
Lagicrus edited this page Aug 13, 2018 · 21 revisions

Endpoint list

ip/info route

This is an API route that is designed to take a GET request from the user in a JSON request structured that only contains either a single IP or multiple IPs in a list.

Single Request

In the case of a single IP address the format looks either like this in the case of a JSON body request made using python's request library

requests.get("http://localhost/ip/info", json={"ip": "127.0.0.1"})

OR This in the case of using URL arguments

requests.get("http://localhost/ip/info", params={"ip": "127.0.0.1"})

which is the same as

requests.get("http://localhost/ip/info?ip=127.0.0.1")

and you will get a similar response back with the JSON being structured like

{"127.0.0.1": 
    {"global": false,
    "loopback": false,
    "max_prefixlen": 32,
    "multicast": false,
    "link_lokal": false,
    "private": true,
    "reserverd": false,
    "reverse_pointer": "200.2.168.192.in-addr.arpa",
    "unspecified": false,
    "version": 4,
    "city": "??",
    "country": "??",
    "country_code": "??",
    "region": "??",
    "org": "??"}
}

Where the layout is described here

Multiple Requests

In the case of wanting to submit multiple IPs at once, the format looks either like this in the case of a JSON body request made using python's request library

requests.get("http://localhost/ip/info", json={"addresses": ["127.0.0.1", "0.0.0.0"]})

OR This in the case of using URL arguments

requests.get("http://localhost/ip/info", params={"addresses": "127.0.0.1 0.0.0.0"})

which is the same as

requests.get("http://localhost/ip/info?ip=127.0.0.1+0.0.0.0")

and you will get a similar response back with the JSON being structured like

{"0.0.0.0": {"city": "??",
             "country": "??",
             "country_code": "??",
             "global": false,
             "link_local": false,
             "loopback": false,
             "max_prefixlen": 32,
             "multicast": false,
             "org": "??",
             "private": true,
             "region": "??",
             "reserved": false,
             "reverse_pointer": "0.0.0.0.in-addr.arpa",
             "unspecified": true,
             "version": 4},
 "127.0.0.1": {"city": "??",
               "country": "??",
               "country_code": "??",
               "global": false,
               "link_local": false,
               "loopback": true,
               "max_prefixlen": 32,
               "multicast": false,
               "org": "??",
               "private": true,
               "region": "??",
               "reserved": false,
               "reverse_pointer": "1.0.0.127.in-addr.arpa",
               "unspecified": false,
               "version": 4}}

Where the layout is described here

ip data structure

For "global", "link_local", "max_prefixlen", "multicast", "org", "private", "reserved", "reverse_pointer", "unspecified", and "version". Please refer to the ip_address docs where they are explained in detail. Note, "packed" is not included due to the large amount of bugs/issues it presented to the code with, in my opinion, little to no use to the end user when it can be generated on their end.

The "country_code" part of the JSON is the 2 digit country code which follows the ISO2 standard which can be found described here or from the JSON I use found here

The "country" part of the JSON is the real world equivalent to the "country_code" described above which uses the JSON table here to convert it back and forth.

The "city" part of the JSON is the real world city that we think of where the IP address is located.

The "region" part of the JSON is the real world region of where we think that the IP address is located.

The "org" part of the JSON is what who is believed to own that IP address.

The "last_updated" part of the JSON is the EPOCH time of when that data was last updated on the server. This is updated on the server when a request is made for that data and the last updated time is greater than 2628288 aka

365 / 12 = 30.42

30.42 * 86400 = 2628288

The "amount_checked" part of the JSON is simply a count (including that request's) of the amount of time that IP has been queried.

stats Endpoint

This GET based endpoint is based around getting statistics from the database. If you send a simple GET request to this endpoint you will get a JSON structured like

{"US": {"country": "United States",
           "lookups": "10",
           "stored_ips": "10"},
{"FR": {"country": "France",
           "lookups": "10",
           "stored_ips": "10"},

The names are the ISO2 translated versions of what is stored in the database. For that reason, GB is the United Kingdom and not the UK, for example.

If you use arguments in the URL such as

requests.get("http://localhost/ip/stats?country=US")

Then you will get returned a JSON structured like

{"US": {"country": "United States",
           "lookups": "10",
           "stored_ips": "10"}

The name is the ISO2 translated equivalent of what you sent in the argument with the number of IPs that come from that IP stated after. You can also request multiple countries in one command using

requests.get("http://localhost/ip/stats?country=US&country=FR")

or

requests.get("http://localhost/ip/stats?country=US+FR")

Which will return a JSON structured like

{"United States": 180, "France": 81}
Clone this wiki locally