RIPE Atlas Documentation

Measurement Result Format ​

RIPE Atlas measurement results can be downloaded in JSON format. This document describes the data structure of these results, which can vary by probe firmware version.

Notes ​

1.1. Versioning ​

The results are returned as an array consisting of elements, each of which is an associative array. The structure of these associative arrays depends on the firmware version used by the probe conducting the measurement. Therefore, it is possible for downloaded results to contain a mix of different result structures.

The data structure of each result contains the key fw which identifies the firmware version used by the probe that generated that result.

  • Version 1 is identified by the value "1".
  • Version 4400 is identified by a value of between "4400" and "4459".
  • Version 4460 is identified by a value of between "4460" and "4539".
  • Version 4540 is identified by a value of between "4540" and "4569".
  • Version 4570 is identified by a value of between "4570" and "4609".
  • Version 4610 is identified by a value of between "4610" and "4749".
  • Version 4750 is identified by a value of between "4750" and "4999".
  • Version 5000 is currently the most recent version of the datastructure documentation. At the moment any value greather than 5000 conforms to the 5000 documentation. An upper limit to this version will added with the release of a firmware version that changes the datastructures.

Since Version 5000, measurement results contain a separate field, called "mver", that specifies the version of the measurement code. This field has the format "x.y.z", where the "x" field is that major version, which changes when the measurement results are incompatible with the previous version. The "y" field is the minor version, and changes when new fields are added, but otherwise old parsers can still parse measurement results. Finally, the "z" field specifies that the measurement code changed, but the output format is still the same. This happens when only (minor) bugs are fixed and no new features are added.

1.2. Multiple Addresses in a Result ​

The result structure may contain several different fields that appear to contain similar information, but which are in fact slightly different.

from

This field is added by the RIPE Atlas backend system and is used in ASN lookup, geo-location, and so on. There are some special cases for IPv6-capable probes in which that this can be an empty string.

src

This field is added by the probe. It comes from a TCP socket, or from UDP connect/getsockname calls.

  • If the probe is behind a NAT, src could be a private address, whereas from will always be a public address.
  • It is also possible for src and from to differ with IPv6 if there are multiple addresses from RAs and/or static configuration with a different priority.
  • With v4 addresses, it is possible for the from field to be filled in at a later time, rather than when the measurement was made. If the probe is unable to connect to the RIPE Atlas backend system, but continues performing measurements and delivers the results at a later time, the backend system will populate the from field for this entire 'disconnected' time with the value at the time of reconnection.

1.3. JSON Terminology ​

Results are returned encoded in JSON. JSON has primitive data types such strings, numbers and booleans. And two compount data types, which are called object and array.

A JSON string is very much like a C string: the string is enclosed in double quotes (") and back slash (\) is used to introduce special characters. Likewise, a number is very much like a C floating point number. The boolean data types has two values, true and false.

The object data type is a collection of named fields. An object is a comma separated list enclosed in curly braces ("{" and "}"). Each element of the list consists of the name of the field encoded as string, a colon (":") and the value, which can be an arbitrary JSON data type.

The array data type is a comma separated list of values encloded in square brackets ("[" and "]"). JSON allows each value to be of a different type. However, in the data structures described here, arrays have values that are all the same type.