TeleGeography Pricing Suite API

The TeleGeography Pricing Suite API is the developer's portal to all of TeleGeography's network pricing data. This collection of read-only endpoints is the RESTful corollary to the search tools found within the TeleGeography Pricing Suite, allowing users to search TeleGeography pricing databases by product, geography, capacity, and more.

Basics

Statistical Summary (the minimum, median, average, and maximum prices from a particular location or route for the quarter in which data was collected.)
Carrier Postings (The actual price from the carrier. Carrier names are anonymized.)

Endpoints within the API are grouped by product and search category. For example, searching DIA Statistical Summary would be done through the endpoint /dia/stats. For a full list of supported products and searches, see the Documentation by Product section or our full Swagger Docs.

Documentation by Product

A full list of the endpoints provided by this API and their associated documentation is shown below - or if you prefer, jump straight to our complete Swagger Docs for the full API.

Authentication

API calls consist of GET requests to product-specific endpoints. Endpoints are protected by Basic Auth using a user's TeleGeography account credentials. Credentials can be passed as a Base64-encoded header or as parameters in an HTTP client.

When passing credentials in the header, Base64-encode must be used. The following is an example of an encoded HTTP Basic Authentication header:

Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA==

With a client such as curl, credentials are passed with the -u option, as shown in the following example:

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats" -u email_address:password

Using curl encodes the user's email address and password and adds them to the request's Authorization header. This is equivalent to passing the header manually:

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

Improperly formatted or missing Authorization headers will result in a 400 HTTP response. Valid headers that fail authentication will result in a 401 HTTP response.

Search Examples

The following examples demonstrate how to use the API to query TeleGeography's network pricing datasets. Because each datasets contain fields that are unique to that dataset, please refer to the Documentation by Product section for a full list of parameters available.

Searching by Geography

One common use-case of this API is to query pricing records within a specific geography, such as City, Country, Region, Subregion, or Route. All geographies are searchable by setting a geography parameter with an exact geographical identifier:

To search for MPLS VPN prices in London, UK: /vpn/stats?country=United+Kingdom&city=London
To search for IP Transit prices in Africa: /ipt/stats?region=Africa
To search for Frankfurt-London 10G Wavelengths: /wave/stats?route=Frankfurt-London&circuit=10G

A complete search query is shown below:

# MPLS VPN prices in London, UK
curl -X GET "https://pricing-suite-api.telegeography.com/vpn/stats?country=United+Kingdom&city=London   -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="
# IP Transit prices in Africa
curl -X GET "https://pricing-suite-api.telegeography.com/ipt/stats?region=Africa  -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="
# Frankfurt-London 10G Wavelengths
curl -X GET "https://pricing-suite-api.telegeography.com/wave/stats?route=Frankfurt-London&circuit=10G  -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

In the example shown, the search query relies on an exact match to TeleGeography's geographic naming convention. This means that if the parameter "U.K." instead of "United Kingdom" is used, the query would return 0 results. For a complete list of the geographic naming conventions used by TeleGeography, please query the References section of the API. For example, to find countries matching the pattern *U*K* (where * is a wildcard), use the query /references/countries endpoint like shown below, setting the name_like parameter to "U*K*".

curl -X GET "https://pricing-suite-api.telegeography.com/references/countries?name_like=U*K*" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

[
  {
    "name": "United Kingdom",
    "ISO2": "GB",
    "ISO3": "GBR",
    "region_name": "Europe",
    "subregion_name": "Western Europe"
  }
]

In the name_like parameter, asterisks represent wildcards. Do note the name_like parameter is case-sensitive. Similar searches can be performed on /references/cities, /references/regions, /references/routes, or any of the endpoints listed under the References section of the Swagger Docs documentation.

Searching by Capacity

Many of TeleGeography's network pricing records contain a field that denotes a circuit and/or capacity. The API provides several ways to query circuits and capacities.

Search by Circuit Name

To search for a specific circuit, for example, "FastE", use the circuit parameter:

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats?circuit=FastE" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

Like the geography parameters in this API, the circuit name must be an exact match with values present in the naming convention used by TeleGeography. A full list of circuits available to query is available in the Circuit Reference section of the API documentation.

Search by Circuit Capacity (Mbps)

To search for a specific circuit by the data rate in Mbps, enter a number (such as 50) and specify the following operators:

Exact Match (e.g. capacity_eq=50)
Greather than or equal to (e.g. capacity_gteq=50)
Less than or equal to (e.g. capacity_lteq=50)

To retrieve DIA Statistics, in London, for capacities <= 50 Mbps, use the following query:

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats?city=London&capacity_lteq=50" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

Searching by Date Range

TeleGeography's network pricing data is collected on a quarterly basis. For any given year, individual carrier postings and any aggregate statistics data are associated with one of the following dates:

3/31 (for data collected in Q1)
6/30 (for data collected in Q2)
9/30 (for data collected in Q3)
12/31 (for data collected in Q4)

To query data from a given date range, the API accepts date range parameters start_date and end_date in the following formats: MM-DD-YYYY, MM/DD/YYYY or YYYY-MM-DD. Dates entered as 03-31-2020, 03/31/2020 or 2020-03-31 would all equal to Q1, 2020.

The following code queries DIA Statistics in London for FastE in the date range Q1-Q4 2019:

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats?city=London&circuit=FastE&start_date=2019-03-31&end_date=2019-12-31" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

The start_date and end_date are inclusive date boundaries. Dates provided in an invalid format will be ignored.

Pagination

All endpoints enforce a maximum result limit of 200 per request. All API endpoints accept optional page and per_page parameters with default values of 1 and 200, respectively. For example, to query records 201-400, you might execute

curl -X GET "https://pricing-suite-api.telegeography.com/dia/stats?page=2&per_page=200" -H "Authorization: Basic ZW1haWxfYWRkcmVzczpwYXNzd29yZA=="

The response headers of each endpoint will include metadata about the current page, total number of records, and links for next and last pages of the search results. An example of the pagination-related response headers is shown below.

{
  "link": "<http://https://pricing-suite-api.telegeography.com/dia/stats?page=4106>; rel=\"last\",
    <http://https://pricing-suite-api.telegeography.com/dia/stats?page=3>; rel=\"next\"",
  "x-per-page": "200",
  "x-page": "2",
  "x-total": "94417",
}