Making ugly URLs decent


A bookmarklet is a special link you drag to your bookmarks toolbar or add to Favorites/Links, and then whenever you click the bookmarklet it’ll run DecentURL on the address of the current page. Here are two DecentURL bookmarklets:

Let-you-choose bookmarklet (recommended): Requires two clicks, but lets you make sure you’re happy with the title before it creates the decent URL. To use it, just drag this link to your toolbar: DecentURL.

Auto-submit bookmarklet: This one was inspired by Ricardo Cabral’s one, and it tells DecentURL to create the URL immediately. It’s a one-click process, but you don’t get to change the title if you don’t like it. Again, to use it, just drag this link to your toolbar: DecentURL!

And here are versions that open in a new tab, by Joerg Schumann (great for Firefox, but IE7 considers the “new tab” a popup, and blocks it):


Note: You now need an API key for the api-get call. Just donate a small amount if you’d like a username (and API key), and your API key will be shown at the bottom of your “my urls” page.

DecentURL has a simple programming interface that returns results as JSON data, so it’s great for use in JavaScript, Python, etc. There are commands to get a decent URL or resolve one, and I’ve also exposed the commands used internally by DecentURL to get a web page’s <title> and a URL’s domain.

You could dig into some code straight away and grab, a DecentURL module for Python, or go to Matthew D’s PHP version.

Or just click an example below to see how it works. The full URL for API calls is but I’ve left off the domain for brevity.

api-get: Get or create a decent URL

Call api-get?u=URL&t=TITLE&k=APIKEY and get [status, decent, canonical_url, full_decent].

api-resolve: Convert a decent URL back to the ugly original

Call api-resolve?d=DECENT and get [status, url, utc_date_created].

api-title: Get a page’s <title>

Call api-title?u=URL&l=MAXLEN and get [status, title, decent_title].

api-domain: Get a URL’s base domain

Call api-domain?u=URL&l=MAXLEN and get [status, base_domain].

Query parameters

Use something like JavaScript’s encodeURIComponent() or Python’s urllib.quote() on the query parameters, which are as follows:

Status codes

Note that on errors (non-ok codes) the API doesn’t return the rest of the results – they’d be invalid anyway.

To report bugs or suggest improvements, please contact me. advertisement