API Documentation

ShortSwitch has a REST API which allows you to programmatically interact with your account. Make requests to the api.shortswitch.com domain.

Authentication

Each ShortSwitch user has an API key assigned to it. This key must be passed into all API methods. You can view and regenerate your API key from the Users page.

apiKey=apiKey

Common Parameters

All API methods support an optional format parameter. Supported formats are xml (default), json and simple

format=json

The simple format behavior differs depending on the action invoked. For shorten it causes the call to only return the shortened url. For expand only the original long url will be returned. All other methods behave as if the format were json

All API methods support JSONP by allowing the optional callback and variable parameters. You can use one or the other or both together.

callback=callback
variable=variable

Returned Parameters

All API methods return at least three parameters which detail the success or failure of the request. If the request succeeded a fourth parameter - results - is included which holds the actual results of the request.

If the request is made via the XML format, the XML returned is inside the root node shortSwitch.

If the request is made via the simple format and the method is either shorten or expand no parameters will be returned. Instead only the applicable data will be returned in text format.

  • errorCode
    The error code which caused the request to fail. 0 if the request succeeded.
  • errorMessage
    The error message detailing the request failure. Blank if the request succeeded.
  • statusCode
    OK or ERROR depending on whether the request succeeded or not.

You can get a full list of all possible error codes and their associated messages by calling the /errors method.

REST API

/shorten

Given a long URL, the /shorten method generates a shortened URL and returns it.

Required parameters

  • longUrl
    • The full URL you want to shorten. This must be URL encoded.

Optional parameters

  • token or hash
    • A custom token/hash for your shortened URL.
  • passThrough
    • (Default: false) Whether or not to allow URL parameters to be passed from the shortened URL to the long URL.

Returned values

  • longUrl
    The URL you shortened.
  • shortUrl
    The generated short URL.
  • hash
    The generated hash for the short URL.

    • If the format is simple only the generated short URL will be returned.

/expand

Given a shortened URL or the hash of a shortened URL, the /expand method returns the long URL it points to.

Required parameters

shortUrl or hash must be provided.

  • shortUrl
    A shortened URL.
  • hash
    The hash of a shortened URL.

Returned values

  • longUrl
    • The URL you shortened.
  • hash
    The hash for the URL.

    • If the format is simple only the URL you shortened will be returned.

/info

Given a shortened URL or the hash of a shortened URL, the /info method returns information about that page, such as the long source URL and other information.

Required parameters

Either shortUrl or hash must be provided.

  • shortUrl
    A shortened URL.
  • hash
    The hash of a shortened URL.

Optional parameters

  • keys
    • A list of values to return. Note: If you want more than one key, use the form: keys[]=value1&keys[]=value2...

Default Returned values

  • longUrl
    The URL you shortened.
  • shortUrl
    The generated short URL.
  • hash
    The hash for the shortened URL.
  • shortenedByUser
    The user that shortened the URL.

/stats

Given a shortened URL or the hash of a shortened URL, the /stats method returns traffic and referrer data.

Required parameters

Either shortUrl or hash must be provided.

  • shortUrl
    A shortened URL.
  • hash
    The hash of a shortened URL.

Returned values

  • clicks
    The number of visits the shortened URL has.
  • hash
    The hash for the shortened URL.

/list

Returns a list of the account's or user's shortened links

Optional parameters

  • account
    • If this is set to no only the links for user (as identified by the api key) will be returned.

Returned values

  • count
    The number of links returned.
  • links
    The links for the account or user.

/errors

The /errors method returns a list of all possible error codes and the associated messages.

Returned values

  • errors
    The list of errors.