Ever seen a hashtag on Twitter, and wondered what it is all about? Now you can look it up, and cast your vote on the definitions. And if you don't like the definitions, or none exists, you can create your own in seconds.
The REST API currently 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>#ff is the same as (short for) #followfriday.</text>
<time>2009-05-08 00:00:00</time>
<upvotes>240</upvotes>
<downvotes>92</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).
If the tag exists in the Tagdef database, the HTTP status code is 200 OK, with a body in the following JSON format:
{
"defs": {
"def": {
"text": "#ff is the same as (short for) #followfriday.",
"time": "2009-05-08 00:00:00",
"upvotes": "240",
"downvotes": "92",
"uri": "http:\/\/tagdef.com\/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"
}
}
}
This API is free to use, but you must provide a clickable link back to the tagdef.com page for the given tag when displaing information from the API. This link can be found in the uri part of the reply, e.g.
<uri>http://tagdef.com/ff</uri>
Please let me know if you use this API. Feedback is welcome. If you have any questions, feel free to contact me at snokleby@gmail.com. If the licence doesn't fit, send me an email and we might work out a different solution.
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 #tag as definition interface.