# Manual

# Using the API

RIPE IPmap can be accessed at https://ipmap-api.ripe.net/v1/ (opens new window) using any HTTPS client. All responses are encoded in JSON which can be parsed in all major languages. For a complete description of the API format see the API Reference.

In order to help us debug issues, we encourage you to include a client query parameter when using the API. For example:

https://ipmap-api.ripe.net/v1/locate/198.51.100.1?client=sarahs-cool-script

The RIPE NCC Website and Publicly Available RIPE NCC Services Terms of Service (opens new window) apply while using this service.

# Engines

We infer geolocations based on multiple approaches organised into distinct geolocation engines. When you query for an IP address, all the engines geolocate the address in parallel and return a list of possible locations. Each location is associated with a score that represents the confidence of the specific engine in the indicated location.

The final score of each location in included in the JSON output. You can find the contributions the various engines make to the final score in the contributions section of each location.

Notes:

  • The score is NOT an accuracy factor but a relative factor used to sort the provided locations.
  • It does NOT provide any percentage of certainty but rather an indication of how reliable a location is relative to others currently provided by the API.

The tuning and evaluation of the engines' accuracy is still an open research topic, which we plan to improve upon in the future. Each engine has a score factor which indicates how reliable are the individual scores that it produces.

# latency and single-radius engines

The latency and single-radius engines both use measurement latencies from RIPE Atlas (opens new window) probes to provide an approximate radius for the location of an IP address. The engines use calculations based on the speed of light to find a maximum physical distance between the two IP addresses. These calculations have the form:

d = r / 2 * c * f

where:

d = maximum distance (radius)
r = round trip time taken from the RIPE Atlas measurement result
c = speed of light in vacuum
f = the refractive index of fibre optic cabling, currently assumed to be 2/3

The engines differ in the following ways:

  • latency makes use of all non-private RIPE Atlas traceroutes over the past week.
  • single-radius is an active engine, which triggers RIPE Atlas measurements on demand (limited and with some delay).
  • latency attempts to minimize the maximum assumed distance by assuming that the smallest RTT seen for a given probe represents its "final mile" distance.
  • latency also attempts to improve the accuracy of results by internally validating the locations of the RIPE Atlas probes by:
    • first using RIPE Atlas Anchor (opens new window) mesh measurements to determine which anchors may not be accurately located,
    • and then using probe measurements towards this set of reliable anchors to validate the remaining RIPE Atlas probe locations.

In the future these engines may be combined by adding an active component to the latency engine.

# reverse-dns engine

reverse-dns analyses PTR records for a queried IP hinting at their location. This analysis is currently very simple, and attempts the following pattern matching:

This simple pattern matching is a useful first step when combined with the broad-brush results from the radius-based engines. In the future, we will support extra datasets and network-specific naming schemes to make the engine much more accurate, as well as score factors for particular networks which reflect how consistently accurate their naming system is.

# crowdsourced engine

crowdsourced allows external parties to curate and contribute sets of locations for IP addresses to RIPE IPmap. The benefit of this engine is that experts on a particular network can provide accurate locations that are unlikely to be found by the other engines. However, these datasets can become stale over time and stop providing accurate locations.

crowdsourced uses a contributor-scoring system to mark up contributions from sources which are very reliable. This system will be improved in a later version of RIPE IPmap.

# simple-anycast engine

simple-anycast uses an active RIPE Atlas measurement approach, similar to single-radius, to detect whether an IP address is shared across multiple locations. This engine is likely to be rolled into the latency engine in the future, which similarly provides results based on RIPE Atlas measurement results.

# ixp engine

ixp uses PeeringDB (opens new window) to locate IP addresses in IXPs, data centres and other interconnection facilities.

# Full dumps

We provide daily full dumps at https://ftp.ripe.net/ripe/ipmap/ (opens new window) in the following CSV format:

ip, geolocation_id, city_name, state_name, country_name, country_code_alpha2, country_code_alpha3, latitude, longitude, score

The dump contains the output of the "best" API (see above). For each IP, it provides the geolocation with the highest score.

Please note the dumps differ substantially from the dumps produced by the first prototype release of RIPE IPmap:

  • We now dump the "best" output computed by all the geolocation engines, rather than only the crowdsourced data;
  • The new score differs from the previous score since it is no longer based only on crowdsourced data (see above).

# How To Contribute

We are always open to collaborating with the community to integrate additional datasets, external APIs, and geolocation engines into RIPE IPmap.

If you want to contribute or get more information, please email us at atlas@ripe.net.

The following code is an example of our geolocation engine interface.

export default class MyEngine extends Suggestor{
    constructor(config){
        super(config);
    }


    isApplicable = (resource, body) => {
        // Check if the resource type can be geolocated by this engine
        // For example: return false if the engine is able to geolocate specific IP ranges and the resource is in none of them
        return true;
    };

    filter = (resource, body, header) => new Promise((resolve, reject) => {
        // Take all the locations possible and filter them. Return just the one possible
        const locations = []; // An array of locations in our worlds API format
        const metadata = {}; // Extra information the engine wants to return in the API answer
                            // (e.g. did the engine finish to calculate the geolocation or the client should try again in X time?)
        resolve({ locations: locations, metadata: metadata });
    });

    setScore = (resource, body, locationList, header) => new Promise((resolve, reject) => {
        // Set a score from 1 to 10 to each location in the locationList array
        // A score of 0 should be filtered out from the locationList returned by this method
        // More than one location can have the same score
        // The locationList array is the one returned by the "filter" method, so only the possible geolocations for this resource
        // The engine should use the score as a way to sort the locations based on the probability that the
        // single location has against the other in the same list. More information about the score will follow.
        resolve(locationList); // Return the array
    });

    toString = () =>{
        return "A description of the engine"; // It will appear in the API
    };

    reset = () => {
        // To reset the cache
    };

}

# Third-party datasets

We would like to thank and credit all the open datasets that made this project possible

# Collaborations

We would like to thank and credit all the researchers that contributed to this project

  • Vasileios Giotsas, for the great support provided during the "single-radius" active geolocation engine design.
Last Updated: 11/18/2021, 4:37:59 PM