Premium URL Shortener API Guide

Documentation on how to use Premium URL Shortener's API system to develop your apps. The new API of Premium URL Shortener 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/api page. The API key must be sent with each request via as an authorization token.

cURL PHP NodeJs 
curl --location --request POST 'https://yourwebsite.com/api/url/add' \ 
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \ 
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/url/add",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    )
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/url/add',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  }

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Server Setup

Some servers do not accept HTTP Authorization by default. You will need to make a slight change in the .htaccess file to allow this feature. Open the file and after RewriteEngine On, add the following code

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

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://yourwebsite.com/DkZOb"
)  

 $responseDecoded = json_decode($response, true);
// Output data
var_dump($responseDecoded);  
                
 array (
  'error' => 0,
  'short' => 'https://yourwebsite.com/DkZOb',
)

Shorten a Link

To send a request, the user must use the following format where the variable url is required. In the example below, the URL of the demo is used but you should use your own domain name. See table below for parameters.

Parameter Description
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
domain (optional) Custom Domain
expiry (optional) Expiration for the link example 2024-12-21 13:26:31
geotarget (optional) Geotargetting data
devicetarget (optional) Device Targetting data
cURL PHP NodeJs 
 POST https://yourwebsite.com/api/url/add
curl --location --request POST 'https://yourwebsite.com/api/url/add' \
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "url": "https://google.com",
      "custom": "google",
      "password": "mypass",
      "domain": "http://goo.gl",
      "expiry": "2020-11-11 12:00:00",
      "type": "splash",
      "geotarget": [{
          "location": "Canada",
          "link": "https://google.ca"
        },
        {
          "location": "United States",
          "link": "https://google.us"
        }
      ],
      "devicetarget": [{
          "device": "iPhone",
          "link": "https://google.com"
        },
        {
          "device": "Android",
          "link": "https://google.com"
        }
      ]
    }'
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/url/add",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    ),
    CURLOPT_POSTFIELDS => '{
      "url": "https://google.com",
      "custom": "google",
      "password": "mypass",
      "domain": "http://goo.gl",
      "expiry": "2020-11-11 12:00:00",
      "type": "splash",
      "geotarget": [{
          "location": "Canada",
          "link": "https://google.ca"
        },
        {
          "location": "United States",
          "link": "https://google.us"
        }
      ],
      "devicetarget": [{
          "device": "iPhone",
          "link": "https://google.com"
        },
        {
          "device": "Android",
          "link": "https://google.com"
        }
      ]
    }',
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/url/add',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://google.com",
    "custom": "google",
    "password": "mypass",
    "domain": "http://goo.gl",
    "expiry": "2020-11-11 12:00:00",
    "type": "splash",
    "geotarget": [{
        "location": "Canada",
        "link": "https://google.ca"
      },
      {
        "location": "United States",
        "link": "https://google.us"
      }
    ],
    "devicetarget": [{
        "device": "iPhone",
        "link": "https://google.com"
      },
      {
        "device": "Android",
        "link": "https://google.com"
      }
    ]
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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:\/\/yourwebsite.com\/DkZOb"
}                
 // An error has occurred
{
  "error" : 1,
  "msg" : "Please enter a valid URL"
}

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
urlid (required) Short URL ID
cURL PHP NodeJs 
 POST https://yourwebsite.com/api/url/stats
curl --location --request POST 'https://yourwebsite.com/api/url/stats' \
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "urlid": 2
  }'
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/url/stats",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    ),
    CURLOPT_POSTFIELDS => '{
      "urlid": 2
    }',
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/url/stats',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "urlid": 2
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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:\/\/yourwebsite.com\/DkZOb",
      "longurl": "https:\/\/gempixel.com",
      "title": "GemPixel | Creative Digital Agency",
      "description": "We are a creative digital agency providing full-featured services including branding, creation of website and app development. We are also behind Premium URL shortener.",
      "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:\/\/gempixel.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 url/get 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
limit (optional) Per page data result
page (optional) Current page request
order (optional) Sort data between date or click
cURL PHP NodeJs 
 POST https://yourwebsite.com/api/url/get
curl --location --request POST 'https://yourwebsite.com/api/url/get' \
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "limit": 12,
      "page" : 2,
      "order": "date"
  }'
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/url/get",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    ),
    CURLOPT_POSTFIELDS => '{
        "limit": 2,
        "page" : 1,
        "order": "date"
    }',
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/url/get',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "limit": 12,
    "page" : 2,
    "order": "date"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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": {
    "result": 2,
    "perpage": 2,
    "currentpage": 1,
    "nextpage": 1,
    "maxpage": 1,
    "urls": [{
      "id": 2,
      "alias": "google",
      "shorturl": "https://yourwebsite.com/google",
      "longurl": "https:\/\/google.com",
      "clicks": 0,
      "title": "Google",
      "description": "",
      "date": "2020-11-10 18:01:43"
    }, {
      "id": 1,
      "alias": "googlecanada",
      "shorturl": "https://yourwebsite.com/googlecanada",
      "longurl": "https:\/\/google.ca",
      "clicks": 0,
      "title": "Google Canada",
      "description": "",
      "date": "2020-11-10 18:00:25"
    }]
  }
}

Create a User

Admins can use the API system to create users.

Parameter Description
username (required) User's username. Needs to be valid.
email (required) User's email. Needs to be valid.
password (required) User's password. Minimum 5 characters.
planid (optional) Premium plan. This can be found in the admin panel.
expiration (optional) Membership expiration example 2020-12-26 12:00:00
cURL PHP NodeJs 
 POST https://yourwebsite.com/api/user/create
curl --location --request POST 'https://yourwebsite.com/api/user/create' \
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
        "username":"user",
        "password":"1234567891011",
        "email" : "[email protected]",
        "planid": 1,
        "expiration": "2020-11-20 11:00:00"
    }'
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/user/create",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    ),
    CURLOPT_POSTFIELDS => '{
        "username":"user",
        "password":"1234567891011",
        "email" : "[email protected]",
        "planid": 1,
        "expiration": "2020-11-20 11:00:00"
    }',
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/user/create',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "username":"user",
      "password":"1234567891011",
      "email" : "[email protected]",
      "planid": 1,
      "expiration": "2020-11-20 11:00:00"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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 user's data.

{
  "error": 0,
  "msg": "User has been registered",
  "data": {
    "id": 2,
    "email": "[email protected]",
    "username": "user"
  }
}

Get a User

Admins can use the API system to get user's information.

Parameter Description
userid (required) User's id
cURL PHP NodeJs 
 POST https://yourwebsite.com/api/user/get
curl --location --request POST 'https://yourwebsite.com/api/user/get' \
  --header 'Authorization: Token YOURAPIKEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
        "userid": 2
    }'
$curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://yourwebsite.com/api/user/get",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 2,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => array(
      "Authorization: Token YOURAPIKEY",
      "Content-Type: application/json",
    ),
    CURLOPT_POSTFIELDS => '{
          "userid": 2
      }',
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://yourwebsite.com/api/user/get',
  'headers': {
    'Authorization': 'Token YOURAPIKEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "userid": 2
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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 the user's data.

{
  "error": 0,
  "data": {
    "email": "[email protected]",
    "username": "user",
    "date": "2020-11-10 11:00:00",
    "avatar": "http://path/to/avatar",
    "pro": "1",
    "planid": "1",
    "expiration": "2020-12-10 11:00:00",
    "last_payment": "2020-11-10 11:00:00"
  }
}