Measurement Data¶

This is the measurement data that is available in our dashboards and when you query the API for measurements.

Note that the definition of calculated statistics is not part of this page. You will find the definitions in the statistics documentation.

For the detailed Client Reports (which provide additional measurement data), see the Client Reports documentation.

Note

For legacy reasons, speed test measurements contain their statistics directly in their attributes, so they are listed here.

Note

Connection details are specified below, but explained in more detail here

Example File¶

Here is an example response for a YouTube video measurement part of a video study.

{
  "id": 874,
  "video_id": 6,
  "web_measurement_id": 605,
  "service": "youtube",
  "manifest_url": "",
  "player": "html5_player",
  "player_version": null,
  "playback_technology": "dash",
  "play_mode": "normal",
  "internal_id": "d1ea9d1c-1c84-4c21-be02-8feb8cad6a7b",
  "started_at": "2023-02-11T13:41:55.433Z",
  "finished_at": "2023-02-11T13:42:54.961Z",
  "statistics_calculated_at": "2023-02-11T13:45:02.619Z",
  "finished_reason": "NAVIGATED_AWAY",
  "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
  "url_stripped": false,
  "ad_block_used": null,
  "logged_in": null,
  "client_version": "1.19.0",
  "domain": "youtube.com",
  "incognito": null,
  "notes": null,
  "params": {},
  "created_at": "2023-02-11T13:42:57.866Z",
  "updated_at": "2023-02-11T13:45:02.681Z",
  "membership": null,
  "aborted_at": null,
  "started_at_skewed": "2023-02-11T13:41:55.436Z",
  "finished_at_skewed": "2023-02-11T13:42:54.878Z",
  "aborted_at_skewed": null,
  "last_indexed_at": "2023-02-11T13:45:02.673Z",
  "hostname": "www.youtube.com",
  "metadata": {},
  "statistic_values": {
    "average_audio_bitrate": 128.64804547948964,
    "average_stalling_time": 0,
    "average_total_bitrate": 1859.8419284589831,
    "average_video_bitrate": 1731.1938829794935,
    "initial_loading_delay": 0.901,
    "initial_resolution": 360,
    "largest_played_video_size": 1080,
    "longest_played_chunk": 1080,
    "number_of_quality_switches": 2,
    "number_of_stalling_events": 0,
    "p1203_average_audio_quality": 4.351516869450904,
    "p1203_average_video_quality": 4.049200728348692,
    "p1203_overall_audiovisual_quality": 4.558856739791521,
    "p1203_overall_mos": 4.1299587261921475,
    "p1203_stalling_quality": 4.565026221198433,
    "quality_switch_up_count": 2,
    "total_stalling_time": 0,
    "total_play_time": 59.333,
    "stalling_ratio": 0.0,
    "video_response_time": 0.049199999999254944,
    "p1203_max_theoretical_mos": 4.795888967025412,
    "quality_switch_down_count": 0,
    "video_completion_ratio": 0.09349654349741018
  },
  "client": {
    "uuid": "4c8e6168-291d-4b76-b993-5a8673371616",
    "type": "SurfmeterClient",
    "label": null,
    "tags": [],
    "extra_label": null
  },
  "client_context": {
    "browser_type": "Chrome",
    "browser_version": "109.0.0.0",
    "operating_system": "Linux",
    "operating_system_version": "aarch64",
    "valid_from": "2023-02-11T13:42:57.064Z",
    "valid_until": null
  },
  "isp_detail": {
    "ip_address": "172.18.0.1",
    "as": null
  },
  "video": {
    "service": "youtube",
    "stream_id": "aqz-KE-bpKQ",
    "is_reference_video": false,
    "title": null,
    "content_type": "feature",
    "duration": 634.601,
    "num_comments": null,
    "num_likes": null,
    "num_dislikes": null,
    "num_views": null,
    "channel_title": null,
    "channel_id": null,
    "src": null
  },
  "connection_detail": null,
  "@timestamp": "2023-02-11T13:41:55.433Z",
  "type": "VideoMeasurement",
  "study_chain": {
    "id": 238,
    "started_at": null,
    "finished_at": null,
    "aborted_at": null,
    "created_at": "2023-02-11T13:42:57.151Z",
    "updated_at": "2023-02-11T13:42:57.151Z",
    "aborted_reason": null,
    "abort_action": null,
    "abort_action_at": null,
    "started_at_skewed": null,
    "finished_at_skewed": null,
    "aborted_at_skewed": null,
    "abort_action_at_skewed": null
  },
  "study": {
    "id": 237,
    "subject": "youtube",
    "started_at": "2023-02-11T13:41:53.869Z",
    "finished_at": "2023-02-11T13:42:54.875Z",
    "aborted_at": null,
    "aborted_reason": null,
    "abort_action": null,
    "abort_action_at": null,
    "created_at": "2023-02-11T13:42:57.197Z",
    "updated_at": "2023-02-11T13:42:57.197Z",
    "run_options": {
      "run_in_control_tab": true
    },
    "started_at_skewed": "2023-02-11T13:41:53.872Z",
    "finished_at_skewed": "2023-02-11T13:42:54.878Z",
    "aborted_at_skewed": null,
    "abort_action_at_skewed": null,
    "description": {
      "id": "STUDY_YOUTUBE",
      "type": "VIDEO",
      "names": {
        "de_de": {
          "long": "YouTube BBB Sample Test",
          "short": "YouTube BBB Test"
        },
        "en_us": {
          "long": "YouTube BBB Sample Test",
          "short": "YouTube BBB Test"
        }
      },
      "params": {
        "video": {
          "src": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
          "content_type": "feature"
        },
        "timeout": 30,
        "duration": 60,
        "play_mode": "normal"
      },
      "subject": "youtube"
    },
    "notes": null,
    "metadata": {}
  },
  "video_measurement_id": 148
}

Properties¶

These are the properties of all measurements. We first describe those common to all types of measurements, then those specific to each type.

Common Properties¶

A base measurement JSON Schema (never sent to analytics, just for providing inheritance)

Property	Type	Description
`id`	`number`	The unique ID of the measurement
`internal_id`	`string`	An internal ID for the measurement
`created_at`	`string`, or `null`	The time the measurement was created on the server (ISO 8601 format)
`updated_at`	`string`, or `null`	The time the measurement was last updated on the server (ISO 8601 format)
`started_at`	`string`, or `null`	The time the measurement was started (ISO 8601 format)
`finished_at`	`string`, or `null`	The time the measurement was finished (ISO 8601 format)
`aborted_at`	`string`, or `null`	The time the measurement was aborted (ISO 8601 format)
`aborted_reason`	`string`, or `null`	The reason why the measurement was aborted
`started_at_skewed`	`string`, or `null`	The time the measurement was started (ISO 8601 format), adjusted in case of client skew
`finished_at_skewed`	`string`, or `null`	The time the measurement was finished (ISO 8601 format), adjusted in case of client skew
`aborted_at_skewed`	`string`, or `null`	The time the measurement was aborted (ISO 8601 format), adjusted in case of client skew
`statistics_calculated_at`	`string`, or `null`	The time the statistics were calculated (ISO 8601 format)
`last_indexed_at`	`string`, or `null` (optional)	The time the measurement was last indexed to Elasticsearch (ISO 8601 format)
`finished_reason`	`string`, or `null` (optional)	A string describing the reason why the measurement was finished
`url`	`string`, or `null` (optional)	A URL corresponding to the measurement
`url_stripped`	`boolean`, or `null` (optional)	Whether the URL was stripped for privacy reasons
`ad_block_used`	`boolean`, or `null` (optional)	Whether ad blocking was used
`logged_in`	`boolean`, or `null` (optional)	Whether the user was logged in
`membership`	`string`, or `null` (optional)	A string describing the membership of the user on the measured service
`client_version`	`string` (optional)	The version of the client used
`client_type`	`string`, or `null` (optional)	The type of the client used (e.g. `SurfmeterLabClient` or `SurfmeterAutomatorClient`)
`domain`	`string` (optional)	The domain of the measurement
`incognito`	`boolean`, or `null` (optional)	Whether incognito mode was used
`notes`	`string`	Any notes associated with the measurement
`metadata`	`object`	Custom metadata associated with the measurement
`params`	`object`	Custom params used for running the measurement
`statistic_values`	`object`	A dictionary of statistic values calculated for the measurement, see Statistic Values reference.
`geolocation`	Geolocation (optional)	A dictionary of geolocation information
`client`	Client	An object describing the client used for the measurement
`client_context`	Client Context (optional)	Detailed information about the client
`isp_detail`	Isp Detail (optional)	Information about the ISP
`remote_isp_detail`	Remote Isp Detail (optional)	Information about the ISP of the remote host
`connection_detail`	Connection Detail (optional)	More information about the connection
`study_chain`	Study Chain (optional)	The study chain containing individual studies
`study`	Study (optional)	The description of a study
`@timestamp`	`string`	The time when the measurement was created (ISO 8601 format)
`started_at_minute`	`integer`, or `null` (optional)	The minute when the measurement was started (integer)

Study¶

The description of a study

Property	Type	Description
`id`	`integer`	The ID of the study
`subject`	`string`	The subject of the study
`started_at`	`string`, or `null`	The time when the study started (ISO 8601 format)
`finished_at`	`string`, or `null`	The time when the study finished (ISO 8601 format)
`aborted_at`	`string`, or `null`	The time when the study was aborted (ISO 8601 format)
`aborted_reason`	`string`, or `null`	A reason for aborting the study
`abort_action`	`string`, or `null`	Which action was taken to abort the study
`abort_action_at`	`string`, or `null`	When the abort action was taken (ISO 8601 format)
`created_at`	`string`, or `null`	The time when the study was created (ISO 8601 format)
`updated_at`	`string`, or `null`	The time when the study was last updated (ISO 8601 format)
`run_options`	`object` (no predefined properties)	Special options used to run the study
`started_at_skewed`	`string`, or `null`	The time when the study started (ISO 8601 format), adjusted in case of client skew
`finished_at_skewed`	`string`, or `null`	The time when the study finished (ISO 8601 format), adjusted in case of client skew
`aborted_at_skewed`	`string`, or `null`	The time when the study was aborted (ISO 8601 format), adjusted in case of client skew
`abort_action_at_skewed`	`string`, or `null`	When the abort action was taken (ISO 8601 format), adjusted in case of client skew
`description`	`object` (no predefined properties)	The description of the study (as in the Public Config)
`notes`	`string` (optional)	Any notes associated with the study
`metadata`	`object` (no predefined properties) (optional)	Custom metadata associated with the study

Study Chain¶

The study chain containing individual studies

Property	Type	Description
`id`	`integer`	The ID of the study chain
`started_at`	`string`, or `null`	The time when the study chain started (ISO 8601 format)
`finished_at`	`string`, or `null`	The time when the study chain finished (ISO 8601 format)
`aborted_at`	`string`, or `null`	The time when the study chain was aborted (ISO 8601 format)
`created_at`	`string`, or `null`	The time when the study chain was created (ISO 8601 format)
`updated_at`	`string`, or `null`	The time when the study chain was last updated (ISO 8601 format)
`aborted_reason`	`string`, or `null`	A reason for aborting the study chain
`abort_action`	`string`, or `null`	Which action was taken to abort the study chain
`abort_action_at`	`string`, or `null`	When the abort action was taken (ISO 8601 format)
`started_at_skewed`	`string`, or `null`	The time when the study chain started (ISO 8601 format), adjusted in case of client skew
`finished_at_skewed`	`string`, or `null`	The time when the study chain finished (ISO 8601 format), adjusted in case of client skew
`aborted_at_skewed`	`string`, or `null`	The time when the study chain was aborted (ISO 8601 format), adjusted in case of client skew
`abort_action_at_skewed`	`string`, or `null`	When the abort action was taken (ISO 8601 format), adjusted in case of client skew
`study_ids`	`array` of `string`	The IDs of the studies in the chain

Connection Detail¶

More information about the connection

Property	Type	Description
`type`	`string`	The type of connection (MobileConnectionDetail, WifiConnectionDetail, EthernetConnectionDetail)
`mobile_network_type`	`string`, or `null` (optional)	The type of mobile network (EDGE, HSDPA, etc.)
`mobile_network_type_general`	`string`, or `null` (optional)	The general type of mobile network (2G, 3G, 4G, etc.)
`client_time`	`string`, or `null` (optional)	The time when the client sent the data (ISO 8601 format)
`client_time_skewed`	`string`, or `null` (optional)	The time when the client sent the data (ISO 8601 format), adjusted in case of client skew
`signal_strength`	`number`, or `null` (optional)	Overall signal strength
`is_internet_reachable`	`boolean`, or `null` (optional)	Boolean indicating if the internet is accessible
`is_connection_expensive`	`boolean`, or `null` (optional)	Boolean indicating if the connection is metered or roaming
`arfcn`	`integer`, or `null` (optional)	Absolute Radio Frequency Channel Number
`bsic`	`integer`, or `null` (optional)	Base Station Identity Code
`bsid`	`integer`, or `null` (optional)	Base Station ID
`cid`	`integer`, or `null` (optional)	Cell Identity
`lac`	`integer`, or `null` (optional)	Location Area Code
`mcc`	`integer`, or `null` (optional)	Mobile Country Code
`mnc`	`integer`, or `null` (optional)	Mobile Network Code
`mno`	`string`, or `null` (optional)	Mobile Network Operator
`enodeb_id`	`integer`, or `null` (optional)	eNodeB ID (for LTE networks)
`pci`	`integer`, or `null` (optional)	Physical Cell ID (for LTE networks)
`psc`	`integer`, or `null` (optional)	Primary Scrambling Code
`tac`	`integer`, or `null` (optional)	Tracking Area Code (for LTE networks)
`bssid`	`string`, or `null` (optional)	MAC address of the connected access point
`ssid`	`string`, or `null` (optional)	Name of the WiFi network
`rssi`	`integer`, or `null` (optional)	Received Signal Strength Indicator
`channel`	`integer`, or `null` (optional)	WiFi channel number
`link_speed`	`number`, or `null` (optional)	Connection speed in Mbps
`frequency`	`integer`, or `null` (optional)	WiFi frequency in MHz
`ip_address`	`string`, or `null` (optional)	IP address of the device on the current network
`subnet`	`string`, or `null` (optional)	Subnet mask of the network
`dbm`	`number`, or `null` (optional)	Signal strength in dBm
`is_roaming`	`boolean`, or `null` (optional)	Boolean indicating if the device is roaming
`asu_level`	`integer`, or `null` (optional)	Signal level as an ASU (Arbitrary Strength Unit) value
`signal_level`	`integer`, or `null` (optional)	Signal level as an integer from 0 to 4
`cpid`	`integer`, or `null` (optional)	Cell Parameters ID
`ecno`	`number`, or `null` (optional)	Energy per Chip to Noise Ratio
`nci`	`integer`, or `null` (optional)	NR Cell Identity (for 5G networks)
`nid`	`integer`, or `null` (optional)	Network ID
`nrarfcn`	`integer`, or `null` (optional)	NR Absolute Radio Frequency Channel Number (for 5G networks)
`rscp`	`number`, or `null` (optional)	Received Signal Code Power
`rsrp`	`number`, or `null` (optional)	Reference Signal Received Power
`rsrq`	`number`, or `null` (optional)	Reference Signal Received Quality
`rssnr`	`number`, or `null` (optional)	Reference Signal Signal-to-Noise Ratio
`sid`	`integer`, or `null` (optional)	System ID
`ssrsrp`	`number`, or `null` (optional)	SS Reference Signal Received Power
`ssrsrq`	`number`, or `null` (optional)	SS Reference Signal Received Quality
`sssinr`	`number`, or `null` (optional)	SS Signal-to-Noise and Interference Ratio
`uarfcn`	`integer`, or `null` (optional)	UTRA Absolute RF Channel Number

Isp Detail¶

Information about the ISP

Property	Type	Description
`isp`	`object` with properties: `name`	The ISP
`ip_address`	`string`, or `null`	The IP address of the client
`as`	`string`, or `null`	The AS number of the client

Remote Isp Detail¶

Information about the ISP of the remote host

Property	Type	Description
`isp`	`object` with properties: `name`	The ISP
`ip_address`	`string`, or `null`	The IP address of the remote host
`as`	`string`, or `null`	The AS number of the remote host

Client Context¶

Detailed information about the client

Property	Type	Description
`browser_type`	`string`, or `null` (optional)	The browser type
`browser_version`	`string`, or `null` (optional)	The browser version
`operating_system`	`string`, or `null` (optional)	The operating system
`operating_system_version`	`string`, or `null` (optional)	The operating system version

Client¶

An object describing the client used for the measurement

Property	Type	Description
`created_at`	`string`, or `null`	The time when the client was created (ISO 8601 format)
`updated_at`	`string`, or `null`	The time when the client was last updated (ISO 8601 format)
`disabled_at`	`string`, or `null`	The time when the client was disabled (ISO 8601 format)
`disabled_reason`	`string`, or `null`	The reason why the client was disabled
`uuid`	`string`	The UUID of the client
`label`	`string`, or `null`	A custom label for the client
`type`	`string`, or `null`	The client type
`tags`	`array` of `string`	Any tags associated with the client
`extra_label`	`string`, or `null`	An extra label for the client

Geolocation¶

A dictionary of geolocation information

Property	Type	Description
`latitude`	`number`, or `null`	The latitude of the measurement
`longitude`	`number`, or `null`	The longitude of the measurement
`latlon`	`array` (optional)	The latitude and longitude of the measurement
`city`	`string`, or `null` (optional)	The city of the measurement
`zip`	`string`, or `null` (optional)	The ZIP code of the measurement
`region`	`string`, or `null` (optional)	The region of the measurement
`country`	`string`, or `null` (optional)	The country of the measurement

Web Measurement Properties¶

A web measurement sent to analytics

Property	Type	Description
`technology`	`string`, or `null`	The technology used for the web measurement (see `subject` in Public Config)
`page_type`	`string`, or `null`	A string describing the type of page
`web_measurement_id`	`integer`	The specific ID of the web measurement

Network Measurement Properties¶

A network measurement sent to analytics

Property	Type	Description
`technology`	`string`	The technology used for the network measurement (see `subject` in Public Config)
`network_measurement_id`	`integer`	The specific ID of the network measurement

Speedtest Measurement Properties¶

A speedtest measurement sent to analytics

Property	Type	Description
`upload`	`number`	The upload speed in Mbit/s
`download`	`number`	The download speed in Mbit/s
`ping`	`number`	The ping/latency time in milliseconds
`remote_server`	`string`, or `null`	The remote server used for the speedtest, if available
`version`	`string`, or `null`	The version of the speedtest, if available
`speedtest_measurement_id`	`integer`	The specific ID of the speedtest measurement

Video Measurement Properties¶

A video measurement sent to analytics

Property	Type	Description
`video`	Video	The video that was measured
`play_mode`	`string` (one of: `normal`, `embedded`, `lab_embedded`, `unknown`) (optional)	The play mode of the measurement. normal: A normal video playback in a browser tab or similar; embedded: A video embedded into a custom HTML webpage; lab_embedded: A video embedded into a lab app like Surfmeter; unknown: Not specified
`service`	`string` (optional)	The service that the video is hosted on
`manifest_url`	`string` (optional)	The URL of the MPEG-DASH/HLS manifest (if streamed from a manifest directly, or if the URL is known). This may not be known for some services.
`player`	`string` (one of: `exoplayer`, `html5_player`, `dashjs_player`, `youtube_player`, `videojs_player`, `brightcove_player`, `unknown`) (optional)	The player that was used to play the video
`player_version`	`string`, or `null` (optional)	The version of the player that was used to play the video (if available)
`playback_technology`	`string` (one of: `dash`, `hls`, `smooth`, `progressive`, `unknown`) (optional)	The playback technology that was used to play the video
`video_measurement_id`	`integer`	The specific ID of the video measurement

Video¶

The video that was measured

Property	Type	Description
`service`	`string`	The service that the video is hosted on
`stream_id`	`string`	The internal ID of the stream or video ID
`is_reference_video`	`boolean`	Whether the video is a reference video (i.e., one that is repeatedly used in measurements)
`content_type`	`string` (one of: `trailer`, `feature`, `advertisement`, `live`, `lab`, `unknown`)	The content type of the video, as set in the study description. Note that this has no implication on the results at the moment and is purely used for identification purposes.
`duration`	`number`, or `null`	The duration of the video in seconds (not available for live streams)
`channel_title`	`string`, or `null` (optional)	The title of the channel (if applicable)
`channel_id`	`string`, or `null` (optional)	The ID of the channel (if applicable)
`src`	`string`, or `null` (optional)	A URL to the video (if available)
`num_comments`	`number`, or `null` (optional)	The number of comments (if available)
`num_dislikes`	`number`, or `null` (optional)	The number of dislikes (if available)
`num_likes`	`number`, or `null` (optional)	The number of likes (if available)
`num_views`	`number`, or `null` (optional)	The number of views (if available)
`title`	`string`, or `null` (optional)	The title of the video

Conferencing Measurement Properties¶

A conferencing measurement sent to analytics

Property	Type	Description
`service`	`string`	The service that the conferencing measurement is for
`conferencing_measurement_id`	`integer`	The specific ID of the conferencing measurement

Connection Data Details¶

The following properties are only available for MobileConnectionDetail:

Field	Description	Type	GSM	WCDMA	LTE	CDMA	TDSCDMA	NR (5G)
mno	Mobile Network Operator	`string`	✓	✓	✓	✓	✓†	✓†
mcc	Mobile Country Code	`string`	✓	✓	✓	✓	✓†	✓†
mnc	Mobile Network Code	`string`	✓	✓	✓	✓	✓†	✓†
dbm	Signal strength in dBm	`integer`	✓	✓	✓	✓	✓†	✓†
signal_level	Overall signal level	`integer`	✓	✓	✓	✓	✓†	✓†
asu_level	Signal level in ASU	`integer`	✓	✓	✓	✓	✓†	✓†
rssi	Received Signal Strength Indicator	`integer`	✓‡	-	-	-	-	-
rscp	Received Signal Code Power	`integer`	-	✓	-	-	✓†	-
ecno	Energy per Chip to Noise Ratio	`integer`	-	✓‡	-	-	-	-
rsrp	Reference Signal Received Power	`integer`	-	-	✓*	-	-	-
rsrq	Reference Signal Received Quality	`integer`	-	-	✓*	-	-	-
rssnr	Reference Signal Signal-to-Noise Ratio	`integer`	-	-	✓†	-	-	-
arfcn	Absolute RF Channel Number	`integer`	✓¹	✓¹	✓¹	-	-	-
bsic	Base Station Identity Code	`integer`	✓¹	-	-	-	-	-
cid	Cell Identity	`integer`	✓	✓	✓	-	✓†	-
lac	Location Area Code	`integer`	✓	✓	-	-	✓†	-
psc	Primary Scrambling Code	`integer`	-	✓¹	-	-	-	-
uarfcn	UTRA Absolute RF Channel Number	`integer`	-	✓¹	-	-	-	-
pci	Physical Cell Id	`integer`	-	-	✓	-	-	✓†
tac	Tracking Area Code	`integer`	-	-	✓	-	-	✓†
bsid	Base Station ID	`integer`	-	-	-	✓	-	-
nid	Network ID	`integer`	-	-	-	✓	-	-
sid	System ID	`integer`	-	-	-	✓	-	-
cpid	Cell Parameters ID	`integer`	-	-	-	-	✓†	-
nci	NR Cell Identity	`integer`	-	-	-	-	-	✓†
nrarfcn	NR Absolute RF Channel Number	`integer`	-	-	-	-	-	✓†
ssrsrp	SS Reference Signal Received Power	`integer`	-	-	-	-	-	✓†
ssrsrq	SS Reference Signal Received Quality	`integer`	-	-	-	-	-	✓†
sssinr	SS Signal-to-Noise and Interference Ratio	`integer`	-	-	-	-	-	✓†

Footnotes:

¹ Requires Android API level 24 (Android 7.0 Nougat) or higher
* Requires Android API level 26 (Android 8.0 Oreo) or higher
† Requires Android API level 29 (Android 10) or higher
‡ Requires Android API level 30 (Android 11) or higher

Note:

The signal_level field is available for all network types when the device is running Android 11 or higher.
For GSM and WCDMA, rssi and rscp respectively are noted to be the same as dbm