UrbanScraper implements a simple API for accessing Urban Dictionary. Nick Charlton built this to get definitions through Alfred.
Note: This was built because Urban Dictionary doesn’t have their own API. To make it work, this relies on screen scraping. If you don’t get a result when you should, something has probably changed.
Get the top definition for a specified term. :term should be encoded according to
RFC 3986.
GET /define/:term
callback: A JSONP wrapper function. (optional).Status: 200 OK
{
"id": "1401399",
"term": "zomg",
"definition": "zOMG is a varient of the all-too-popular acronym \"OMG\"",
"example": "\"zOMG! you r teh winz!!one!!eleven!\"",
"author": "ectweak",
"author_url": "http://www.urbandictionary.com/author.php?author=ectweak",
"url": "http://www.urbandictionary.com/define.php?term=zomg&defid=1401399",
"posted": "2005-08-06T00:00:00+00:00"
}
A 404 error will be returned if no definitions can be found (see below).
Return a list of definitions of a term. :term should be encoded according to
RFC 3986.
GET /search/:term
callback: A JSONP wrapper function. (optional).Status: 200 OK
[{
"id": "1401399",
"term": "zomg",
"definition": "zOMG is a varient of the all-too-popular acronym \"OMG\"",
"example": "\"zOMG! you r teh winz!!one!!eleven!\"",
"author": "ectweak",
"author_url": "http://www.urbandictionary.com/author.php?author=ectweak",
"url": "http://www.urbandictionary.com/define.php?term=zomg&defid=1401399",
"posted": "2005-08-06T00:00:00+00:00"
},
{
"id": "2212015",
"term": "zomg",
"definition": "OMG was the ruler of the planet XYRZON until 2451 AD...",
"example": "ZOMG, i love cupcakes.",
"author": "WARRIOR MAN",
"author_url": "http://www.urbandictionary.com/author.php?author=WARRIOR+MAN",
"url": "http://www.urbandictionary.com/define.php?term=zomg&defid=2212015",
"posted": "2007-01-22T00:00:00+00:00"
},
...
]
Unlike the top definition, search won’t return an error if no reponse is found. Instead, the result will be an empty JSON array. It will return about 7 results, as this is where Urban Dictionary starts to page them.
All of the definition methods also support JSONP. This is useful if you’re trying to load these methods over JavaScript on another domain, allowing you to work around Cross Origin resource sharing issues.
You might use it like this:
GET /define/:term?callback=functionA
Status: 200 OK
functionA({
"id": "1401399",
"term": "zomg",
"definition": "zOMG is a varient of the all-too-popular acronym \"OMG\"",
"example": "\"zOMG! you r teh winz!!one!!eleven!\"",
"author": "ectweak",
"author_url": "http://www.urbandictionary.com/author.php?author=ectweak",
"url": "http://www.urbandictionary.com/define.php?term=zomg&defid=1401399",
"posted": "2005-08-06T00:00:00+00:00"
});
You’ll most likely see this if the term you requested wasn’t found at all. It’ll look a bit like this:
Status: 404 Not Found
{
"message": "No definitions could be found for: thvbqgfbhkrvjv."
}
If you miss-call a route, this will happen instead:
Status: 404 Not Found
{
"message": "Route not found. Check your syntax."
}
The code is up on GitHub. It’s MIT licensed. And, it’s hosted on Heroku.
The content is owned by those who submitted it to Urban Dictionary. Using this (presumably) puts you under the Urban Dictionary Terms of Service.
A little bit of caching is done on my side to keep the hits to Urban Dictionary down, but even then, please don’t abuse it. They probably wouldn’t like it.