API Information

The IP API is generally free to use, but we ask you to obey the rules laid out here

⚠ CAUTION ⚠

If you plan on using these ranges to block them in your firewall, be very careful.
  • Some range types (country code "__" and ASN "0") contain special purpose addresses, including private IP addresses you encounter in a LAN. Blocking them will likely cause unintended consequences and may break services such as VPNs, packet filters, DHCP, and DNS.
  • Make sure you don't accidentally block yourself. Be sure you have means to access the console directly (either locally or via IPMI for example) so you can undo your changes.
  • If you are looking at this page because you want to write IP blocking software, be sure to add a mechanism that will automatically undo changes if the user stops responding after initially applying them.
Always review ranges carefully, and make exceptions where appropriate. Also don't forget to reboot your machine after blocking ranges for the first time to ensure you're not caught off guard in case some service refuses to start after accidentally having an essential IP range blocked.

General rules

The rules below apply to all API requests

User agent

Use a proper user agent. If you imitate a web browser, do not set one at all, or leave it at whatever the default of your HTTP library is, you may find your IP address or user agent restricted.
A proper user agent consists of the name of your application, version number, and a way to contact you, prefixed with a "+" sign. This is a common format in use by web crawlers also.
E-mail addresses as well as public HTTP(s) urls are accepted as means of contact.
Example: FirewallUpdater/1.0 +https://github.com/Example/FirewallUpdater
Tip: If you use curl, use the -A "..." argument to set your user agent.

API call rates

We generally do not restrict the number of calls you make to our API, however we may rate limit you using a 429 Too Many Requests response if it becomes excessive. In that case, check for a Retry-After header. It either contains the number of seconds to wait, or the date and time after which you can make requests again. Not obeying this will add further penalty time to your timeout. If the header is missing, employ a backoff algorithm in these steps (or similar): 5s, 10s, 30s, 60s, 120s, 300s, 600s

During development, consider testing only with very small ranges at first, and switch to larger ranges once the basic implementation is functioning. Processing the data is generally more complicated than downloading it, so you may also want to write the downloaded range into a file during development so you can read the file instead of making repeated API requests during debugging.

Data updates

API endpoints delivering ranges employ a HTTP caching mechanism based on the Last-Modified header. You can either use this mechanism, or check with the "Info" API command for updates

The "Info" API endpoint (see below) can be used to get expiration and update details of each range type. Note that the update will not happen exactly at the point the date specifies, but some time after, usually within the same hour for external ranges, and within a week for country and ASN ranges.
The recommended procedure is to store the timestamp of the last update every time you make a call, and only update the ranges when that timestamp has changed.

API endpoints

The API currently provides two endpoints, one to get the cache information, and one to obtain ranges.

"Info" command

Method: GET
URL: /Download/Info

The response is a JSON dictionary (without the comments) in this general format: 

{
    "cache": { //Timestamps for caching purposes. Format is yyyy-MM-dd'T'HH:mm:ss'Z'
        "country": "ISO 8601",
        "asn": "ISO 8601",
        "external": {
            //Keys may be added or removed here at any time
            "amazon": "ISO 8601",
            "azure": "ISO 8601",
            "cloudflare": "ISO 8601",
            "google": "ISO 8601",
            "tor": "ISO 8601"
        }
    },
    "ranges": {
        //The keys map to the "range" parameter for downloading ranges
        "asn": [],
        "country": [],
        "external": []
    },
    "types": ["string"] //This contains all permitted values for the "type" parameter for downloading ranges
}

For each range, the format will be 

{
        "id": "string", //Maps to the "id" parameter for downloading ranges
        "name": "string" | null, //Not all ranges provide a human readable name
        "rangeCount": int
}

Downloading ranges

Method: GET
URL: /Download/{range}/{id}?type={type}

Parameter "range": One of country, asn , external
Parameter "id": Country code, asn number, or external name
Parameter "type": One of csv, p2p, cidr

Tip: All ranges shown on this website have download buttons for each file type next to them. Rather than constructing an URL manually, go to the page that shows the desired range, then right click the file format button of choice and copy the URL to your clipboard.

The response will be the requested ranges in the requested file format. The response is always GZip compressed, regardless of whether your HTTP client requests them this way or not. If the downloaded result looks like binary garbage instead of text, you must either GZip decompress it manually, or tell your HTTP client to automatically decompress responses (we set the appropriate response header). The .NET "System.Net.HttpClient" is one such example, where automatic decompression has to be explicitly enabled.