17track API result information

countryselection.json

{
  "ret": 1,
  "msg": "Ok",
  "dat": {
    "a": "00340433836055698228",
    "b": 0,
    "c": 0,
    "d": 0,
    "e": 0,
    "f": -1,
    "ln1": "",
    "ln2": "",
    "is1": 0,
    "is2": 0,
    "ygt1": 0,
    "ygt2": 0,
    "ylt1": "2079-01-01 00:00:00",
    "ylt2": "2079-01-01 00:00:00",
    "yt": "{\"t\":0, \"d\":[{\"c\":1608, \"p\":1}, {\"c\":2105, \"p\":1}, {\"c\":704, \"p\":2}]}",
    "z0": null,
    "z1": [],
    "z2": []
  }
}

exampledata.json

{
    "ret": 1,
    "msg": "Ok",
    "dat": {
        "a": "RS340375795NL",
        "b": 1404,
        "c": 704,
        "d": 1,
        "e": 10,
        "f": -1,
        "ln1": "en",
        "ln2": "en",
        "is1": 1,
        "is2": 2,
        "ygt1": 3625,
        "ygt2": 5578,
        "ylt1": "2079-01-01 00:00:00",
        "ylt2": "2079-01-01 00:00:00",
        "yt": null,
        "z0": {
            "a": "2015-10-22 14:46",
            "b": null,
            "c": "",
            "d": "",
            "z": "The item is on transport to the country of destination"
        },
        "z1": [
            {
            "a": "2015-10-22 14:46",
            "b": null,
            "c": "",
            "d": "",
            "z": "The item is on transport to the country of destination"
            },
            {
            "a": "2015-10-22 11:36",
            "b": null,
            "c": "",
            "d": "",
            "z": "The item is at the PostNL sorting center"
            },
            {
            "a": "2015-10-20 09:13",
            "b": null,
            "c": "",
            "d": "",
            "z": "The item is pre-advised"
            }
        ],
        "z2": []
    }
}

explanation.json

"ret": "return code (1 == OK); -8 means that you need to solve a captcha which you can get /f/firewallcaptchahandler.ashx?get=image&d=RANDOMNESS and verify using /f/firewallcaptchahandler.ashx?get=validationresult&i=CAPTCHA&d=RANDOMNESS, you can then requery the API",
"msg": "return code converted to text ('Ok' for example)",
"dat": {
	"a": "Tracking number",
	"b": "Origin (COUNTRY_ENUM)",
	"c": "Destination (COUNTRY_ENUM) (0 if it's a non-international package or the API couldn't find the destination country (yet))",
	"d": "package type (PACKAGETYPE_ENUM)",
	"e": "package status (in transit, delivered, …) (PACKAGESTATE_ENUM)",
	"f": "? (sometimes -1, sometimes 1 - I really have no clue about this one)",
	"ln1": "language of tracking information (origin country)",
	"ln2": "language of tracking information (destination country)",
	"is1": "status of origin country's tracking (OK, web error, service error, …) (INFOSTATE_ENUM)",
	"is2": "status of destination country's tracking (OK, web error, service error, …) (INFOSTATE_ENUM)",
	"ygt1": "time needed for tracking (origin country) -> cached result if 0",
	"ygt1": "time needed for tracking (destination country) -> cached result if 0",
	"ylt1": "cache time UTC (origin country)",
	"ylt2": "cache time UTC (destination country)",
	"yt": "assumptions where the package might belong to, JSON data, contains country and package type codes which should be supplied to the API using the GET parameters cm and pt",
	"z0": {
		".": "latest tracking entry",
		"a": "date (local time)",
		"b": "?",
		"c": "information on location (empty for some mail services)",
		"d": "?",
		"z": "information text",
	},
	"z1": {
		".": "tracking history (array of all entries)",
		"a": "date (local time)",
		"b": "?",
		"c": "information on location (empty for some mail services)",
		"d": "?",
		"z": "information text",
	},
	"z2": {
		".": "? (might be tracking history of the destination country)",
	},
},

referencescript.js

// This script shall provide you a reference on what you can do with the data the API provides you with
// It is a plugin for the IRC bot GLaDOS (https://github.com/maddin77/GLaDOS).
// As you can see the bot will send up to 3 retry requests. This is done because the API likes to deliver no data at all sometimes.

var request = require('request');

module.exports = function (scriptLoader) {
    countries = {
        0: { country: "Unknown" },
        102: { country: "Afghanistan" },
        103: { country: "Albania" },
        104: { country: "Algeria" },
        105: { country: "Andorra" },
        106: { country: "Angola" },
        108: { country: "Antarctica" },
        110: { country: "Antigua and Barbuda" },
        112: { country: "Argentina" },
        113: { country: "Armenia" },
        115: { country: "Australia" },
        116: { country: "Austria" },
        117: { country: "Azerbaijan" },
        201: { country: "Bahamas" },
        202: { country: "Bahrain" },
        203: { country: "Bangladesh" },
        204: { country: "Barbados" },
        205: { country: "Belarus" },
        206: { country: "Belgium" },
        207: { country: "Belize" },
        208: { country: "Benin" },
        210: { country: "Bhutan" },
        211: { country: "Bolivia" },
        212: { country: "Bosnia and Herzegovina" },
        213: { country: "Botswana" },
        215: { country: "Brazil" },
        216: { country: "Brunei" },
        217: { country: "Bulgaria" },
        218: { country: "Burkina Faso" },
        219: { country: "Burundi" },
        301: { country: "China" },
        302: { country: "Cambodia" },
        303: { country: "Cameroon" },
        304: { country: "Canada" },
        306: { country: "Cape Verde" },
        308: { country: "Central African Republic" },
        310: { country: "Chile" },
        312: { country: "Ivory Coast" },
        313: { country: "Colombia" },
        314: { country: "Comoros" },
        315: { country: "Congo-Brazzaville" },
        316: { country: "Congo-Kinshasa" },
        317: { country: "Cook Islands" },
        318: { country: "Costa Rica" },
        319: { country: "Croatia" },
        320: { country: "Cuba" },
        321: { country: "Cyprus" },
        322: { country: "Czech Republic" },
        323: { country: "Chad" },
        401: { country: "Denmark" },
        402: { country: "Djibouti" },
        403: { country: "Dominica" },
        404: { country: "Dominican Republic" },
        501: { country: "Ecuador" },
        502: { country: "Egypt" },
        503: { country: "United Arab Emirates" },
        504: { country: "Estonia" },
        505: { country: "Ethiopia" },
        506: { country: "Eritrea" },
        507: { country: "Equatorial Guinea" },
        508: { country: "East Timor" },
        603: { country: "Fiji" },
        604: { country: "Finland" },
        605: { country: "France" },
        701: { country: "Gabon" },
        702: { country: "Gambia" },
        703: { country: "Georgia" },
        704: { country: "Germany" },
        705: { country: "Ghana" },
        707: { country: "Greece" },
        709: { country: "Grenada" },
        712: { country: "Guatemala" },
        713: { country: "Guinea" },
        714: { country: "Guyana" },
        716: { country: "Guinea-Bissau" },
        801: { country: "Hong Kong [CN]" },
        802: { country: "Haiti" },
        804: { country: "Honduras" },
        805: { country: "Hungary" },
        901: { country: "Iceland" },
        902: { country: "India" },
        903: { country: "Indonesia" },
        904: { country: "Iran" },
        905: { country: "Ireland" },
        906: { country: "Israel" },
        907: { country: "Italy" },
        908: { country: "Iraq" },
        1001: { country: "Jamaica" },
        1002: { country: "Japan" },
        1003: { country: "Jordan" },
        1101: { country: "Kazakhstan" },
        1102: { country: "Kenya" },
        1103: { country: "United Kingdom" },
        1104: { country: "Kiribati" },
        1105: { country: "Korea, South" },
        1106: { country: "Korea, North" },
        1107: { country: "Kosovo" },
        1108: { country: "Kuwait" },
        1109: { country: "Kyrgyzstan" },
        1201: { country: "Laos" },
        1202: { country: "Latvia" },
        1203: { country: "Lebanon" },
        1204: { country: "Lesotho" },
        1205: { country: "Liberia" },
        1206: { country: "Libya" },
        1207: { country: "Liechtenstein" },
        1208: { country: "Lithuania" },
        1209: { country: "Saint Lucia" },
        1210: { country: "Luxembourg" },
        1301: { country: "Macao [CN]" },
        1302: { country: "Macedonia" },
        1303: { country: "Madagascar" },
        1304: { country: "Malawi" },
        1305: { country: "Malaysia" },
        1306: { country: "Maldives" },
        1307: { country: "Mali" },
        1308: { country: "Malta" },
        1310: { country: "Marshall Islands" },
        1312: { country: "Mauritania" },
        1313: { country: "Mauritius" },
        1314: { country: "Mexico" },
        1315: { country: "Federated States of Micronesia" },
        1316: { country: "Moldova" },
        1317: { country: "Monaco" },
        1318: { country: "Mongolia" },
        1319: { country: "Montenegro" },
        1321: { country: "Morocco" },
        1322: { country: "Mozambique" },
        1323: { country: "Myanmar" },
        1401: { country: "Namibia" },
        1402: { country: "Nauru" },
        1403: { country: "Nepal" },
        1404: { country: "Netherlands" },
        1406: { country: "New Zealand" },
        1407: { country: "Nicaragua" },
        1408: { country: "Norway" },
        1409: { country: "Niger" },
        1410: { country: "Nigeria" },
        1501: { country: "Oman" },
        1601: { country: "Pakistan" },
        1602: { country: "Palestine" },
        1603: { country: "Panama" },
        1604: { country: "Papua New Guinea" },
        1605: { country: "Paraguay" },
        1606: { country: "Peru" },
        1607: { country: "Philippines" },
        1608: { country: "Poland" },
        1610: { country: "Portugal" },
        1614: { country: "Palau" },
        1701: { country: "Qatar" },
        1802: { country: "Romania" },
        1803: { country: "Russian Federation" },
        1804: { country: "Rwanda" },
        1902: { country: "Saint Vincent and the Grenadines" },
        1903: { country: "El Salvador" },
        1905: { country: "San Marino" },
        1906: { country: "Sao Tome and Principe" },
        1907: { country: "Saudi Arabia" },
        1908: { country: "Senegal" },
        1909: { country: "Serbia" },
        1911: { country: "Seychelles" },
        1912: { country: "Sierra Leone" },
        1913: { country: "Singapore" },
        1914: { country: "Slovakia" },
        1915: { country: "Slovenia" },
        1916: { country: "Solomon Islands" },
        1917: { country: "South Africa" },
        1918: { country: "Spain" },
        1919: { country: "Sri Lanka" },
        1920: { country: "Sudan" },
        1921: { country: "Suriname" },
        1923: { country: "Swaziland" },
        1924: { country: "Sweden" },
        1925: { country: "Switzerland" },
        1926: { country: "Syrian Arab Republic" },
        1927: { country: "Saint Kitts and Nevis" },
        1928: { country: "Samoa" },
        1929: { country: "Somalia" },
        1930: { country: "Scotland" },
        1932: { country: "South Ossetia" },
        2001: { country: "Taiwan [CN]" },
        2002: { country: "Tajikistan" },
        2003: { country: "Tanzania" },
        2004: { country: "Thailand" },
        2005: { country: "Togo" },
        2006: { country: "Tonga" },
        2007: { country: "Trinidad and Tobago" },
        2009: { country: "Tuvalu" },
        2010: { country: "Tunisia" },
        2011: { country: "Turkey" },
        2012: { country: "Turkmenistan" },
        2101: { country: "Uganda" },
        2102: { country: "Ukraine" },
        2103: { country: "Uzbekistan" },
        2104: { country: "Uruguay" },
        2105: { country: "United States" },
        2202: { country: "Vanuatu" },
        2203: { country: "Venezuela" },
        2204: { country: "Vietnam" },
        2205: { country: "Vatican City" },
        2302: { country: "Western Sahara" },
        2501: { country: "Yemen" },
        2601: { country: "Zambia" },
        2602: { country: "Zimbabwe" },
        8901: { country: "Overseas Territory [ES]" },
        9001: { country: "Overseas Territory [GB]" },
        9002: { country: "Anguilla [GB]" },
        9003: { country: "Ascension [GB]" },
        9004: { country: "Bermuda [GB]" },
        9005: { country: "Cayman Islands [GB]" },
        9006: { country: "Gibraltar [GB]" },
        9007: { country: "Guernsey [GB]" },
        9008: { country: "Saint Helena [GB]" },
        9101: { country: "Overseas Territory [FI]" },
        9102: { country: "Ã…aland Islands [FI]" },
        9201: { country: "Overseas Territory [NL]" },
        9202: { country: "Antilles [NL]" },
        9203: { country: "Aruba [NL]" },
        9301: { country: "Overseas Territory [PT]" },
        9401: { country: "Overseas Territory [NO]" },
        9501: { country: "Overseas Territory [AU]" },
        9502: { country: "Norfolk Island [AU]" },
        9601: { country: "Overseas Territory [DK]" },
        9602: { country: "Faroe Islands [DK]" },
        9603: { country: "Greenland [DK]" },
        9701: { country: "Overseas Territory [FR]" },
        9702: { country: "New Caledonia [FR]" },
        9801: { country: "Overseas Territory [US]" },
        9901: { country: "Overseas Territory [NZ]" }
    };

    package_types = {
        0: { type: "Unknown package" },
        1: { type: "Small registered package" },
        2: { type: "Registered parcel" },
        3: { type: "EMS package" }
    };

    package_states = {
        0: { state: "not found" },
        10: { state: "in transit" },
        20: { state: "expired" },
        30: { state: "ready to be picked up" },
        40: { state: "delivered" },
        50: { state: "returned" }
    };

    var retry_counter = 0;

    function query_api(event) {
        request({
            "uri": "http://www.17track.net/r/handlertrack.ashx?num=" + event.params[0],
            "json": true,
            'headers': {
                "User-Agent": scriptLoader.connection.config.userAgent
            }
        }, function (error, response, json) {
            if (!error && response.statusCode === 200) {
                if (json.ret !== 1) {
                    event.channel.reply(event.user, "Error while trying to query the tracking number: " + json.msg);
                } else if (json.dat.b === 0) {
                    if(retry_counter < 3) {
                        retry_counter++;
                        scriptLoader.debug('[17track] query retry #%d', retry_counter);
                        query_api(event);
                    } else {
                        event.channel.reply(event.user, "Unknown or invalid tracking number. If you're sure it's correct, then please try again since there seem to be random rate limits in the API.");
                    }
                } else {
                    retry_counter = 10;
                    latest_location = (json.dat.z0 != null && json.dat.z0.c != "") ? " in " + json.dat.z0.c : ""
                    latest_tracking_entry = json.dat.z0 != null ? json.dat.z0.z + " (at " + json.dat.z0.a + latest_location + ")" : "";
                    event.channel.reply(event.user, package_types[json.dat.d].type + " (" + countries[json.dat.b].country + " → " + countries[json.dat.c].country + "): " +
                    package_states[json.dat.e].state + " - " + latest_tracking_entry);
                }
            } else {
                event.channel.reply(event.user, 'Gratz. You broke it. (' + error + ')');
                scriptLoader.debug('[17track] %s', error);
            }
        });
    }

    scriptLoader.on('command', 'track', function (event) {
        if(event.params.length < 1) {
            event.user.notice("Use: track <tracking number>");
            return;
        }
        event.channel.reply(event.user, "Querying the 17track API. This can take up to a minute (or even longer, who knows?). Please be patient.");
        query_api(event);
    })
};