Application Programming Interface

Urlms.com provides a fairly basic API (Application Programming Interface) which can be used in order for other applications to harness our URL shortening service. This works by accessing a particular URL on the urlms.com site which accepts the long URL you would like shortened as a parameter. The shortened URL (or various error conditions as appropriate) will then be returned.


Using the API with PHP


/*
$url -> The URL you want shortened
$custom -> Your custom pointer. E.g: (http://urlms.com/my_own_pointer)
$preview -> Value: yes
*/

function Shortify($url, $custom = false, $preview = false) {

      $post  = "url=" . rawurlencode($url);
      $post .= ($custom) ? "&pointer=" . rawurlencode($custom) : '';
      $post .= ($preview) ? "&preview=" . $preview : '';

      $api = "http://api.urlms.com/";

      $session = curl_init($api);
      curl_setopt($session, CURLOPT_URL, $api);
      curl_setopt($session, CURLOPT_HEADER, 0);
      curl_setopt($session, CURLOPT_POST, 1);
      curl_setopt($session, CURLOPT_POSTFIELDS, $post);
      curl_setopt($session, CURLOPT_FOLLOWLOCATION, 0);
      curl_setopt($session, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($session, CURLOPT_USERAGENT, "Urlms.com API");
      $data = curl_exec($session);
      curl_close($session);
      return $data;
}


Using the API with ColdFusion


<!--- Code by Barney Boisvert [barneyb.com] --->

<cffunction name="shortify" output="false" returntype="string">
      <cfargument name="srcUrl" type="string" required="true" />
      <cfargument name="custom" type="string" default="" />
      <cfargument name="preview" type="boolean" default="false" />
      <cfset var cfhttp = "" />
      <cfset var xml = "" />
      <cfhttp url="http://api.urlms.com/"
            method="post"
            result="cfhttp">
            <cfhttpparam type="formfield" name="url" value="#srcUrl#" />
                  <cfif len(trim(custom)) GT 0>
                  <cfhttpparam type="formfield" name="pointer" value="#trim(custom)#" />
            </cfif>
            <cfif preview>
                  <cfhttpparam type="formfield" name="preview" value="true" />
            </cfif>
      </cfhttp>
      <cfreturn cfhttp.fileContent />
</cffunction>


Receiving the shortened URL


After submitting the URL you would like shortened (for any code above), assuming the request was successful, you'll get an XML response containing the original URL and the short version.


Example:


<?xml version="1.0" encoding="UTF-8"?>
<link>
      <url>http://members.your-hosting-provider.com/~username/</url>
      <permalink>http://urlms.com/SdH</permalink>
</link>


Possible errors


If the request was unsuccessful, the body of the response (XML) will contain a specific error message giving the reason, which may be any of the following:



Example:


<?xml version="1.0" encoding="UTF-8"?>
<link>
      <error>The URL you entered is not a valid URL</error>
</link>


Please, be polite...


Use good judgment when designing your application. Don't make repeated requests for the same data frequently. We monitor API usage, and we may block applications that do silly things. Use good judgment to keep your application running smoothly!


Terms


Please visit our "Terms" section for more information about the usage of this service.