Locate API v2

The Locate API v2 provides consistent, expected measurement quality for M-Lab clients. The Locate API v2 provides complete, client usable URLs for measurement services. This means service ports, URL paths, and required HTTP parameters are already embedded in the reply.

TL;DR Find Nearby Measurement Services

The Locate API v2 currently supports four measurement services:

  • ndt/ndt5
  • ndt/ndt7
  • wehe/replay
  • neubot/dash

The measurement service name (e.g. “ndt”) and type (e.g. “ndt7”) are the last two part of the Locate API v2 request URL. For example:

On success, this request returns a JSON response with a result array. Each result includes the target machine, location, and a set of complete service URLs (urls).

Clients may add additional HTTP parameters to the service URL. However, clients should not remove any existing parameters. In particular, the Locate API v2 includes an access_token= parameter that is validated by the target service. Access tokens are the primary mechanism for ensuring that clients route requests through the Locate API so that global load balancing is possible, and consistent, expected measurement quality is achieved.

{
  "results": [
    {
      "machine": "mlab2-lga05.mlab-oti.measurement-lab.org",
      "location": {
        "city": "New York",
        "country": "US"
      },
      "urls": {
        "wss:///ndt/v7/download": "wss://ndt-mlab2-lga05.mlab-oti.measurement-lab.org/ndt/v7/download?access_token=",
        "wss:///ndt/v7/upload": "wss://ndt-mlab2-lga05.mlab-oti.measurement-lab.org/ndt/v7/upload?access_token=",
      }
    },
    {
      ...
    }
  ]
}

Learning More About the Locate API v2

  • USAGE.md is a technical overview of the Locate API’s capabilities and usage.
Back to Top