Tier 2 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/
This wiki page is a clone of the ?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 (=).
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 | 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 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/.