Tier 2 GeoIP API [OpenNIC Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Tier 2 GeoIP API =======
The GeoIP API returns a list of the nearest OpenNIC [[opennic:tier2|Tier 2]] servers.

===== The API =====
The APIs base URL is at https://api.opennicproject.org/geoip/

This wiki page is a clone of the [[https://api.opennicproject.org/geoip/?help|?help page]] with some fancy tables and extra glitter.

===== 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 (''='').

Example: ''https://api.opennicproject.org/geoip/?list&adm=3''

==== 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 | <code>87.98.175.85 # ns10.fr # 98.65%
62.113.203.55 # ns1.de # 99.41%</code> |
^ bare | Only list the server IP addresses | <code>87.98.175.85
62.113.203.55</code> |
^ ns | Create a list of nameservers | <code>nameserver 87.98.175.85     # (98.65%) ns10.fr (wil)
nameserver 62.113.203.55    # (99.41%) ns1.de (dfroe)</code> |
^ resolv | Provide a useable resolv.conf file | <code># 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)</code> |
^ json | Generate JSON data | <code>[{"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"},...]</code> |
^ jsonp | Generate a JSON array | <code>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"},...]);</code> |

==== 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 | false | Randomize the returned server order |
^ wl | all | none | Include whitelist servers in the results. \\ If you specify wl=all, ONLY whitelist servers will be shown. |
^ bl | | | Include blocklist servers in the results |
^ anon | true | false | Return servers with anonymized logs only |


==== 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 |

===== Known issues =====
The GeoIP API is known to report servers in an inaccurate or wrong location. The GeoIP API uses [[https://www.maxmind.com/|MaxMinds GeoIP database]] to look up the physical location of IP addresses, which is not always accurate. Due to this reason, it is always better to manually pick some near servers from https://servers.opennicproject.org/.