You can use this API to get definitions for hashtags in your application. It is free to use, but please read the short licence at the bottom of this page.
This API contains two forms of resources. One that gives you a sorted list of definitions for a tag, the other give you the top definition for the tag.
The default format is XML. To get JSON, add .json to the url.
http://api.tagdef.com/tagname
where tagname is the name of the tag, gives you a list of up to five definitions, sorted by user votes (highest net votes first).
http://api.tagdef.com/ff for the list in XML format.
http://api.tagdef.com/ff.json will give you the same list in JSON format.
http://api.tagdef.com/one.tagname
where tagname is the name of the tag, gives you the top ranking definition
http://api.tagdef.com/one.ff for the entry in XML format.
http://api.tagdef.com/one.ff.json will give you the same entry in JSON format.
If the tag exists in the Tagdef database, the status code is 200 OK, with a body in the following XML format:
<?xml version="1.0" encoding="UTF-8"?>
<defs>
<def>
<text>
<![CDATA[#ff is the same as (short for) #followfriday.]]>
</text>
<time>2009-05-08 00:00:00</time>
<upvotes>2009</upvotes>
<downvotes>1388</downvotes>
<uri>http://tagdef.com/ff</uri>
</def>
</defs>
If the tag is not found, the HTTP status code is 404, and the return body only contains the uri to the page that can be used to define the tag:
<?xml version="1.0" encoding="UTF-8"?>
<defs>
<uri>http://tagdef.com/nonexisting</uri>
<def>
<uri>http://tagdef.com/nonexisting</uri>
</def>
</defs>
(Yes, the uri is in there twice, due to backwards compatibility. Pick the one you like).
A call using the one. modifier, e.g. e.g. http://api.tagdef.com/one.ff.json will return this format:
{
"num_defs": "47",
"defs": {
"def": {
"text": "#ff is the same as (short for) #followfriday.",
"time": "2009-05-08 00:00:00",
"upvotes": "2009",
"downvotes": "1388",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
}
}
A call used without the .one modifier, e.g. http://api.tagdef.com/ff.json will give this format:
{
"num_defs": "47",
"defs": [
{
"def": {
"text": "#ff is the same as (short for) #followfriday.",
"time": "2009-05-08 00:00:00",
"upvotes": "2009",
"downvotes": "1388",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
},
{
"def": {
"text": "Every friday you can use #followfriday (#FF) to suggest people to follow.",
"time": "2010-05-28 17:04:37",
"upvotes": "980",
"downvotes": "514",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
},
{
"def": {
"text": "Using #ff (or #followfriday) in a tweet along with 1 or more @names means you recommend those people as worth following.",
"time": "2010-10-29 08:40:26",
"upvotes": "739",
"downvotes": "297",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
},
{
"def": {
"text": "Recomendacion que haces a tus seguidores acerca de una persona que deberian seguir,",
"time": "2010-08-18 03:25:50",
"upvotes": "68",
"downvotes": "31",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
},
{
"def": {
"text": "It means follow friday. It's a special day to follow as many times as possible. (just for those who want, of course!)",
"time": "2010-05-17 15:39:16",
"upvotes": "81",
"downvotes": "76",
"uri": "http:\/\/tagdef.com\/ff",
"hashtag": "ff"
}
}
]
}
If the tag is not found, the HTTP status code is 404, and the return body only contains the uri to the page that can be used to define the tag:
{
"defs": {
"def": {
"uri": "http:\/\/tagdef.com\/nonexisting"
}
}
}
Using the callback= parameter, you can specify a callback to the JSON API. The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing. Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9) and underscore (_).
http://api.tagdef.com/one.tagname.json?callback=my_callback
where my_callback is the name of the callback.
http://api.tagdef.com/one.ff.json?callback=my_callback:
my_callback(...);
Because JSON output is native JavaScript, you do not have to parse or evaluate the returned object in your callback function. You can immediately access the elements inside it, just as if you had passed an object reference to your ws_result function.
By default the API will return an HTTP 404 return code if the definition is not found. If you are working with javascript and json-callbacks, this might not be what you want. To force the API to always return a 200 response, use the parameter no404=1
http://api.tagdef.com/unknowntag.json?callback=MyCallback&no404=1
Here is an example of how you can use this to write a simple client using jQuery:
Change the hashtag-part of the url to api.tagdef.com to a non-existing hashtag to see the behaviour for non-exsisting tags.
You can access the API securely by using the https version, e.g. https://api.tagdef.com/ff.
add lang=lang-code to the request to filter the definitions by language.
http://api.tagdef.com/ff.json?lang=en Will give you only English results
http://api.tagdef.com/ff.json?lang=es Will give you only Spanish results
Here is a list of valid language-codes:
en - english
es - spanish
pt - portuguese
fr - french
de - german
id - indonesian
it - italian
nl - dutch
int - the rest
This API is free to use, but you must provide a clickable link back to the tagdef.com page for the given tag when using information from the API. The link cannot have a rel=nofollow attribute. This link can be found in the uri part of the reply, e.g.
<uri>http://tagdef.com/ff</uri>
You are not allowed to use this api in a service that is competing with tagdef.com, without a permission from the owner of tagdef.com
Scraping of the site is not allowed.
Please let me know if you use this API. Feedback is welcome. If you have any questions, feel free to send an email. If the licence doesn't fit, send an email and we can discuss it.
Tagdef.com is constantly monitored for uptime and response-times from around the world. Visit the Pingdom reports for details.
The only supported HTTP Method at the moment is GET. To add definitions, refer your users to the web-interface, or use the twitter @tagdef define #tag as definition interface.