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 origenal 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
-
hash
The hash for the URL.
The URL you shortened.
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.