The tagdef API

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.

List of definitions for tag

https://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).

Example

https://api.tagdef.com/ff for the list in XML format.
https://api.tagdef.com/ff.json will give you the same list in JSON format.

Top definition for tag

http://api.tagdef.com/one.tagname

where tagname is the name of the tag, gives you the top ranking definition

Example

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.

Return content, XML

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>2118</upvotes>
        <downvotes>1497</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).

Return content, single JSON entry

A call using the one. modifier, e.g. e.g. http://api.tagdef.com/one.ff.json will return this format:

{
  "num_defs": "54",
  "defs": {
    "def": {
      "text": "#ff is the same as (short for) #followfriday.",
      "time": "2009-05-08 00:00:00",
      "upvotes": "2118",
      "downvotes": "1497",
      "uri": "http:\/\/tagdef.com\/ff",
      "hashtag": "ff"
    }
  }
}

Return content, multiple JSON entries

A call used without the .one modifier, e.g. http://api.tagdef.com/ff.json will give this format:

{
  "num_defs": "54",
  "defs": [
    {
      "def": {
        "text": "#ff is the same as (short for) #followfriday.",
        "time": "2009-05-08 00:00:00",
        "upvotes": "2118",
        "downvotes": "1497",
        "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": "1002",
        "downvotes": "527",
        "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": "748",
        "downvotes": "302",
        "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": "86",
        "downvotes": "52",
        "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": "84",
        "downvotes": "80",
        "uri": "http:\/\/tagdef.com\/ff",
        "hashtag": "ff"
      }
    }
  ]
}

Return content, No definition found

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"
    }
  }
}

JSON callback

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.

Example

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.

Force HTTP 200 return code

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

Example

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:

<!DOCTYPE html> <html> <head> <script src=”http://code.jquery.com/jquery-latest.js”></script> </head> <body> <h1 id=”tagresult”></h1> <script> $.getJSON(“https://api.tagdef.com/one.ff.json?no404=1&callback=?”, function(data) { if (data.defs.def.text === undefined) $(“#tagresult”).text(“Add your defintion at ” + data.defs.def.uri); else $(“#tagresult”).text(data.defs.def.text); }); </script> </body> </html>

Change the hashtag-part of the url to api.tagdef.com to a non-existing hashtag to see the behaviour for non-exsisting tags.

Secure

You can access the API securely by using the https version, e.g. https://api.tagdef.com/ff.

Multi language

add lang=lang-code to the request to filter the definitions by language.

Example

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

Licence

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.

Uptime and latency

Tagdef.com is constantly monitored for uptime and response-times from around the world. Visit the Pingdom reports for details.

Notes

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.