22 January 2019

WHX.IO API

WHX.IO Public API (v1)


About

We currently only provide 3 different actions that can be made and those are for getting url data, visitor data and creating new links, we will have more actions coming soon for updating, deleting and so on (this will require authentication). Every content type is set to json.

Request Status
  • server_info
    • server_status
      • success
      • error
        • server_message
      • warning
        • server_message

Request status can be determined by "server_info" -> "server_status" which can be the following: "success" for successful request, "error" for failed request, "warning" for other warnings. if you get an error then you usually also receive a message with it for troubleshooting. Here is an example of error: input: http://whx.io/api/v1/create/:url and output:

    
{
    "server_info": [
        {
            "server_status": "error",
            "server_message": "Link has to be without http: part! e.g mysite.com or www.mysite.com",
            "query_datetime": "2019-01-21 17:58:02"
        }
    ]
}
    

All of the API requests can currently be called without a API key and there are no limits!

Calling: whx.io/api/v1/{api-call}/{parameters}


URL Creation

GET
    
        /api/v1/create/:url
    
Parameter Value Description Data Type
:url required Target url that would be shortened. string
pswd not required Password for the shorturl string
On 27 January 2019 we removed "whx_status" and can now be found under "server_info" -> "server_status".

{
    "server_info": [
        {
            "server_status": "success",
            "query_datetime": "2019-02-12 04:46:46"
        }
    ],
    "website_data": [
        {
            "whx_id": "whx_9e2b50ea5ef",
            "whx_full_link": "http:\/\/whx.io\/a5ef",
            "whx_track_code": "a5ef",
            "whx_page_title": "WHX.IO - Link Shortener w\/ Analytics! - No Registration!\n",
            "whx_page_description": "Create tracking links and manage them toally free of charge! Analytics with Charts & Unique Users! Detect social, organic and direct traffic, get your visitors: IP Address, Country, City, Region, Zip Code, Latitude & Longitude, Referral Pages, Useragent, ",
            "whx_root": "http:\/\/whx.io",
            "whx_submitted": "whx.io"
        }
    ]
}

' imports
Imports System.Text
Imports System
Imports System.IO
Imports System.Net
Imports System.Web
Imports System.Runtime.InteropServices
Imports Newtonsoft.Json.Linq
Imports Json.Net
Imports Newtonsoft.Json

Public Class Form2
    ' Request
    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        request = DirectCast(WebRequest.Create("http://whx.io/api/v1/create/whx.io"), HttpWebRequest)

        response = DirectCast(request.GetResponse(), HttpWebResponse)
        reader = New StreamReader(response.GetResponseStream())

        Dim rawresp As String
        rawresp = reader.ReadToEnd()
        Dim array As JObject = JObject.Parse(rawresp)
        Dim FinalURL As String

         If array.SelectToken("server_info[0].server_status").ToString() = "success" Then
            FinalURL = array.SelectToken("website_data[0].whx_full_link").ToString()
         End If
     End Sub
 End Class

    
<?php

    $url = 'www.whx.io'; /* the url that would be shortened */
    $obj = file_get_contents('http://whx.io/api/v1/create/'.$url);
    $obj_decode = json_decode($obj, true);

    /* for printing the whole output */
    // var_dump($obj_decode);

    /* check if it was successfully shortened */
    if($obj_decode['server_info'][0]['server_status'] == 'success') 
    {
        /* for printing a single result (in this case the full shorturl) */
        echo $obj_decode['website_data'][0]['whx_full_link'];
    } else {
        /* 
            print error message 
            you may try to prompt this message by replacing www. with http:// in $url.
        */
        echo 'Error: '.$obj_decode['server_info'][0]['server_message'];
    }

?>

URL Data

GET
    
        /api/v1/url/:id
    
Parameter Value Description Data Type
:id required Target url that would be shortened. string

{
    "server_info": [
        {
            "server_status": "success",
            "query_datetime": "2019-01-29 12:30:16"
        }
    ],
    "link_data": [
        {
            "link_url": "http:\/\/whx.io\/whx",
            "link_tracking_id": "whx",
            "link_base_url": "http:\/\/whx.io",
            "link_mylink_id": "whx_a9d1bd5whx",
            "link_total_unique_clicks": "2",
            "link_total_clicks": "3",
            "link_last_active": "2019-01-20 06:55:27",
            "link_first_active": "2018-12-10 12:27:03",
            "link_created": "2018-12-16 04:22:44"
        }
    ]
}
<?php

    $id = 'whx-api';
    $obj = file_get_contents('http://whx.io/api/v1/url/'.$id);
    $obj_decode = json_decode($obj, true);

    /* for printing the whole output */
    // var_dump($obj_decode);

    /* check if the status is success */
    if($obj_decode['server_info'][0]['server_status'] == 'success') 
    {
        /* for printing a single result (for retreiving mylink_id for /visitors/ api request) */
        echo $obj_decode['link_data'][0]['link_mylink_id'];
    } else {
        /* 
            print error message 
            you may try to prompt this message by replacing the id with an invalid one.
        */
        echo 'Error: '.$obj_decode['server_info'][0]['server_message'];
    }

?>

URL Visitor Data

GET
    
        /api/v1/visitors/:mylink_id
    

look at /api/v1/url/ on how to fetch the :mylink_id

Parameter Value Description Data Type
:mylink_id required The url that visitors you would be fetching. string
datatype not required print type (legacy or empty) string
amount not required For controlling the amount of results. int

{
    "server_info": [
        {
            "server_status": "success",
            "query_datetime": "2019-02-12 04:51:22"
        }
    ],
    "visitor_data": [
        {
            "tracking_id": "9u7i",
            "tracking_ipaddr": "118.1***",
            "tracking_country": "AU",
            "tracking_country_code": "AU",
            "tracking_region": "Victoria",
            "tracking_region_code": "VIC",
            "tracking_city": "Southbank",
            "tracking_zip": "3006",
            "tracking_lat": "-3***",
            "tracking_log": "14***",
            "tracking_isp": "SPIRIT-TELECOM",
            "tracking_as": "AS38790 Spirit Telecom (Australia) Pty Ltd",
            "tracking_organization": "",
            "tracking_mobile": "",
            "tracking_proxy": "",
            "tracking_reverse": "118-127-96-93.static.spirit.net.au.99.12*****.in-addr.arpa",
            "tracking_timezone": "Australia\/Melbourne",
            "tracking_referral": "",
            "tracking_useragent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.79 Safari\/537.36 Edge\/14.14393",
            "tracking_time": "2019-02-05 15:51:01"
        },
        {
            "tracking_id": "9u7i",
            "tracking_ipaddr": "191.2***",
            "tracking_country": "BR",
            "tracking_country_code": "BR",
            "tracking_region": "Ceara",
            "tracking_region_code": "CE",
            "tracking_city": "Fortaleza",
            "tracking_zip": "60000",
            "tracking_lat": "-3***",
            "tracking_log": "-3***",
            "tracking_isp": "Tecnet Provedor De Acesso AS Redes De Com. Ltda",
            "tracking_as": "AS263665 TECNET PROVEDOR DE ACESSO AS REDES DE COM. LTDA",
            "tracking_organization": "Ipade - Instituto Para O Desenvolvimento DA Educac",
            "tracking_mobile": "",
            "tracking_proxy": "",
            "tracking_reverse": "dynamic-cliente.tecnetce.com.br",
            "tracking_timezone": "America\/Fortaleza",
            "tracking_referral": "",
            "tracking_useragent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.79 Safari\/537.36 Edge\/14.14393",
            "tracking_time": "2019-02-05 16:06:31"
        }
    ]
}
<?php

    $mylink_id = 'whx_a895812whx-api'; /* look at /api/v1/url/ on how to fetch this! */
    $obj = file_get_contents('http://whx.io/api/v1/visitors/'.$mylink_id);
    /* 
        Example with "amount" parameter:
        $obj = file_get_contents('http://whx.io/api/v1/visitors/'.$mylink_id.'&amount=1'); 
    */
    $obj_decode = json_decode($obj, true);

    /* for printing the whole output */
    // var_dump($obj_decode);

    /* check if the status is success */
    if($obj_decode['server_info'][0]['server_status'] == 'success') 
    {
        /* for printing each visitor result */
        foreach($obj_decode['visitor_data'] as $visitors)
        {
            echo $visitors['tracking_ipaddr'].'<br>'; /* for printing each visitor ip address */
        }
    } else {
        /* 
            print error message 
            you may try to prompt this message by replacing the mylink_id with an invalid one.
        */
        echo 'Error: '.$obj_decode['server_info'][0]['server_message'];
    }

?>

Self Hosting WHX.IO

Wish to have the links as www.my-website-url.com/go/whx-shortened-id ? you could use this simple script (using /api/v1/url/:id to validate the shorturl) read more on self hosting here

<?php

    if(isset($_GET['id']))
    {

        $id = $_GET['id']; /* the url that would be shortened */
        $obj = file_get_contents('http://whx.io/api/v1/url/'.$id);
        $obj_decode = json_decode($obj, true);

        /* for printing the whole output */
        // var_dump($obj_decode);

        /* check if the shorturl exists */
        if($obj_decode['server_info'][0]['server_status'] == 'success') 
        {
            /* navigates through whx */
            header('Location: http://whx.io/'.$obj_decode['link_data'][0]['link_tracking_id']); 
        } else {
            /* 
                print error message 
                you may try to prompt this message by replacing the id with an invalid one.
            */
            echo 'Error: '.$obj_decode['server_info'][0]['server_message'];
        }

    } else {
        echo 'Error: id parameter not set!';
    }

?>