Data Extracts API

Documentation

The Speedtest Intelligence Data Extract API provides easy programmatic access to your data
extract files as well as all metadata associated with those files. This enables users to automate
extract file downloads, or even build their own integrations.

To get started, you’ll first need to generate an API key. API keys are specific to an individual
user rather than an organization, so the account associated with the API key will need to have
data extract access.

Obtaining An API Key

In the Extracts section of the Portal (https://intelligence.speedtest.net/#extracts), there is
a “Create API key” button that you’ll need to select in order to obtain an API key. The
API Key is a pair composed of an API key id and a secret key. The API key id will
remain on the Account Settings page for future reference. The secret key, however, will
need to be saved in a secure location as it will not be accessible again. Follow the
instructions below to apply the API key pair.

If you need to delete a key and regenerate another API key pair, simply select the “Create API
Key” button. You will receive a prompt to make sure that you want to delete the current key and
generate a new one. Upon selecting that, you will receive a new API key id and a new secret
key.

Using The API

Easiest method - An Ookla-provided Python script
Ookla provides an example Python script that downloads the most recently created extract file
for each extract type available. You can find the script, get-extracts.py, in our Speedtest Tools
GitHub repository or download it directly here. Once downloaded, edit the script and add your
API key where indicated. You can run the script with Python 2 or 3.

The script works by first querying the API for a list of all available files and any metadata
associated with those files. It then determines what extract types are available and downloads
the newest extract file for each type. Because the script downloads the most recently modified
version of each extract type, the script will need to be run at least as often as new extract
files are added. Also, rather than parsing file names to determine the date of the file, the script
uses the file’s timestamp. If the extract file is modified in any way, the timestamp will reflect the
last modified date which may temporarily cause the modified files to appear as the newest
extract until new extracts are added.

Automating the script to run in set intervals is dependant on your operating environment.
Depending on the platform, most users will want to use cron (Linux), Windows Scheduled
Tasks, or launchctl (Mac OS), but scheduling can also be done directly within Python using
the schedule library.

Building your own integration

The primary function of the API returns a JSON formatted list of all available extract files, file
metadata, and the download URL of each file. You can view sample output in your browser by
first logging in to the Speedtest Intelligence Portal and then navigating directly to
https://intelligence.speedtest.net/extracts.

All requests to https://intelligence.speedtest.net/extracts use basic authentication with a base64

encoded string of the API key and API secret as the username and password. For example,
using the following API credentials:

API key ID = 123A4BC API key secret = Z9YxwV8

we would need to base64 encode the string 123A4BC:Z9YxwV8 and add that to the request
header. The header using these credentials would need to look like

[('Authorization', 'Basic MTIzQTRCQzpaOVl4d1Y4')]

If authentication is successful, the API returns a JSON object. If authentication fails, rather than
a 401 error, the API returns the Speedtest Intelligence Portal web login. If authentication is
successful but the user doesn’t have access to data extracts, the API returns a 500 error.