This is an old revision of the document!
GeoIP API
The GeoIP API returns a list of the nearest OpenNIC Tier 2 servers.
The API
The APIs base URL is at https://api.opennicproject.org/geoip/
URL Parameters
URL Parameters are appended to the base URL separated by a question mark (?
), all parameters are separated by ampersand (&
), parameter key/value pairs are separated by an equal sign (=
).
Result parameters
These parameters define how the API formats the resulting information. They are mutually exclusive, don't accept any value and don't require an equal sign (=
) as a key/value pair separator.
Parameter | Function | Example |
---|---|---|
list | (default) List servers including name and reliability | 87.98.175.85 # ns10.fr # 98.65% 62.113.203.55 # ns1.de # 99.41% |
bare | Only list the server IP addresses | 87.98.175.85 62.113.203.55 |
ns | Create a list of nameservers | nameserver 87.98.175.85 # (98.65%) ns10.fr (wil) nameserver 62.113.203.55 # (99.41%) ns1.de (dfroe) |
resolv | Provide a useable resolv.conf file | # This file was generated by OpenNIC 2017-Jul-04 22:32 UTC # and shows the most reliable servers near you. # You may retrieve updates automatically by using: # wget --inet4-only "https://api.opennicproject.org/geoip?resolv" domain opennic.glue search opennic.glue nameserver 87.98.175.85 # (98.65%) ns10.fr (wil) nameserver 62.113.203.55 # (99.41%) ns1.de (dfroe) |
json | Generate JSON data | [{"host":"ns10.fr.dns.opennic.glue","short":"ns10.fr","ip":"87.98.175.85","loc":"FR","miles":617,"kilometers":993,"stat":"98.65","manager":"wil"},...] |
jsonp | Generate a JSON array | opennic([{"host":"ns10.fr.dns.opennic.glue","short":"ns10.fr","ip":"87.98.175.85","loc":"FR","miles":617,"kilometers":993,"stat":"98.65","manager":"wil"},...]); |
Variable parameters
These parameters define what data is returned.
Parameter | Example Value 1 | Example Value 2 | Description |
---|---|---|---|
adm | 2 | 5 | The first x servers will have unique admins (Defaults to 66% of the list) |
ip | 1.2.3.4 | 123.45.67.89 | Provide servers nearest the given IP address |
res | 2 | 5 | Change the number of results |
pct | 95 | 50 | (default=95) Change the threshold percentage for acceptable server reliability, given as a whole integer |
lat | 50 | -33.45 | Set the reference latitude for your location |
lon | -50 | 33.45 | Set the reference longitude for your location |
ipv | 4 | 6 | Specify which class of IP addresses to return. 4 - Only list IPv4 servers 6 - Only list IPv6 servers all - Include both IPv4 and IPv6 servers |
rnd | true | Randomize the returned server order (omit this parameter to disable randomization) | |
wl | all | none | Include whitelist servers in the results. If you specify wl=all, ONLY whitelist servers will be shown. |
Examples
?json | Output JSON data |
?resolv&res=5 | Generate a resolv.conf file with 5 nameservers |
?res=8&bare&pct=90 | Return a list of 8 IP addresses where the servers have a reliability of 90% or greater |
?res=4&adm=4&wl | Return a list of 4 servers from 4 different admins, including whitelist servers |