Developer API

ItsSSL API Guide

Documentation on how to use itsSSL's API system to develop your apps. Our new API is built on the RESTful architecture and it allows you to easily interact with your website using the following endpoints. There were some changes to the API in order facilitate requests from developers.

 

Authentication

As before, an API key is required for requests to be processed by the system. Once a user registers, an API key is automatically generated for this user and it can be found in the /user/tools page. The API key must be sent with each request via the key parameter.

 GET https://itsSSL.com/api?key=YOURAPIKEY

Response Handling

All API response are returned in JSON format by default. To convert this into usable data, the appropriate function will need to be used according to the language. In PHP, the function json_decode() can be used to convert the data to either an object (default) or an array (set the second parameter to true). It is very important to check the error key as that provides information on whether there was an error or not.

 $responseDecoded = json_decode($response);
// Output data
var_dump($responseDecoded);  
                
stdClass Object
(
    [error] => 0
    [short] => "https://itsSSL.com/DkZOb"
)  
 $responseDecoded = json_decode($response, true);
// Output data
var_dump($responseDecoded);  
                
 array (
  'error' => 0,
  'short' => 'https://itsSSL.com/DkZOb',
)  
                

Shorten a Link

To send a request, the user must use the following format where the variables key and url are required. In the example below, the URL of the demo is used but you should use your own domain name. To request a custom alias, simply add &custom= at the end.

Parameter Description
key (required) Your API key.
url (required) Long URL to shorten.
custom (optional) Custom alias instead of random alias.
type (optional) Redirection type [direct, frame, splash]
password (optional) Password protection
format (optional) Output format. Default is json. [json, text]
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://itsSSL.com/api?key=YOURAPIKEY&url=https://TheLongURL.com"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

Server response

As before, the response will encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element.

If there is an error, the second element will be named “msg”. which contains the source of error, otherwise it will be named “short” which contains the short URL. (See the example)

 // No errors
{
  "error" : 0,
  "short" : "https:\/\/itsSSL.com\/DkZOb"
}                
 // An error has occurred
{
  "error" : 1,
  "msg" : "Please enter a valid URL"
}                

Text Format

You can now request the response to be in plain text by just adding &format=text at the end of your request. This will return just https://itsssl.com/short/DkZOb instead of the JSON response. Note that if an error occurs, it will not output anything.

 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://itsSSL.com/api?key=YOURAPIKEY&url=https://TheLongURL.com&format=text"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                
 https://itsSSL.com/DkZOb                

Statistics for a short URL

You can get more detail on a short URL by using the /details endpoint along with the following parameters. You need to send the unique alias of a short URL and the response will be in JSON.

Parameter Description
key (required) Your API key.
alias (required) Short URL alias.
 GET https://itsSSL.com/api/details
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://itsSSL.com/api/details?key=YOURAPIKEY&alias=UNIQUEALIAS"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

Server response

As before, the response will encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element.

If there is an error, the second element will be named "msg". which contains the source of error, otherwise it will be named "details" which contains details of the short URL and "data" which includes statistics.

 {
   "error": 0,
   "details":{
      "shorturl": "https:\/\/itsSSL.com\/DkZOb",
      "longurl": "https:\/\/LONGURL.com",
      "title": "TITLE OF THE WEBSITE",
      "description": "The website description.",
      "location": null,
      "device": null,
      "expiry": null,
      "date": "2019-01-27 22:49:36"
   },
   "data":{
      "clicks": 4,
      "uniqueClicks": 2,
      "topCountries": {
         "Canada": 4
      },
      "topReferrers": {
         "Direct, email and other": 2,
         "https:\/\/LONGURL.com": 2
      },
      "topBrowsers":{
         "Chrome": 4
      },
      "topOs":{
         "Windows 10": 4
      },
      "socialCount":{
         "facebook": 0,
         "twitter": 0,
         "google": 0
      }
   }
}                

Account Links List

You can get all of your links list on your account by using the urls endpoint. You don't need to send any other parameters besides the API key. The response will be in JSON and it will include all of your links in your account.

Parameter Description
key (required) Your API key.
 GET https://itsSSL.com/api/urls
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://itsSSL.com/api/urls?key=YOURAPIKEY"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

Server response

As before, the response will encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element.

If there is an error, the second element will be named "msg". which contains the source of error, otherwise it will be named "data" which contains this list of URLs.

 {
   "error": 0,
   "data": [
      {
         "alias": "site123",
         "shorturl": "https:\/\/itsSSL.com\/site123",
         "longurl": "https:\/\/LONGURL.ca",
         "clicks": "4",
         "title": "TITLE OF THE WEBSITE",
         "description": "THIS IS THE DESCRIPTION OF THE WEBSITE.",
         "date": "2019-01-27 22:49:36"
      },
      {
         "alias": "DkZOb",
         "shorturl": "https:\/\/itsSSL.com\/DkZOb",
         "longurl": "https:\/\/LONGURL.com",
         "clicks": "2",
         "title": "WEBSITE TITLE",
         "description": "The Description of the website.",
         "date": "2019-01-27 22:48:36"
      }
   ]
}                

 

 

 

LEGACY Developer API

Registering for an API Key

As before, an API key is required for requests to be processed by the system. Once a user registers, an API key is automatically generated for this user. The API key must attached to request via the api parameter (see full example below).

Sending a request for shortening a URL

To send a request, the user must use the following format where the variables api and url are required. In the example below, the URL of the demo is used but you should use your own domain name. To request a custom alias, simply add &custom= at the end.

  GET http://itsssl.com/short/api?api=APIKEY&url=THELONGURLTOBESHORTENED&custom=CUSTOMALIAS

Server response

As before, the response will encoded in JSON format (default). This is done to facilitate cross-language usage. The first element of the response will always tell if an error has occurred (error: 1) or not (error: 0). The second element will change with respect to the first element. If there is an error, the second element will be named “msg”. which contains the source of error, otherwise it will be named “short” which contains the short URL. (See below for an example)

// No errors
{
  "error":0,
  "short":"http:\/\/itsssl.com\/short\/DkZOb"
}
// An error has occurred
{
  "error":1,
  "msg":"Please enter a valid email"
}

Using plain text format

You can now request the response to be in plain text by just adding &format=text at the end of your request. This will return justhttp://itsssl.com/short/DkZOb instead of the JSON response. Note that if an error occurs, it will not output anything.

Using the API in PHP

To use the API in your PHP application, you have to send a GET request through file_get_contents or cURL: Both are reliable methods. You can see a sample code below using file_get_contents.