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

The latency engine uses measurement latencies from RIPE Atlas (opens new window) probes to provide an approximate radius for the location of an IP address. It is supported by the single-radius engine which triggers new RIPE Atlas measurements and feeds the results to latency. 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 have the following features:

• 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 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, with a queue and rate limit.
• 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.
• The metadata for the engines contains a numClusters variable, which shows how many disjointed speed-of-light bubbles have been found. This value is used to also set an anycast flag, which is the best guess as to whether the given IP address is multihosted/anycast.
• If both engines are used, either by default or with ?engines=single-radius,latency, single-radius will only be triggered if there are not already results in latency. Additionally, any results will always be displayed by latency unless single-radius is used by itself, for the purposes of backwards-compatibility.

We would like to thank Vasileios Giotsas for the great support provided during the development of the original "single-radius" engine.

worlds

worlds uses human and natural geographical data to convert locations suggestions from the other engines to cities and towns. This includes converting points and geographical areas to named locations, annotating locations with a common set of details, and scoring suggestions based on demographic factors.

This engine is made possible by the public data sources provided by:

• Geonames (opens new window)
• Natural Earth (opens new window)

reverse-dns

reverse-dns analyses hostnames from PTR records for a queried IP address and attempts to find geolocations based on the naming schemes used by network operators.

The engine generates several internal datasets on a daily basis:

• a list of hints from the worlds engine, including place names, IATA location codes, ISO-3166-1 country codes, and ISO-3166-2 subdivision codes.
• a list of hostnames by finding PTR records for every address known to the latency engine, which currently includes every traceroute hop seen by RIPE Atlas probes (with verified locations) over the past week.
• a mapping of hostnames to RIPE Atlas probe locations, along with the minimum round-trip time between the probe and the hop

These lists are fed to the sc_hoiho tool from CAIDA's scamper toolkit, which generates a list of possible naming scheme patterns for each domain/operator, based on the worlds geohints and latency speed-of-light limitations.

The engine is then able to provide three kinds of results:

1. A location matching an inferred pattern and the particular location or facility has been seen in the data. e.g. the PTR record contains router1.ams01 referring to Amsterdam, and there are other confirmed locations in the data containing router2.ams01, router1.ams02 etc. This type of result is scored the highest.
2. A location matching a pattern, but with a particular location that hasn't been seen elsewhere. e.g. the PTR record contains router1.ams01, the data contains router1.fra02 and router2.lon01 but there is no previous reference to a facility in Amsterdam. This type of result is scored slightly lower than 1.
3. A location not matching any known pattern for this domain, but containing tokens which map to known geohints, such as an IATA code. This type of result is assigned a low score, but can still be useful in some cases when there is a narrow area provided by the radius-based engines.

For 1 and 2, the engine includes patterns that sc_hoiho considers either good or promising, scoring the latter slightly lower than the former.

This engine relies heavily on the work put into the sc_hoiho tool and the research that went into (and before) it. For more information, see:

• SC_HOIHO(1) (opens new window)
• Learning to Extract Geographic Information from Internet Router Hostnames (opens new window) Matthew Luckie, Bradley Huffaker, Alexander Marder, Zachary Bischof, Marianne Fletcher, and k claffy

crowdsourced

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

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

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.