The kt.tn API

Introduction

An API, or application programming interface, allows developers or power users to access features of kt.tn without using our website. Anyone can easily integrate kt.tn directly into their website or other applications, at no cost.

The kt.tn API v1 is identical to the API of tr.im on github by the (now defunct) Nambu Network, Inc. and Eric Woodward (we even kept the prefix "trim" in the function names).

 

We have many API methods, divided into different logical sections, to access the entire kt.tn feature set. We stress simplicity here at kt.tn, so it is very easy to work with.

Our API supports XML and JSON response formats.

 

API Rate Limits

All kt.tn API methods are subject to rate limiting by IP address. The kt.tn API methods trim_url and trim_simple have a combined default rate limit of 48 new URLs per day, up to 10 per hour, per IP address. This is intentionally set on the low side to prevent any overwhelming malicious insertion of data into our database. trim_destination has the highest rate limit set -- generally the same number of URLs we create per day -- so that you can more efficiently determine the destinaion URL for all or any kt.tn URLs.

For most other methods other than these three, there is a limit of 1,500 requests per day, up to 120 per hour, per IP address. If this is too restrictive for your application, email us for an API key so we can customize your limits.

Please note: If your application hits an API limit you will get a kt.tn response code within your JSON or XML response clearly indicating this. If you ignore kt.tn response codes, and continue to make API requests well in excess of the limits for any method, we have automated protection systems in place that will ban your IP address for 48 hours for all methods, and access to all kt.tn websites. Please check these kt.tn API response codes. Almost no developers encounter this problem, but please prepare for the usage you expect, and help us keep kt.tn's API running smoothly.

For development and other testing please use the sandbox parameter on the trim_url and trim_simple methods to not actually create an operational kt.tn URL or consume any API rate limits. This will ensure you don't run into any API rate limit problems while in development.

API Keys

kt.tn API keys are for applications, not individual user accounts. If you have an application that may potentially require higher limits than those above -- such as if you are accessing multiple accounts from a single server IP address, for example -- you can request an API key that we can configure to bypass the default API limits. If you would like to get an increase, or may run into the limit because of a shared IP address, send an email to info@kt.tn and we can assign you an API key. API keys are also required for selected API methods.

JSON Callback

The kt.tn API will wrap a JSON response in a callback function if you add a callback parameter, and request the JSON response format.
   http://kt.tn/v1/trim_url.json?api_key=jiOWWs2zD8tE&url=http://www.google.com&callback=jsfunction

kt.tn Account Authentication

Many API methods can be sent a kt.tn account and password as appropriate or required. You can authenticate a kt.tn user account in one of two ways: 1) query string parameters; and 2) basic HTTP authentication. HTTP authentication is the preferred method, since query string parameters are potentially cached by proxies, potentially leaving the kt.tn username and password cached in the clear. However, we supply both options, and leave it up to the individual developer to determine which authentication method is the most appropriate for their purposes.

Response Codes

The kt.tn API responds with the following error codes:

 

API Methods

trim_url

This is the main method for the kt.tn API, to submit a destination URL and get a unique kt.tn URL. You can send additional configuration options, and attach any kt.tn URLs you create to an authenticated kt.tn account.

URL: http://api.kt.tn/v1/trim_url.<format>
Method: GET or POST
Formats: xml, json
Parameters:

url Required The destination URL to be shortened.
custom Optional A custom URL that is preferred to an auto-generated URL.
searchtags Optional A search string value to attach to a kt.tn URL.
privacycode Optional A string value that must be appended after the URL.
newtrim Optional If present with any value, it will force the creation of a new kt.tn URL.
api_key Optional An application API key assigned to your application.
sandbox Optional If present with any value a test data set will be returned, and no URL created. This is intended for testing so that you do not consume API calls or insert pointless data while in development.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.
url A unique kt.tn URL for the submitted destination URL.
trimpath The kt.tn URL's path string.
reference A unique string generated for each kt.tn URL for use with other API methods. We recommend that you save this reference code for use with future kt.tn API methods.

Notes:

Examples:

 

trim_simple

This method works exactly the same as the trim_url method, with exactly the same parameters and authentication options. However, it only returns the new kt.tn URL -- nothing more. If there was an error, such as a failed authentication attempt or an exceeded API rate limit, it will return nothing. For this reason we suggest that you do not use method, or use it with caution, since you cannot determine the nature of problems.

Examples:

 

trim_reference

This method will return the reference code for a kt.tn URL, if owned by the authenticated user.

URL: http://api.kt.tn/v1/trim_reference.<format>
Method: GET or POST
Formats: xml, json
Parameters:

trimpath Required The kt.tn URL's unique path string.
api_key Optional An application API key assigned to your application.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.
reference The kt.tn URL's reference code.

Example:

 

trim_claim

This method will attach an unattached kt.tn URL to the authenticated account, if you have the unique reference code for the kt.tn URL.

URL: http://api.kt.tn/v1/trim_claim.<format>
Method: GET or POST
Formats: xml, json
Parameters:

reference Required The kt.tn URL's unique reference string.
api_key Optional An application API key assigned to your application.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.

 

trim_destination

This method will return the destination URL that the kt.tn URL redirects to. Therefore, you do not need to request the URL to learn where it goes, and adversely affect kt.tn statistics. This method's response will also be faster that an HTTP redirection.

URL: http://api.kt.tn/v1/trim_destination.<format>
Method: GET or POST
Formats: xml, json
Parameters:

trimpath Required The kt.tn URL's unique path string.
api_key Optional An application API key assigned to your application.

Response:

status The result state, kt.tn response code, and a human readable message.

Example:

 

url_visits

This method will return visitation details specific to a single kt.tn URL. This enables the ability to construct a kt.tn URL statistics page in a style and colour scheme that matches your application. An API key is required to use this API method.

URL: http://api.kt.tn/v1/url_visits.<format>
Method: GET
Formats: xml, json
Parameters:

reference Required The kt.tn URL's unique reference string.
api_key Required An application API key assigned to your application.

Response:

status The result state, kt.tn response code, and a human readable message.
visits The date, time, and country for each visit.
total_visits The total number of visits the referenced kt.tn URL has had.

 

account_urls

This method returns the authenticated kt.tn account's kt.tn URLs with their visitation totals. No detailed visitation information is returned. This method is intended for generating an account's URL list. An API key is required to use this API method.

URL: http://api.kt.tn/v1/account_urls.<format>
Method: GET
Formats: xml, json
Parameters:

api_key Required An application API key assigned to your application.
count Optional The number of kt.tn URL data sets to return, from the most to the least recent. Defaults to 20 if not present. A maximum of 100 is permitted.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.
urls A list of the returned kt.tn URLs and their destination domain name, shortened times and visitation count.
url_count The total URL count contained in the response.

 

account_visits

This method will return the kt.tn URLs for the authenticated kt.tn account with the visitation details. This is a heavier API method, so please use it only if you need the detailed information it contains. An API key is required to use this API method.

URL: http://api.kt.tn/v1/account_urls.<format>
Method: GET
Formats: xml, json
Parameters:

api_key Required An application API key assigned to your application.
count Optional The number of kt.tn URL data sets to return, from the most to the least recent. Defaults to 20 if not present. A maximum of 100 is permitted.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.
url_count The total URL count contained in the response.
urls A list of the returned kt.tn URLs and their individual visitation counts, with the date, time, and country.
total_visits The total number of visits recorded for the returned URLs.

 

verify

This method will return whether or not a username/password combination is a valid kt.tn account's username and password.

URL: http://api.kt.tn/v1/verify.<format>
Method: GET or POST
Formats: xml, json
Parameters:

api_key Optional An application API key assigned to your application.
username Optional A kt.tn username that you would like to attach the URL to.
password Optional The password for the kt.tn username referenced above.

Response:

status The result state, kt.tn response code, and a human readable message.

 

shorteners

This method will return the domain names currently configured as domain name shortening services that kt.tn will not permit to be present within the destination URL.

URL: http://api.kt.tn/v1/shorteners.<format>
Method: GET
Formats: xml, json
Parameters:

api_key Optional An application API key assigned to your application.

Response:

status The result state, kt.tn response code, and a human readable message.
domains The list of domain names configured within kt.tn as disallowed shortener domain names.

Notes:

 

shorten

This is an alternative method to shorten a destination URL, based on an older version of bit.ly's API. We mirror their main arguments and response formats.

URL: http://api.kt.tn/v1/shorten
Method: GET or POST
Format: json
Parameters:

apiKey Required An application API key assigned to your application.
version Required Set this to 2.0.1. This is the version of the bit.ly response we have cloned.
longUrl Required The destination URL to be shortened.

Response:

errorCode The error code if an error code occurred, otherwise 0.
errorMessage The error code if an error code occurred, otherwise an empty string.
results A hash of the results based on the destination URL as the key, as per bit.ly's implementation.

Examples:

 

expand

This is an alternative method to determination the destination URL for a kt.tn URL via the API, based on an older version of bit.ly's API. We mirror their main arguments and response format.

URL: http://api.kt.tn/v1/expand
Method: GET
Format: json
Parameters:

apiKey Required An application API key assigned to your application.
version Required Set this to 2.0.1. This is the version of the bit.ly response we have cloned.
shortUrl Required The path of the kt.tn URL. Please note, this is not an URL, as bit.ly named it. It is the path string, such as "AbcD" within the kt.tn URL.

Response:

errorCode The error code if an error code occurred, otherwise 0.
errorMessage The error code if an error code occurred, otherwise an empty string.
results A hash of the results based on the "shortUrl" as the key, as per bit.ly's implementation.

Examples:

 

 

Frequently Asked Questions

Do I need to get an API key to use the kt.tn API?

No. You can access the main method to submit a destination URL and get a new kt.tn URL without an API key. However, to access any of the kt.tn account or URL statistics methods, you will need an API key. On the specification for each method we specify whether or not it requires an API key. Anyone can get an API key by emailing us at info@kt.tn.

Are API keys attached to a kt.tn account?

No. kt.tn API keys are for applications, not user accounts. When you ask for an API key by emailing us at info@kt.tn you do not need to sign up for, have, or send us your kt.tn account username.

Can I get a rate limit increase?

Yes, of course. If you need an increease we can assign a set of custom API limits for your kt.tn API key. Just email us if you hit API limits, or expect to. Custom API limits are usually only necessary if your application submits many requests to our API via a set of the same IP server addresses.

Why has my IP address been banned?

We have automated API protection measures in place to protect our API from excessive requests and attacks. If you are using the API and are repeatedly seeing the kt.tn response code for an API rate limit -- code 425 -- and you continue submitting requests 10x in excess of the API limit you are up against, we automatically ban your IP address for 48 hours. You need to check the kt.tn response code if you are submitting lots of requests to us from the same IP address.

For initial development against the kt.tn API we recommend that you use the sandbox parameter avaiable on the trim_url and trim_simple API methods. When present any calls will not create actual URLs, and therefore will not count towards any API limits. These methods will still return a sample data set for you to experiment and develop with.

What is a kt.tn URL reference code?

When you a create a kt.tn URL with the API's trim_url creation method we return to you in the response data a unique string called a "reference" code. This is a unique string that cannot be guessed, and allows you to request statistics for this URL from the API without having a kt.tn account, or having formal ownership of the kt.tn URL. The intent is to allow developers to access API methods for a specific URL without implementing account attachment if it is not applicable for their specific purposes. Therefore, anywhere in the API specifications that call for a reference code, it is requesting this unique string, not the kt.tn path. The kt.tn path is publicly known and guessable, and provides no measure of secure access.

How do these API response codes work? Are they HTTP codes?

There are two types of response codes when working with the kt.tn API: 1) the HTTP response code; and 2) the kt.tn API result code. We decided not to mix the two. Unless there is a genuine HTTP or network error, or excessive requests beyond the API rate limit, the kt.tn API will always respond with a 200 HTTP code. The kt.tn response codes with the status response data set then indicate the result of the request as it was completed within kt.tn. You need to check these response codes, depending on the method you are working with, to ensure the requested was completed properly.