The (secret (?)) 17track API and how to use it

Yay, another English article. I normally don’t do this unless the article might provide some information which isn’t available anywhere else (yet).
This article will cover the more or less secret 17track API and how you can integrate it into your applications.

NOTE: This does currently *NOT* work anymore. 17track basically redesigned their site and the API. It moved to a new place, it needs new parameters to function (which I didn’t figure out yet) and probably even returns different data. The following article is related to the old API which is not accessible any longer. Thank you for your attention.

If you found this article on Google: I’m sorry, my English really isn’t the best on the world but I hope it’s enough to explain some of the aspects of the API. If you find any obvious mistakes, please feel free to correct me in the comments.

So, let’s get started. Finding the API itself isn’t too hard. The URL’s there in plain text after digging through the iFrame widget’s source code which 17track provides for public usage. The URL of the API is where NUM is the tracking number you want to track. Apart from num there isn’t really any parameter you need or even want to use (well, almost none, but I’m going to cover this later on). There isn’t any format parameter so you’re forced to parse the format 17track provides you with. But this shouldn’t be a problem at all since it’s JSON and everybody loves JSON, right?

First of all, after you send the request you have to wait patiently for 10 to 30 seconds, depending on how fast 17track can get and parse the tracking web pages. So if you have any timeout option, you might want to set that to 60 seconds or something and you definitely want to inform your user that loading the results *will* take some time.

When the API finally returns a result to you, you’re encountered with weirdly labeled variables so this gist will try to cover what they could mean:
This was „mined“ using three tracking numbers – Germany to Germany, China to Germany and Netherlands to Germany. Feel free to fork and extend this since I wasn’t able to find a meaning behind every variable using just those three tracking numbers. There’s also a reference script in there now. This way you can get an impression on how you can use that data.

The API will, if it isn’t sure where the package belongs to, ask you to specify a country and package type code. Possible codes will be given to you as JSON data in For this matter there are two more GET parameters: cm and pt, which are the country and package type codes respectively.

All the *_ENUM variables can be found in the _vars/en.js file which is publicly available on 17track’s servers. You should probably use something like on it so it’s actually readable.

If most of the values are 0 in the result you received, you should probably query the API again. It seems to rate limit you after some tries. Also, if no cache time is available, it will fall back to 2079-01-01 00:00:00.

If you need the country’s tracking site URL, you can look it up in window.POST_ENUM. The IDs are constructed of the country’s ID and some index in case the country has multiple tracking sites. The index will start at 1.

In case you need to translate the tracking entries you can just use some translation service like Bing or Google Translate. Bing will support all the languages the 17track API might return (since 17track uses Bing to translate the entries, too).

Apart from that I just want to point out that I am not affiliated with 17track in any way and that the API might change at anytime so don’t count on it. I found some Russian forum posts covering the API just from last year and it heavily changed since those posts were made.

You know more about the 17track API? Good! Feel free to drop me a comment so I can extend this article with more knowledge.

That’s it for now. See ya.

2 Gedanken zu „The (secret (?)) 17track API and how to use it

  1. Sophie

    A great blog you wrote i’m impressed, actually, 17track what we designed. And it’s not easy to crank our api design, and you did. You must be really good at programing… now we’ve redesigned the whole system, please don’t crank it again… Lol.. if you find ways to crank, let me know~~Nice to know you.


Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.