Diagnostic Tools API v1 Resources

API Summary

Operation Method Endpoint
Diagnostics
List Locations GET /diagnostic-tools/v1/locations
Run dig GET /diagnostic-tools/v1/dig{?hostname,queryType,location,sourceIp}
Run mtr GET /diagnostic-tools/v1/mtr{?destinationDomain,location,sourceIp}
Translate Hostname GET /diagnostic-tools/v1/akamaitranslator{?hostname}
Translate Error Code GET /diagnostic-tools/v1/errortranslator{?errorCode}
Get IP Geolocation GET /diagnostic-tools/v1/ipgeolocator{?ip}
Verify if an IP is Within the CDN GET /diagnostic-tools/v1/verifycdnip{?ip}

List Locations

This operation lists active Akamai server locations from which you can run diagnostic tools. The dig and mtr tools use elements from this list. The response is a locationsContainer object with a list of locations or an errorString if the request fails.

GET /diagnostic-tools/v1/locations

Status 200 application/json

Response:

{
    "locations": [
        "city1, country",
        "city2, country"
    ],
    "errorString": null
}

Run dig

Run dig for a given hostname from an Akamai location. Dig looks up IP addresses from hostnames on the nameserver running on the Akamai edge server. It can help you determine which IP address the Akamai edge server uses to resolve your hostname. The response is a digContainer with dig output or an errorString if the request fails.

GET /diagnostic-tools/v1/dig{?hostname,queryType,location,sourceIp}

Example: /diagnostic-tools/v1/dig?hostname=developer.akamai.com&queryType=A&location=Sydney%2C+Australia&sourceIp=NN.NN.NN.NN

Parameter Type Sample Description
Required
hostname String developer.akamai.com the domain name you want to get information about.
location String Sydney, Australia Location of Akamai server from which you want to run dig. You can find servers using GET /diagnostic-tools/v1/locations.
queryType Enumeration A query type for the dig; valid types are:. Possible values: AAAA, A, CNAME, MX, PTR, SOA.
Optional
sourceIp String NN.NN.NN.NN CDN server IP to run DIG from.

Status 200 application/json

Response:

{
    "dig": {
        "hostname": "www.example.com.",
        "queryType": "A",
        "answerSection": [
            {
                "domain": "www.example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "A",
                "ttl": "5",
                "value": "NN.NN.NN.NN"
            }
        ],
        "authoritySection": [
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "a.example.net."
            },
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "b.example.net."
            }
        ],
        "result": "\n; <<>> DiG 9.8.1-P1 <<>> www.example.com -t A\n...",
        "errorString": null
    }
}

  1. Retrieve the locations container.

  2. Select a location from the list.

  3. URL-encode the location.

  4. Construct and submit the dig request.

Run mtr

Run mtr for a given hostname from an Akamai location. Network Connectivity Tester (mtr) combines the functionality of the traceroute and ping programs in a single network diagnostic tool. It investigates the network connection between the host on which mtr runs and the destinationDomain. The results of mtr show you how many network hops a packet takes from the Akamai server to the host and how long each hop takes. The statistics can show you where network delays are being introduced in the path. The response is a mtrContainer with mtr output or an errorString if the request fails.

GET /diagnostic-tools/v1/mtr{?destinationDomain,location,sourceIp}

Example: /diagnostic-tools/v1/mtr?destinationDomain=developer.akamai.com&location=Sydney%2C+Australia&sourceIp=NN.NN.NN.NN

Parameter Type Sample Description
Required
destinationDomain String developer.akamai.com The domain name you want to get information about.
location String Sydney, Australia Location of Akamai Server you want to run dig from. You can find servers using GET /diagnostic-tools/v1/locations. Either this parameter or sourceIp is required.
Optional
sourceIp String NN.NN.NN.NN CDN server IP to run MTR from. Either this parameter or location is required.

Status 200 application/json

Response:

{
    "mtr": {
        "source": null,
        "destination": "www.example.com",
        "host": "aNNN-NNN-NNN-NN.deploy.example.net",
        "packetLoss": "0.0",
        "avgLatency": "0.3",
        "analysis": "",
        "errorString": null,
        "hops": [
            {
                "num": "1.|-",
                "host": "NNNN:NNN:N:NNN::N",
                "loss": "0.0",
                "sent": "10",
                "last": "0.2",
                "avg": "0.3",
                "best": "0.2",
                "worst": "0.8",
                "stDev": "0.0"
            },
            {
                "num": "2.|-",
                "host": "XXN-NNN.XXXNN.example.net",
                "loss": "0.0",
                "sent": "10",
                "last": "0.3",
                "avg": "4.6",
                "best": "0.3",
                "worst": "33.9",
                "stDev": "10.7"
            },
            {
                "num": "3.|-",
                "host": "XX-N-N-N.XXXNN.example.ne",
                "loss": "0.0",
                "sent": "10",
                "last": "0.6",
                "avg": "0.4",
                "best": "0.3",
                "worst": "0.6",
                "stDev": "0.0"
            }
        ]
    }
}

  1. Retrieve the locations container.

  2. Select a location from the list.

  3. URL-encode the location.

  4. Construct and submit the mtr request.

Translate Hostname

Translates an Akamaized URL (ARL) into typecode, origin server, CP code, serial number, and TTL. The response is an ARLContainer with details on the ARL or an errorString if the request fails.

GET /diagnostic-tools/v1/akamaitranslator{?hostname}

Example: /diagnostic-tools/v1/akamaitranslator?hostname=host.example.com

Parameter Type Sample Description
Required
hostname String host.example.com Hostname for which to retrieve ARL information.

Status 200 application/json

Response:

{
    "arl": {
        "typeCode": "Object changes when ARL changes",
        "originServer": "origin.example.com",
        "cpCode": "12345",
        "serialNumber": "54321",
        "ttl": "Infinite",
        "pragma": null,
        "cacheControl": null,
        "errorString": null
    }
}

Translate Error Code

This operation decodes any error string sent by an edge server to the browser. The data it returns helps you to understand the problem’s root cause. The response is an errorTranslatorContainer featuring error details or a separate errorString if the request fails.

GET /diagnostic-tools/v1/errortranslator{?errorCode}

Example: /diagnostic-tools/v1/errortranslator?errorCode=9.6f64d440.1318965461.2f2b078

Parameter Type Sample Description
Required
errorCode String 9.6f64d440.1318965461.2f2b078 Error code or reference number you want to translate, which typically appears on an error page.

Status 200 application/json

Response:

{
    "errorTranslator": {
        "url": "http&#x3a;&#x2f;&#x2f;etranslator.edgesuite.net&#x2f;ERR_READ_TIMEOUT",
        "httpResponseCode": "504",
        "dateTime": "Fri, Jun 26, 2015 17&#x3a;39 GMT",
        "epochTime": "1435340340",
        "clientIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "serverIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "originHostname": "example.download.akamai.com",
        "originIP": "NN.NN.NN.NN&#x28;ASHBURN,VA,US&#x29;",
        "userAgent": "Mozilla&#x2f;5.0 &#x28;Macintosh&#x3b; Intel Mac OS X 10_10_3&#x29; AppleWebKit&#x2f;537.36 &#x28;KHTML, like Gecko&#x29; Chrome&#x2f;43.0.2357.124 Safari&#x2f;537.36",
        "requestMethod": "GET",
        "reasonForFailure": "ERR_READ_TIMEOUT&#x7c;before_resp_hdrs",
        "logs": null,
        "errorString": null
    }
}

Get IP Geolocation

This operation provides details for the location of an IP address. The response is an ipGeoLocationDataContainer with location details for the IP address provided.

GET /diagnostic-tools/v1/ipgeolocator{?ip}

Example: /diagnostic-tools/v1/ipgeolocator?ip=NNN.NNN.NNN.NNN

Parameter Type Sample Description
Required
ip String NNN.NNN.NNN.NNN IP Address

Status 200 application/json

Response:

{
    "ipGeoLocation": {
        "clientIp": "NNN.NNN.NNN.NNN",
        "countryCode": "US",
        "regionCode": "NY",
        "city": "NEWYORK",
        "dma": "501",
        "msa": "5602",
        "pmsa": "5600",
        "areaCode": "212",
        "latitude": "40.7500",
        "longitude": "-73.9967",
        "county": "NEWYORK",
        "continent": "NA",
        "fips": "36061",
        "timeZone": "EST",
        "network": null,
        "networkType": null,
        "zipCode": "10001-10014+10016-10041+10043-10045+10055+10060+10065",
        "throughput": "vhigh",
        "asNum": "1299",
        "errorString": null
    }
}

Verify if an IP is Within the CDN

Verifies whether or not the IP provided belongs to the content delivery network. You would typically run this test before running the Akamai Translator on IP addresses that pass. The response provides a verifyCdnIPData object.

GET /diagnostic-tools/v1/verifycdnip{?ip}

Example: /diagnostic-tools/v1/verifycdnip?ip=NNN.NNN.NNN.NNN

Parameter Type Sample Description
Required
ip String NNN.NNN.NNN.NNN IP Address you want to determine is included in the Akamai network.

Status 200 application/json

Response:

{
    "isCdnIP"     : "No",
    "ip"          : "NN.NN.NN.NN",
    "errorString" : null
}


Last modified: 4/14/2017