API Protocol

The API is the same for safe.mn, clic.gs, go2.gs, cliks.fr and 888.hn.

The API will evolve as we make more features available to third-parties.

For a list of libraries (PHP, Perl, Python, Javascript, etc.), see Libraries.

Shorten a URL

Expand a URL

Track a short link

Shorten a URL

Request

To shorten a long URL, issue a GET request like this:

http://safe.mn/api/shorten?url=<url>&format=<format>&callback=<callback>

With the following values <...>:

ParameterRequiredMeaningPossible valueDefaultComment
urlrequiredLong URLhttp://www.reviews-web-hosting.com/none 
aliasoptionalshort aliasEXAMPLEnoneAlias must contain between 5 and 100 characters (letters, numbers, _ and -).
formatoptionalFormat of the responsexml (XML), json (Json), jsonp (JsonP) or text (plain text)text 
callbackoptionalcallback function for JsonPsafemn_resultmissing_callbackUsed with format=jsonp only

We recommend that you do not rely on the default values. You should explicitly specify the format, and the callback (for JsonP).

Response

XML:

Successful:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
 <url>http://safe.mn/c</url>
</data>

Error:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
 <error>Invalid URL</error>
</data>

Json:

Successful:

{ "url": "http://safe.mn/c" }

Error:

{ "error": "Invalid URL" }

JsonP (callback=safe123):

Successful:

safe123({ "url": "http://safe.mn/c" })

Error:

safe123({ "error": "Invalid URL" })

Plain text:

Successful:

http://safe.mn/c

Error:

Error: Invalid URL

Note: there might be additional white spaces (tab, space, line break) in the server reply.

Examples

Request:

http://safe.mn/api/shorten?url=http://www.aol.net/&format=jsonp&callback=safe123

Response:

safe123({ "url": "http://safe.mn/c" })

Request:

http://safe.mn/api/shorten?url=http://www.aol.net/&alias=AOL-NET&format=json

Response:

{ "url": "http://safe.mn/AOL-NET" }

Top

Expand a URL

Request

To get the long URL for a short URL, issue a GET request in this fashion:

http://safe.mn/api/expand?short_url=<url>&format=<format>&callback=<callback>

With the following values <...>:

ParameterRequiredMeaningPossible valueDefaultComment
short_urlrequiredShort URLhttp://safe.mn/1none 
formatoptionalFormat of the responsexml (XML), json (Json), jsonp (JsonP) or text (plain text)text 
callbackoptionalcallback function for JsonPsafemn_resultmissing_callbackUsed with format=jsonp only

We recommend that you do not rely on the default values. You should explicitly specify the format, and the callback (for JsonP).

Response

XML:

Successful:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
 <url>http://www.google.com/</url>
</data>

Error:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
 <error>Invalid URL</error>
</data>

Json:

Successful:

{ "url": "http://www.google.com/" }

Error:

{ "error": "Invalid URL" }

JsonP (callback=safe123):

Successful:

safe123({ "url": "http://www.google.com/" })

Error:

safe123({ "error": "Invalid URL" })

Plain text:

Successful:

http://www.google.com/

Error:

Error: Invalid URL

Note: there might be additional white spaces (tab, space, line break) in the server reply.

Examples

Request:

http://safe.mn/api/expand?short_url=http://safe.mn/c&format=xml

Response:

<?xml version='1.0' ?>
<data>
 <url>http://www.aol.net/</url>
</data>

Top

Track a short link

Request

To shorten a long URL, issue a GET request like this:

http://safe.mn/api/info?url=<url>&format=<format>&callback=<callback>

With the following values <...>:

ParameterRequiredMeaningPossible valueDefaultComment
urlrequiredLong URLhttp://www.reviews-web-hosting.com/none 
formatoptionalFormat of the responsexml (XML), json (Json), jsonp (JsonP) or text (plain text)text 
callbackoptionalcallback function for JsonPsafemn_resultmissing_callbackUsed with format=jsonp only

We recommend that you do not rely on the default values. You should explicitly specify the format, and the callback (for JsonP).

Response

json

ParameterMeaningPossible valueComment
urlLong URLhttp://www.reviews-web-hosting.com/ 
clicksNumber of clicks for the short link1201Integer
referersNumber of clicks per original domain[["Direct Access/Applications","1,151"],["baidu.com","2"]]Array of pairs [Domain, Clicks]
countriesNumber of clicks per country[["United States","851"],["China","94"]]Array of pairs [Country, Clicks]
filetypePotentially dangerous file typeapplication/x-dosexecEmpty if safe
virusVirus nameEicar-Test-SignatureEmpty if no virus
dangerousKnown dangerous siteSpyware/Malware/AdwareEmpty if safe
partialPartial download10 if download is complete
unreachablePage is unreachable10 if page is reachable
activexDangerous ActiveX name00000000-0000-0000-0000-000000000000 CnBabe AdwareEmpty if safe
xssCross-Site Scripting10 if URL is safe
categoryContent categoryAdultEmpty if safe
redirectionToo many redirections10 if not too many redirections
errorAn error occurredInvalid URLNo error field if successful
qr_shortURL of the QR code for the short linkhttp://safe.m/static/images/qr/1-safe.gif 
qr_longURL of the QR code for the long linkhttp://safe.mn/static/images/qr/1.gif 

jsonp

Same as json.

xml

Root name: <data>

ParameterMeaningPossible valueComment
urlLong URL<url>http://www.reviews-web-hosting.com/</url> 
clicksNumber of clicks for the short link<clicks>1201</clicks>Integer
referersNumber of clicks per original domain<referers>
  <referer clicks="1151" domain="Direct Access/Applications" />
  <referer clicks="2" domain="baidu.com" />
</referers>
List of <referer clicks="Clicks" domain="Domain" />
countriesNumber of clicks per country<countries>
  <country name="United States" clicks="851" />
  <country name="China" clicks="94" />
<countries>
List of <country name="Country" clicks="Clicks" />
filetypePotentially dangerous file type<filetype>application/x-dosexec</filetype>Empty if safe
virusVirus name<virus>Eicar-Test-Signature</virus>Empty if no virus
dangerousKnown dangerous site<dangerous>Spyware/Malware/Adware</dangerous>Empty if safe
partialPartial download<partial>1</partial>0 if download is complete
unreachablePage is unreachable<unreachable>1</unreachable>0 if page is reachable
activexDangerous ActiveX name<activex>00000000-0000-0000-0000-000000000000 CnBabe Adware</activex>Empty if safe
xssCross-Site Scripting<xss>1</xss>0 if URL is safe
categoryContent category<category>Adult</category>Empty if safe
redirectionToo many redirections<redirection>1</redirection>0 if not too many redirections
errorAn error occurred<error>Invalid URL</error>No error field if successful
qr_shortURL of the QR code for the short link<qr_short>http://safe.m/static/images/qr/1-safe.gif</qr_short> 
qr_longURL of the QR code for the long link<qr_long>http://safe.mn/static/images/qr/1.gif</qr_long> 

text

Fields are separated by a line break \n.

ParameterMeaningPossible valueComment
urlLong URLurl: http://www.reviews-web-hosting.com/ 
clicksNumber of clicks for the short linkclicks: 1201Integer
referersNumber of clicks per original domainreferers: "Direct Access/Applications": 1151 "baidu.com": 2 
countriesNumber of clicks per countrycountries: "United States": 851 "China": 94 
filetypePotentially dangerous file typefiletype: application/x-dosexecEmpty if safe
virusVirus namevirus: Eicar-Test-SignatureEmpty if no virus
dangerousKnown dangerous sitedangerous: Spyware/Malware/AdwareEmpty if safe
partialPartial downloadpartial: 10 if download is complete
unreachablePage is unreachableunreachable: 10 if page is reachable
activexDangerous ActiveX nameactivex: 00000000-0000-0000-0000-000000000000 CnBabe AdwareEmpty if safe
xssCross-Site Scriptingxss: 10 if URL is safe
categoryContent categorycategory: AdultEmpty if safe
redirectionToo many redirectionsredirection: 10 if not too many redirections
errorAn error occurrederror: Invalid URLNo error field if successful
qr_shortURL of the QR code for the short linkhttp://safe.m/static/images/qr/1-safe.gif 
qr_longURL of the QR code for the long linkhttp://safe.mn/static/images/qr/1.gif 

Examples

Successful:

http://safe.mn/api/info?url=http://safe.mn/1&format=xml
<?xml version='1.0' ?>
<data>
 <activex></activex>
 <category></category>
 <clicks>1246</clicks>
 <countries>
 <country name="United States" clicks="851" />
 <country name="China" clicks="94" />
 <country name="Romania" clicks="53" />
 <country name="Russian Federation" clicks="46" />
 <country name="Japan" clicks="32" />
 <country name="Germany" clicks="24" />
 <country name="Taiwan" clicks="23" />
 <country name="Netherlands" clicks="20" />
[...]
 </countries>
 <download></download>
 <filetype></filetype>
 <google></google>
 <redirection></redirection>
 <referers>
 <referer clicks="1151" domain="Direct Access/Applications" />
 <referer clicks="73" domain="safe.mn" />
 <referer clicks="2" domain="192.168.1.75" />
 <referer clicks="2" domain="win.mail.ru" />
 <referer clicks="2" domain="baidu.com" />
 <referer clicks="1" domain="znatok.biz" />
 <referer clicks="1" domain="digifur.com" />
 <referer clicks="1" domain="www.ipark.cn" />
[...]
 </referers>
 <unreachable>0</unreachable>
 <url>http://www.amazon.com/gp/product/1430224258/ref=s9_intb_gw_i1?pf_rd_m=ATVPDKIKX0DER
&pf_rd_s=center-2&pf_rd_r=10DQS8RKGF8F4G84WJBD&pf_rd_t=101&pf_rd_p=470938631
&pf_rd_i=507846</url>
 <virus></virus>
 <xss></xss>
 <qr_short>http://safe.mn/static/images/qr/1-safe.gif</qr_short>
 <qr_long>http://safe.mn/static/images/qr/1.gif</qr_long>
</data>

Error:

http://go2.gs/api/info?url=foo&format=json
{"error":"Invalid URL"}

Top