GiveALink | GiveALink API

API Methods

User

User.getAnnotations

Url

Annotation

Post

Givealink API Documentation

Overview

The Givealink API allows you to call methods that respond in REST style xml. The API root URL is located at http://givealink.org/api/2.0/. Some methods are public, i.e., they do not require user authentication, while others are private, e.g., write services. A user wanting to invoke a private method needs to be authenticated by way of the scheme described in the Authentication How-To section.

Encoding

Use UTF-8 encoding when sending arguments to API methods.

Request Styles

The Consumer sends a request to the root URL specifying a method in the form package.method with a set of parameters (required plus possible optional). The API action is specified via the required parameter method.

For example, the call http://givealink.org/api/2.0/?method=tag.getTopTags&limit=10&api_key=XXXXXX invokes the method tag.getTopTags with the parameter n specifying the number of most popular tags to return.

Response Styles

The API responds in XML format following the template below:

    <givealink status="status_message">
      payload
    </givealink>

where status_message : [ok|fail] and payload is the content of the reply.

Example:

    <givealink status="ok">
      response of the API call
    </givealink>

Or in the case of error:

    <givealink status="fail">
      <message>error_message</message>
      <code>error_code</code>
    </givealink>

where error_code and error_message depend on the called API method.

Authentication

The authentication protocol allows you to perform actions on user accounts in a manner that is secure for Givealink users. All write services require authentication. Givealink is a OAuth Service Provider using OAuth for user authorization. See the Authentication How-To for more details.

Givealink provides authentication methods to the following URLs:

Get an Unauthorized Request Token: http://givealink.org/oauth/request_token
Obtaining User Authorization: http://givealink.org/oauth/authorize
Get an Access Token: http://givealink.org/oauth/access_token

Terms of use

Please use an identifiable User-Agent header on all requests. This reduces the risk of your application getting banned and helps our logging.

Use common sense when deciding how many calls to make. For example, if you're making a web application, try not to hit the API on page load. You account may be suspended if your application makes calls too frequently.

API methods specification

User.getAnnotations

Returns the set of annotations from a user

Params

api_key	required	A Givealink API key
user	required	Email of the user in question
tag	optional	A space separated list of tags
url	optional	A space separated list of urls
pag	optional	The page you want to fetch to (the result set is divided in pages of 40 elements)
limit	optional	Limit the amount of annotations returned
with_title	optional	Retrieve the title associated to an annotation (yes/no)
with_desc	optional	Retrieve the description associated to an annotation (yes/no)
with_time	optional	Retrieve the timestamp associated to an annotation (yes/no)

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
  <usergetannotations user="mario.rossi@givealink.org" page="1" nPages="22">
    <url name="http://news.cnet.com/" desc="Website dedicated to technology"
            title="Technology News - CNET News">
      <tag name="news" time="Mon Sep 14 15:59:17 +0200 2009">
      <tag name="tech" time="Mon Sep 14 16:22:45 +0200 2009">
    </url>
  ...
  </usergetannotations>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
12	WRONG_DATA_TYPE	Type not allowed in a parameter

Tag.delete

Delete a tag and all the related annotations

Params

user	required	User in question
tag	required	Tag to delete
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
10	UNKNOWN_TAG	Unknown tag in question
8	UNKNOWN_USER	Unknown user in question

Tag.getSimilar

Returns a list of tags similar to a given tag

Params

tag	required	Tag in question
api_key	required	A Givealink API key
limit	optional	Limit the amount of similar tags returned.maximum/default is 40)

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <taggetsimilar tag="news">
    <tag name="technology" sim="0.92385"/>
    <tag name="business" sim="0.92385"/>

    ...
  </taggetsimilar>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
10	UNKNOWN_TAG	Unknown tag in question

Tag.getTags

Returns a list of most used tags

Params

mode	optional	Choose which mode you want to use (top/random, default mode is top). When mode="top" it returns the most popular urls; when mode="random" it returns random urls.
spam	optional	Whether filter out the spam tags (yes/no, default is yes). When spam="yes" it remians the possible spam tags; when spam="no" it filters out the possible spam tags.
limit	optional	Limit the amount of tags returned (maximum/default is 40)
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <taggettags mode="top" limit="40">
    <tag name="research" strength="25.5125"/>
    <tag name="business" strength="9.63206"/>

    ...
  </taggettags>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Tag.getUrls

Returns a list of urls annotated by this tag

Params

tag	required	Get urls of this tag
with_title	optional	Whether includes url titles or not(yes/no, defalut is "no")
limit	optional	Limit the number of urls for each tag returned (maximum/default is 20)
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <taggeturls tag="google" with_title="no" limit="40">
    <url name="www.google.com" />
    <url name="scholar.google.com" />

    ...
  </taggeturls>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
10	UNKNOWN_TAG	Unknown tag in question

Tag.isSpam

Returns the results of whether a list of tags are spam or not.

Params

tag	required	A list of tags to be decided whether they are spam or not
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <isspam tag="indiana" is_spam="false" name="indiana" />
  <isspam tag="online" is_spam="true" name="online" />
  <isspam tag="web" is_spam="true" name="web" />
  ...
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Tag.search

Returns related information when searching by tags.

Params

tag	required	One or multiple tags as search keywords
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<bipartite>
  <urls>
    <information count="50">
    <url tags="imported learn group university meeting indiana ceramics iu fil" 
	  url="http://homer.informatics.indiana.edu/~nan/" 
	  title="Homer~nan/" />
    <url tags="systems research agents university ai meeting complex informatics ceramics iu alife" 
	  url="http://cx.informatics.indiana.edu/" 
	  title=" Center for Complex Networks and Systems Research" />
    ...
  </urls>
  <tags>
    <information count="15"/>
    <tag centrality="470.725" name="indiana"/>
    <tag centrality="10597.9" name="imported"/>
	...
  </tags>  
  <pairs>
    <information count="6"/>
    <pair tag="indiana" url="http://homer.informatics.indiana.edu/~nan/"/>
    <pair tag="indiana" url="http://homer.informatics.indiana.edu/~nan/"/>
	...
  </pairs>
</bipartite>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Tag.similarity

Returns similarities of each pair of tags in a list of tags.

Params

tag	required	Tags are space-sperated
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <tagsims>
    <edge source="web" target="webdesign" sim=28.1577 />
    <edge source="web" target="model" sim=1.92 />

    ...
  </tagsims>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Tag.subtag

For each annotation containing a given tag create a copy replacing the tag field with a new tag

Params

tag	required	Tag in question
sub_tag	required	New tag
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
6	INVALID_TAG	Invalid tag specified: it is either empty or only contains disallowed characters
7	UNAUTHORIZED	Invalid OAuth Request
10	UNKNOWN_TAG	Unknown tag in question
8	UNKNOWN_USER	Unknown user in question
13	INTERNAL_ERROR	Internal server error

Tag.update

Update the annotations containing a given tag with a new tag

Params

old_tag	required	Tag to update
new_tag	required	New tag
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
6	INVALID_TAG	Invalid tag specified: it is either empty or only contains disallowed characters
7	UNAUTHORIZED	Invalid OAuth Request
10	UNKNOWN_TAG	Unknown tag in question
8	UNKNOWN_USER	Unknown user in question
13	INTERNAL_ERROR	Internal server error

Url.generate

Return a url randomly selected.

Params

limit	optional	The number of returned random urls, default value is 1.
with_title	optional	Whether return title of urls ("yes"/"no"), default value is "no".
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <urlgenerate limit="2" with_title="yes" >
    <url name="www.iub.edu" titl="Indiana University Bloomington" />
    <url name="http://www.laurodesigner.it/" titl="Lauro design" />
  </urlgenerate >
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Url.getInfo

Get the title and the description associated to a url

Params

url	required	Url in question
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
  <urlgetinfo url="http://www.wordreference.com">
    <info title="Wordreference.com"
          desc="English to French, Italian & Spanish Dictionary - WordReference.com" >
  </urlgetinfo>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
9	UNKNOWN_URL	Unknown url in question

Url.getSimilar

Get the urls similar to this url

Params

pag

url	required	Url in question
limit	optional	Limit the amount of urls returned
optional	The page you want to fetch to (the result set is divided in pages of 40 elements)
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <urlgetsimilar pag="1" nPages="12" >
    <url name="http://www.wordreference.com/"/>
      <similar name="http://dictionary.cambridge.org/" value="1"/>
      <similar name="http://www.thefreedictionary.com/" value="1"/>
      <similar name="http://www.cnn.com/" value="0.0767"/>

    ...
  </urlgetsimilar>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Url.getTags

Returns a list of tags used for this url.

Params

url	required	Get tagss of this url
limit	optional	Limit the amount of tags returned (maximum/default is 40)
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <urlgettags url="http://www.iub.edu/" limit="40">
    <tag name="iu" />
    <tag name="indiana_university" />

    ...
  </urltags>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Url.getTitle

Returns a title of the given url randomly.

Params

url	required	Get title of this url
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <gettitle url="http://www.google.com/" />
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Url.isSpam

Returns the results of whether a list of urls are spam or not.

Params

url	required	A list of urls to be decided whether they are spam or not
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <isspam url="http://www.google.com/" is_spam="false" name="http://www.google.com/" />
  <isspam url="http://www.iub.edu/" is_spam="false" name="http://www.iub.edu/" />
  ...
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Url.search

Returns related information when searching by urls.

Params

url	required	One or multiple urls as search keywords
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<bipartite>
  <urls>
    <information count="50">
    <url tags="online web internet search engine news imported tools information 
	bookmarks google reference resources financial planning links math investing computers 
	bar bookmark menu engines district explorer folder educator search developments" 
	  url="http://www.google.com/" 
	  title="Google" />
    <url tags="search bookmarks_toolbar_folder" 
	  url="http://www.iub.edu/compute/" 
	  title="Indiana University Bloomington Computer Services" />
	...
  </urls>
  <tags>
    <information count="6"/>
    <tag centrality="32259.7" name="web"/>
    <tag centrality="23543.1" name="internet"/>
	...
  </tags>  
  <pairs>
    <information count="20"/>
    <pair tag="google" url="http://www.google.com//>
    <pair tag="web" url="http://www.google.com//>
	...
  </pairs>
</bipartite>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package

Url.setDescription

Associate a description to a given url

Params

desc	required	Description in question
url	required	Url in question
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
9	UNKNOWN_URL	Unknown url in question

Url.setInfo

Associate a title and a description to a given url

Params

title	required	Title in question
desc	required	Description in question
url	required	Url in question
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
9	UNKNOWN_URL	Unknown url in question

Url.setTitle

Associate a title to a given url

Params

title	required	Title in question
url	required	Url in question
user	required	User in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
9	UNKNOWN_URL	Unknown url in question

Url.similarity

Returns similarities of each pair of urls in a list of urls.

Params

url	required	Urls are space-sperated
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <urlsims url="http://www.iub.edu/" >
    <edge source="http://www.iub.edu/" target="http://www.idsnews.com/" sim=1.877 />
    <edge source="http://www.google.com/" target="http://www.yahoo.com/" sim=4.918 />

    ...
  </urlsims>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Url.targetSimilarity

Returns similarities of a list of urls and a target url.

Params

target	required	Target url with which similarity will be calculated
url	required	Urls are space-sperated
api_key	required	A Givealink API key

Authentication

This service does not require authentication.

Sample Response

<givealink status="ok">
  <urltargetsims >
    <edge source="http://www.idsnews.com/" target="http://www.iub.edu/" sim=2.877 />
    <edge source="http://www.yahoo.com/" target="http://www.iub.edu/" sim=1.918 />

    ...
  </urltargetsims>
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
9	UNKNOWN_URL	Unknown url in question

Annotation.add

Add a new annotation

Params

user	required	User in question
url	required	Url in question
tag	required	Tag in question
title	optional	Title of the annotation
desc	optional	Description of the annotation
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
5	INVALID_URL	Invalid url
6	INVALID_TAG	Invalid tag specified: it is either empty or only contains disallowed characters
7	UNAUTHORIZED	Invalid OAuth Request
8	UNKNOWN_USER	Unknown user in question
9	UNKNOWN_URL	Unknown url in question
10	UNKNOWN_TAG	Unknown tag in question

Annotation.delete

Delete an annotation

Params

user	required	User in question
url	required	Url in question
tag	required	Tag in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
7	UNAUTHORIZED	Invalid OAuth Request
8	UNKNOWN_USER	Unknown user in question
9	UNKNOWN_URL	Unknown url in question
10	UNKNOWN_TAG	Unknown tag in question
11	UNKNOWN_ANNOTATION	11

Post.add

Add a post (i.e., a user, a url and a set of associated tags). This method overrides previous annotations associated to the url in question

Params

user	required	User in question
url	required	Url in question
tag	required	A space separated list of tags
title	optional	Title of the annotation
desc	optional	Description of the annotation
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
5	INVALID_URL	Invalid url
6	INVALID_TAG	Invalid tag specified: it is either empty or only contains disallowed characters
7	UNAUTHORIZED	Invalid OAuth Request
8	UNKNOWN_USER	Unknown user in question
9	UNKNOWN_URL	Unknown url in question
10	UNKNOWN_TAG	Unknown tag in question

Post.delete

Delete a post (i.e., a url and all associated annotations)

Params

user	required	User in question
url	required	Url in question
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
5	INVALID_URL	Invalid url
7	UNAUTHORIZED	Invalid OAuth Request
8	UNKNOWN_USER	Unknown user in question
9	UNKNOWN_URL	Unknown url in question

Post.merge

Add a post (i.e., a user, a url and a set of associated tags). This method does not overrides previous annotations associated to the url in question

Params

user	required	User in question
url	required	Url in question
tag	required	A space separated list of tags
title	optional	Title of the annotation
desc	optional	Description of the annotation
api_key	required	A Givealink API key

Authentication

This service requires authentication. Please see our Authentication How-To for details.

Sample Response

<givealink status="ok">
</givealink>

Errors

1	INVALID_PARAMETERS	Your request is missing a required parameter
2	INVALID_API_KEY	You must be granted a valid key by Givealink
3	INVALID_METHOD	No method with that name in this package
5	INVALID_URL	Invalid url
6	INVALID_TAG	Invalid tag specified: it is either empty or only contains disallowed characters
7	UNAUTHORIZED	Invalid OAuth Request
8	UNKNOWN_USER	Unknown user in question
9	UNKNOWN_URL	Unknown url in question
10	UNKNOWN_TAG	Unknown tag in question