TinyArrows for Developers

API Overview

We have a pretty straight-forward API for developers. This is used to create short links in the style and mode you like.

The default API call is simply this:
http://tinyarro.ws/api-create.php?url=http://www.example.com

Which will return something like this in raw HTML: http://➡.ws/abcb (which, when displayed on a website would look more like this: http://➡.ws/abcb)

api-create.php

api-create.php is the core API used to shrink URLs.

Note: Let's get this part over first. The most important thing to keep in mind is that the url param always has to be the final parameter in the query string. Yes, this is a violation of all things that are holy and sacred on the web, but we're trying to support URLs that sometimes come in unencoded. This is a pain for us, but we like to play extra nice.

Parameters

url - The URL you want to shrink. This parameter has to be last in the query string and is the most important part. Don't phone us without it.

Example: http://tinyarro.ws/api-create.php?url=http://www.example.com

host - This allows you to specify which of our domains you want the short URL to come from. We support a number of custom domains.

Example: http://tinyarro.ws/api-create.php?host=xn--5gi.ws&url=http://www.yumbunny.com

The following host parameters are supported as of the last time we updated this document:

• xn--ogi.ws for ➨.ws
• xn--vgi.ws for ➯.ws
• xn--3fi.ws for ➔.ws
• xn--egi.ws for ➞.ws
• xn--9gi.ws for ➽.ws
• xn--5gi.ws for ➹.ws
• xn--1ci.ws for ✩.ws
• xn--odi.ws for ✿.ws
• xn--rei.ws for ❥.ws
• xn--cwg.ws for ›.ws
• xn--bih.ws for ⌘.ws
• xn--fwg.ws for ‽.ws
• xn--l3h.ws for ☁.ws
• ta.gd for ta.gd

If you're familiar with IDN, you'll notice these are the punycode versions of the Unicode domains.

suggest - This allows you to try to specify your own word to use for the short URL. If it doesn't work, we'll respond with a random URL instead.

Example: http://tinyarro.ws/api-create.php?suggest=yumbunny&url=http://www.yumbunny.com

New: The suggest feature can now request non-unicode URL suffixes. If you set suggest=_nounicode then we'll try to send you a random ASCII-based URL suffix.

utfpure - Set this to 1 and we'll return the entire URL in UTF-8 without using HTML entity encoding for the hostname. We really recommend everyone use this, but the existing API can't be changed without breaking people who rely upon it.

Example: http://tinyarro.ws/api-create.php?utfpure=1&url=http://www.yumbunny.com

userid - Set this to the userid of a specific user and the tiny URL created will be registered with their account. (Note that user accounts haven't been made publicly available yet.)

Example: http://tinyarro.ws/api-create.php?userid=92839283&url=http://www.yumbunny.com/info/faq?new

idn-lookup.php

Description

Quick API that returns the punycode version of a link that uses an International Domain Name. Some platforms do not support automatic decoding of these links to their punycode/ASCII form, so this API may be handy for converting tinyarro.ws links to ASCII. iPhone is one such platform where NSURL doesn't quite support international domains in the API (even though Safari does).

Parameters

url - Provide the url-encoded unicode URL to convert to punycode.

Example

http://tinyarro.ws/idn-lookup.php?url=http%3A%2F%2F%E2%9E%A1.ws%2F6w

Returns: http://xn--hgi.ws/6w

idn-redirect.php

Description

Just like idn-lookup, but instead of returning the ASCII version of the IDN, it performs an HTTP redirect to the punycoded site. Use this if you need an easy mechanism to just quickly redirect a user to a domain you think may be IDN (though should work with any domain). Useful especially for platforms or browsers that don't have full IDN support built-in.

Parameters

url - Provide the url-encoded unicode URL to convert and then redirect the user.

Example

http://tinyarro.ws/idn-redirect.php?url=http%3A%2F%2F%E2%9E%A1.ws%2F6w

Would perform a 301 redirect to this url: http://xn--hgi.ws/6w