Linkee® - URL Shortening, Real-Time Tracking & Social Sharing

API Documentation

Overview

The Linkee API provides a means to interact with the Linkee service programmatically. This document provides the instructions & examples for a developer to use to create web, desktop and mobile applications.

Versions

This document pertains to version 1.0 of API. Version 1.0 is the latest version.

Service URL

The API Service URL is split into two parts: the API version & the action to perform. Both parts are required and must be in this order:

http://api.linkee.com / version / action

EXAMPLE

  http://api.linkee.com/1.0/shorten

HTTP Methods

GET or POST for all API calls.

HTTP Response Codes

All responses will be 200 OK, unless an actual HTTP code of another kind is required. The errors and messages for the API have their own codes and meanings accessible via the response message, whether that be in JSON, XML, etc.

Required Parameters

input=

The input to act upon, url-escaped.

EXAMPLE

  http://api.linkee.com/1.0/shorten?input=http%3A%2F%2Fwww.example.com
  http://api.linkee.com/1.0/expand?input=5f0

Optional Parameters

api_key=

A unique code used to associate a shortened link with a user account, if sent. This is a user key, not a developer key. If the key cannot be associated with a known user account, the response will contain an error and the service will not complete the action requested. Users with an account can find the API Key on the My Account page under “API KEY”.

This parameter only applies to the /shorten method.

EXAMPLE

  http://api.linkee.com/1.0/shorten?input=http%3A%2F%2Fwww.example.com&api_key=c5735d19189ad736565f11619f34d864

format=

The response format.

json (default)
xml
text

EXAMPLES

Request:

  http://api.linkee.com/1.0/expand?input=5f0&format=json

Response:

  {"status": {"code": 200, "message": "OK"}, "result": "http://www.example.com"}

Request:

  http://api.linkee.com/1.0/expand?input=5f0&format=xml

Response:

  <?xml version="1.0" encoding="UTF-8"?>
  <linkee>
    <status>
      <code>200</code>
      <message>OK</message>
    </status>
    <result>http://www.example.com</result>
  </linkee>

Request:

  http://api.linkee.com/1.0/expand?input=5f0&format=text

Response:

  http://www.example.com

callback=

For use only with JSON response format, specify a callback function which sends the JSON response as the first parameter.

EXAMPLE

Request:

  http://api.linkee.com/1.0/expand?input=5f0&callback=myFunction

Response:

  myFunction({"status": {"code": 200, "message": "OK"}, "result": "http://www.example.com"})

sandbox=

Set to 1, will return test data for development purposes to prevent needless API calls.

  http://api.linkee.com/1.0/expand?input=5f0&sandbox=1

Methods

/shorten

Shortens the given input and returns the new short Linkee URL.

EXAMPLE

Request:

  http://api.linkee.com/1.0/shorten?input=http%3A%2F%2Fwww.example.com

Response:

  {"status": {"code": 200, "message": "OK"}, "result": "http://linkee.com/5f0"}

/expand

Retrieves the full URL from the input. Input can be in the form of just the unique code ("5f0") or the full Linkee URL ("http://linkee.com/5f0")

EXAMPLES

Request:

  http://api.linkee.com/1.0/expand?input=5f0

Response:

  {"status": {"code": 200, "message": "OK"}, "result": "http://www.example.com"}

Request:

  http://api.linkee.com/1.0/expand?input=http://linkee.com/5f0

Response:

  {"status": {"code": 200, "message": "OK"}, "result": "http://www.example.com"}

Responses

Overview

Text format simply returns either the result of the action or "ERROR".

JSON & XML formats return data in this structure:

status
- code
- message
result

status

Codes & Messages:

200 => OK
300 => API Key not valid.
400 => URL cannot be blank.
401 => URL cannot be to the Linkee website.
402 => URL cannot be to another link shortening service.
403 => URL must be 2000 characters or less.
500 => Hash not provided.
501 => Hash not found.

result

Contains result appropriate for the action, usually a URL, or nothing if there is an error.