V.ht Application Programming Interface (API) Reference

API Adrress


API Syntax is as follows:

  1. https://v.ht/api.php?url=[URL]&suffix=[SUFFIX]&userkey=[USERKEY]&format=[FORMAT]&callback=[CALLBACK]

Parameters


ParameterNeed?Description
[URL]Mandatory *Used to indicate the URL address that is to be shortened: click here for Notes
[SUFFIX]OptionalUsed to provide user defined suffixes to the resulting URL
[USERKEY]OptionalUsed to provide your own API PassKey
[FORMAT]OptionalUsed to determine the format in which the API should respond, possible ways are:

plain , json , jsonp , xml

[CALLBACK]OptionalUsed to specify a callback function to wrap the returned data in when using jsonp

Error Messages


The list of Error codes and their respective Error Messages:

Error CodeError Message
1Incorrect URL format or URL is not provided.
2SUFFIX already in use or contains Invalid Character, Valid Characters are:A-Z,a-z,0-9,-,_
3Sorry! The entered URL is black listed.
4The service is not available, or an error occurred during the execution of the request.
5URL shortening rate limit exceeded (Application needs to wait before trying again)

API Responses


Once a successful request is sent, the API will respond with a message explaining either the URL has been shortened or not:

KeywordDescription
shorturlThe generated new short URL.
errorcodeContains the error code when an error occurs.
errormessageContains the error message when an error occurs.

Examples of API Responses


PLAIN

- On a successful URL creation request, the result will be a single line of text in the response body, i.e the new shortened URL.

- The HTTP status code on success will be: 200 (HTTP/1.1 200 OK) in the Server Response Header

- The Response body begins with :- https:// when successful, or in case of failure it begins with :- Error:

- If there is error in the request, the server will send the error code in the Response Header illustrating the error type, and the page body will contain the error message.

- Response Headers in case of Errors are as follows :

[1]: HTTP/1.1 400 Bad Request

[2]: HTTP/1.1 406 Not Acceptable

[3]: HTTP/1.1 403 Forbidden

[4]: HTTP/1.1 503 Service Temporarily Unavailable

[5]: HTTP/1.1 502 Bad Gateway

An example of a response to a request without errors:

  1. https://v.ht/Kp

An example of a response to a request with errors:

  1. Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -

JSON

An example of a response to a request without errors:

  1. {"shorturl":"https://v.ht/Kp"}

An example of a response to a request with errors:

  1. {"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"}

Note :

In JSON, the HTTP status code of the response will always be 200 even in the case of any error. But the Response body will indicate the error caused in brief.


JSONP

In case a CallBack is used, which is default with a request, the syntax for calling a user defined function is : callback=myfunc

An example of a response to a request without errors:

  1. ( {"shorturl":"https://v.ht/Kp"} );

An example of a response to a request without errors when callback=myfunc is used:

  1. myfunc ( {"shorturl":"https://v.ht/Kp"} );

An example of a response to a request with errors:

  1. ( {"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"} );

An example of a response to a request with errors when callback=myfunc is used:

  1. myfunc ( {"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"} );

XML

The response is included within the <output> tag

An example of a response to a request without errors:

  1. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  2. <output>
  3.     <shorturl>https://v.ht/Kp</shorturl>
  4. </output>

An example of a response to a request with errors:

  1. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  2. <output>
  3.     <errorcode>1</errorcode>
  4.     <errormessage>Error: You haven't supplied a URL..!!</errormessage>
  5. </output>

Note :

In XML, the HTTP status code of the response will always be 200 even in the case of any error. But the Response body will indicate the error caused in brief.

Important Points:


* You must ensure the URL is encoded properly, before issuing your request to the API. You can use any of the following functions according to the language of your application:

- PHP: urlencode

- JavaScript: encodeURIComponent

- Python:urlib.quote

- Dot. Net: Url.UrlEncode

- Delphi: TIdURI.URLEncode

* You can use any of the Request methods available: POST, GET or COOKIE with the API, using the same parameters, which are explained in Parameters section above.

* It is advisable to always use the method: POST to send requests because of the limitations on the GET method.

* The maximum available URLs that can be shortened is 100, during the time frame of 180 seconds. In case your application exceeded this limit, then your application needs to wait for this time frame to elapse counted from the first shortened URL in this 100 URLs batch, before beginning to shorten any more URLs.