REST API Documentation

Custom applications built on the Tiny API. Limited use of our API is free.
We also offer high volume URL shortening platforms with custom features. All complete on a private server and dedicated IP; just set up your branded shortening domain and its ready to go. No project is too big or too small. Let us handle all admin and maintenance details. $.001/URL/month. See plans.

API Key

You will need to use an API Key in order to access the tiny.cc API.
Login to generate an API key.

Rate Limiting

Development requests are limited to 50 per day, and no more than 5 concurrent requests from a single IP address at a time. If your testing exceeds these limits or you go to production, please see plans. Do you have unique usage case that doesn't seem to fit what we offer? We can also provide custom solutions for your projects.

API Requests

All API calls require a fundamental call to our API object and starts with this method : http://tiny.cc/?c=rest_api

All API calls require authentication credentials to be supplied as query arguments.

login=login&apiKey=apiKey

All API calls require a version identifier to be present:

version=2.0.3 All API calls support an optional return format ('json' by default. 'xml' also available):

format=json All API calls support an optional callback specifier for use with json return format:

callback=callback All API calls support both GET -and- POST request methods.


API Response

All API calls will return with the following response values:
errorCode - The error code if an error occurred, otherwise 0.
errorMessage - The error message if an error occurred, otherwise empty.
results - The results of a successful requested method, otherwise empty.
status - The human readable status. values are 'OK', 'ERROR'.

API Methods


shorten

Accepts a long url and returns a tiny.cc short url.


Parameters
longUrl - the long url to shorten. url escaped and urlencoded (a php function).
shortUrl - your custom url, (for example - shortUrl=&longUrl), if empty a default url will be generated.

Response:
shortUrl - the new tiny.cc short url
userHash - the new tiny.cc short url hash
hash - the new tiny.cc short url hash

Example to copy, paste and edit:



shorten (with custom hash)

Accepts a long url and hash and returns a tiny.cc custom url.


Parameters
longUrl - the long url to shorten. url escaped and urlencoded (a php function).
shortUrl - your custom url, (for example - shortUrl=&longUrl), if empty a default url will be generated.

Response:
shortUrl - the new tiny.cc short url
userHash - the new tiny.cc short url hash
hash - the new tiny.cc short url hash

Example to copy, paste and edit:



expand

Accepts a tiny.cc short url and returns the long url.


Parameters
shortUrl - the short url to expand.
hash - the tiny.cc Url Hash to expand.

Response:
longUrl - the long url


Example to copy, paste and edit:



expand_batch

Accepts array of tiny.cc short urls and returns the array of pairs of long url and short url. Maximum number of results requested in each call - 30.


Parameters
shortUrls - the array of short urls to expand.
hashes - the array of tiny.cc Url Hashes to expand.

Response - array of pairs:
longUrl - the long url
hash - the tiny.cc hash (as provided)


Example to copy, paste and edit:



total_visits

Accepts a tiny.cc short url and returns the total visits.


Parameters
shortUrl - the short url to get visit totals.
hash - the tiny.cc Url Hash to get visit totals.

Response:
clicks - the total number of visits to this tiny.cc short url
hash - the tiny.cc hash (as provided)


Example to copy, paste and edit:



total_visits_batch

Accepts array of tiny.cc short urls and returns the total visits for each short url. Maximum number of results requested in each call - 30.


Parameters
shortUrls - the array of short urls to get visit totals.
hashes - the array of tiny.cc Url Hashes to get visit totals.

Response - array of pairs:
clicks - the total number of visits to this tiny.cc short url
hash - the tiny.cc hash (as provided)


Example to copy, paste and edit:



edit

Edit a tiny.cc short url and long url.


Parameters
longUrl - the long url to edit. url escaped and urlencoded (a php function).
shortUrl - the short url to edit.
hash - the old tiny.cc Url Hash.

Response:
longUrl - the new tiny.cc long url
shortUrl - the new tiny.cc short url
hash - the new tiny.cc short url hash


Example to copy, paste and edit:



delete

Delete a tiny.cc url.


Parameters
delete - include this parameter in request.
hash - the to-be-deleted tiny.cc Url Hash.

Example to copy, paste and edit:



get_requests_count

Retrieve your account's remaining request limit - for the day.


Parameters
get_requests_count - include this parameter in request.

Response:
number - remaining requests out of 500 (or whatever your current daily limit is).


Example to copy, paste and edit:



API Error Codes

101 -- 'Unknown error'
202 -- 'Undefined method'
205 -- 'Invalid username or API key. Or failed to urlencode (php function)'
206 -- 'You specified an invalid version number. Valid version is [2.0.3].'
503 -- 'Service unavailable or request limit hit.'
1102 -- 'Invalid username.'
1204 -- 'Not a valid Short URL hash.'
1205 -- 'Traffic lookup for that hash failed.'
1206 -- 'URL you tried to shorten was invalid.'
1213 -- 'We could not find a long URL for that short URL.'
1214 -- 'URL you tried to shorten was already a short URL.'
1215 -- 'Short URL is not correct or does not exist.'
1216 -- 'URL you tried to shorten is not allowed.'
1217 -- 'Access Denied.'
1218 -- 'Short URL is not correct.'
1219 -- 'Target server on cooldown.'
1220 -- 'URLs limit has been reached.'
1221 -- 'Exceeded limit of batch operation.'


URLs submitted through the API should be URL-encoded

• URL-encoded query strings with PHP.
• URL-encoded query strings with online form.